Create, read, update, and delete email inboxes. Manage inbox settings, aliases, and routing rules.

Inbox Management

The Inbox API allows you to programmatically manage email inboxes for receiving and organizing messages.

Overview

Inboxes are the primary containers for receiving emails. Each inbox has:

A unique email address (e.g., support@yourdomain.com)
Configurable routing rules
Message threading capabilities
Webhook integration support

Base URL

/api/email/inboxes

Endpoints

List Inboxes

Retrieve all inboxes for the authenticated organization.

GET /api/email/inboxes

Query Parameters:

Parameter	Type	Description
`domain`	string	Filter by domain ID
`status`	string	Filter by status: `active`, `paused`
`limit`	number	Number of results (default: 20)
`offset`	number	Pagination offset

Response:

{
  "inboxes": [
    {
      "id": "inb_123456789",
      "email": "support@yourdomain.com",
      "domainId": "dom_987654321",
      "status": "active",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z",
      "messageCount": 42,
      "unreadCount": 5
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

Create Inbox

Create a new inbox for receiving emails.

POST /api/email/inboxes

Request Body:

{
  "email": "support@yourdomain.com",
  "domainId": "dom_987654321",
  "webhookUrl": "https://yourapp.com/webhooks/email",
  "forwardTo": ["admin@yourdomain.com"],
  "autoReply": {
    "enabled": true,
    "subject": "Thank you for contacting us",
    "body": "We have received your message and will respond within 24 hours."
  }
}

Response:

{
  "id": "inb_123456789",
  "email": "support@yourdomain.com",
  "domainId": "dom_987654321",
  "status": "active",
  "webhookUrl": "https://yourapp.com/webhooks/email",
  "forwardTo": ["admin@yourdomain.com"],
  "autoReply": {
    "enabled": true,
    "subject": "Thank you for contacting us",
    "body": "We have received your message and will respond within 24 hours."
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Get Inbox

Retrieve a specific inbox by ID.

GET /api/email/inboxes/:id

Response:

{
  "id": "inb_123456789",
  "email": "support@yourdomain.com",
  "domainId": "dom_987654321",
  "status": "active",
  "webhookUrl": "https://yourapp.com/webhooks/email",
  "forwardTo": ["admin@yourdomain.com"],
  "autoReply": {
    "enabled": true,
    "subject": "Thank you for contacting us",
    "body": "We have received your message and will respond within 24 hours."
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
  "stats": {
    "totalMessages": 42,
    "unreadMessages": 5,
    "totalThreads": 18
  }
}

Update Inbox

Update an existing inbox configuration.

PATCH /api/email/inboxes/:id

Request Body:

{
  "status": "paused",
  "webhookUrl": "https://yourapp.com/webhooks/email-updated",
  "forwardTo": ["admin@yourdomain.com", "support@yourdomain.com"],
  "autoReply": {
    "enabled": false
  }
}

Response:

{
  "id": "inb_123456789",
  "email": "support@yourdomain.com",
  "domainId": "dom_987654321",
  "status": "paused",
  "webhookUrl": "https://yourapp.com/webhooks/email-updated",
  "forwardTo": ["admin@yourdomain.com", "support@yourdomain.com"],
  "autoReply": {
    "enabled": false
  },
  "updatedAt": "2024-01-15T11:00:00Z"
}

Delete Inbox

Permanently delete an inbox and all associated messages.

DELETE /api/email/inboxes/:id

Response:

{
  "success": true,
  "message": "Inbox deleted successfully",
  "deletedAt": "2024-01-15T11:30:00Z"
}

Code Examples

JavaScript/TypeScript

import { createInbox, listInboxes } from '@repo/email-sdk';

// Create a new inbox
const inbox = await createInbox({
  email: 'support@yourdomain.com',
  domainId: 'dom_987654321',
  webhookUrl: 'https://yourapp.com/webhooks/email'
});

// List all inboxes
const { inboxes } = await listInboxes({
  status: 'active',
  limit: 10
});

cURL

# Create inbox
curl -X POST https://api.yourapp.com/api/email/inboxes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "support@yourdomain.com",
    "domainId": "dom_987654321"
  }'

# List inboxes
curl -X GET "https://api.yourapp.com/api/email/inboxes?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Error Codes

Code	Description
`INBOX_NOT_FOUND`	The requested inbox does not exist
`DOMAIN_NOT_VERIFIED`	Cannot create inbox on unverified domain
`EMAIL_EXISTS`	Email address already in use
`INVALID_EMAIL`	Email format is invalid
`RATE_LIMIT_EXCEEDED`	Too many requests

Threads - Manage email threads and messages
Domains - Configure custom domains
Webhooks - Real-time email notifications

Inbox Management

On this page