Mailboxes

Mailboxes let your tenant receive inbound email at dedicated addresses. Each mailbox is scoped to a single tenant and can be used to receive and process incoming messages.

Plan limits

The number of mailboxes you can create depends on your plan:

When your account is in the expired state, no new mailboxes can be created.

Creating a mailbox

Mailboxes are created via the agentic mailbox API:

curl -X POST https://api.molted.email/v1/agent/mailboxes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "tenant-abc",
    "address": "support@example.com",
    "displayName": "Support Inbox"
  }'

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenantId": "tenant-abc",
  "address": "support@example.com",
  "displayName": "Support Inbox",
  "status": "provisioning",
  "config": {},
  "createdAt": "2026-03-01T12:00:00Z",
  "updatedAt": "2026-03-01T12:00:00Z"
}

Limit exceeded

If you attempt to create a mailbox beyond your plan's limit, you'll receive a 403 Forbidden response:

{
  "statusCode": 403,
  "message": "Mailbox limit reached (3). Upgrade your plan to create more mailboxes."
}

Mailbox status

Each mailbox has a status field:

Updating a mailbox

Use PATCH /v1/agent/mailboxes/:id to update mailbox properties:

molted mailboxes update MAILBOX_ID --display-name "New Display Name"

curl -X PATCH https://api.molted.email/v1/agent/mailboxes/MAILBOX_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "New Display Name"
  }'

Update fields

Mailbox config schema

The config field is a JSON object for per-mailbox settings. All fields are optional on update -- you only need to include the fields you want to change.

molted mailboxes update MAILBOX_ID --config '{"inboundRateLimit": 120}'

molted mailboxes update MAILBOX_ID --config '{"pausedAutoReply": "We are currently unavailable. We will respond shortly."}'

curl -X PATCH https://api.molted.email/v1/agent/mailboxes/MAILBOX_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "inboundRateLimit": 120,
      "pausedAutoReply": "We are currently unavailable."
    }
  }'

Changing the email address

You can change a mailbox's email address if it is on a custom domain. Shared domain mailboxes (agent.molted.email) cannot have their address changed.

The new address must be on a verified custom domain owned by the tenant.

curl -X PATCH https://api.molted.email/v1/agent/mailboxes/MAILBOX_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "new-address@yourdomain.com"
  }'

Restrictions:

• Shared domain mailboxes cannot change their address
• The new address must be on a verified custom domain
• The new address must be unique within the tenant
• Changing address affects deliverability since the new address has no sending reputation

Cloning a mailbox

You can clone an existing mailbox to create a new one with the same settings. This is useful when you want to set up a new mailbox with the same autonomy level, safety mitigations, humanizer configuration, rules, and folders as an existing one.

What gets copied

• Autonomy level (L1/L2/L3)
• Config (safety mitigations, humanizer style, reply-to, signature)
• Custom rules (with folder references remapped to the cloned folders)
• Custom folders (empty - threads are not copied)

What does not get copied

• Threads and sending history
• Catch-all setting (only one mailbox per domain can be catch-all)
• Email address and display name (you provide new ones)

Via API

curl -X POST https://api.molted.email/v1/agent/mailboxes/MAILBOX_ID/clone \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "sales@example.com",
    "displayName": "Sales Inbox"
  }'

The response is the newly created mailbox object, identical to the response from creating a mailbox.

Via portal

In the portal, open the mailbox settings page and find the Duplicate Mailbox section. Click Duplicate, enter the new email address and optional display name, then confirm. You will be redirected to the new mailbox's settings page.

Guards

• Requires admin scope. Only API keys with the admin scope can clone mailboxes.
• Plan limits apply. The clone counts against your mailbox quota just like creating a new mailbox.
• Address must be unique. The new address must not already exist for your tenant.

Pausing and resuming

You can pause a mailbox to temporarily stop all outbound sending. This is useful during incidents, migrations, or while investigating deliverability issues.

Via API

curl -X PATCH https://api.molted.email/v1/agent/mailboxes/MAILBOX_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "paused"
  }'

curl -X PATCH https://api.molted.email/v1/agent/mailboxes/MAILBOX_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "active"
  }'

Via portal

In the portal, open the mailbox settings page and use the Sending Status toggle at the top. Pausing requires confirmation. Paused mailboxes show a "PAUSED" badge in the sidebar.

What happens when a mailbox is paused

• Outbound emails are blocked. Any send attempt returns a mailbox_paused block reason.
• Queued and scheduled messages are held, not dropped. They will be sent once the mailbox is resumed.
• Inbound messages continue to be received and stored normally.
• Paused mailboxes do not count against rate limits.
• Mailboxes can also be auto-paused by the reputation system if bounce or complaint rates exceed thresholds.

Deleting a mailbox

Mailboxes can be deleted via the API or the portal. Deletion is a soft-delete -- the mailbox is marked as deleted and filtered out of all queries.

Via API

curl -X DELETE https://api.molted.email/v1/agent/mailboxes/MAILBOX_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

A successful deletion returns:

{
  "deleted": true
}

Via portal

In the portal, open the mailbox settings page and scroll to the Danger Zone section at the bottom. Click Delete Mailbox and type delete to confirm.

What happens when a mailbox is deleted

• All threads are trashed. Existing threads belonging to the mailbox are moved to trash.
• Rules, folders, and reputation data are preserved in the database but become inaccessible.
• API key scopes referencing the deleted mailbox are removed via cascade.
• Send history is preserved -- the mailbox_id on send requests and inbound messages is set to NULL.
• The mailbox no longer appears in list or get queries.

Guards

• You cannot delete the last mailbox. Every tenant must have at least one active mailbox. Create another mailbox first if you need to delete the current one.
• Requires admin scope. Only API keys with the admin scope can delete mailboxes.

Listing mailboxes

molted mailboxes list

curl https://api.molted.email/v1/agent/mailboxes?tenantId=tenant-abc \
  -H "Authorization: Bearer YOUR_API_KEY"

Mailbox statistics

Get per-mailbox usage statistics including send volume, deliverability metrics, and inbound counts.

curl https://api.molted.email/v1/agent/mailboxes/MAILBOX_ID/stats?period=7d \
  -H "Authorization: Bearer YOUR_API_KEY"

Query parameters

Response

{
  "mailboxId": "550e8400-e29b-41d4-a716-446655440000",
  "period": "7d",
  "sends": {
    "total": 1250,
    "period": 342
  },
  "inbound": {
    "period": 87
  },
  "deliverability": {
    "delivered": 330,
    "bounced": 8,
    "complained": 1,
    "opened": 210,
    "clicked": 45,
    "deliveryRate": 0.973,
    "bounceRate": 0.024,
    "complaintRate": 0.003,
    "openRate": 0.614,
    "clickRate": 0.132
  },
  "suppressionCount": 12,
  "lastSendAt": "2026-03-31T14:22:00Z",
  "dailySends": [
    { "day": "2026-03-25", "count": 48 },
    { "day": "2026-03-26", "count": 52 },
    { "day": "2026-03-27", "count": 41 }
  ]
}

The stats are computed from existing send and delivery data. The dailySends array provides data for charting send volume over the selected period.

Checking your usage

Mailbox usage is included in the billing status endpoint:

curl https://api.molted.email/v1/billing/status \
  -H "Authorization: Bearer YOUR_API_KEY"

The response includes a mailboxes field:

{
  "mailboxes": {
    "used": 2,
    "limit": 3
  }
}

A null limit means unlimited mailboxes (Enterprise plan).