Mailboxes

Mailboxes are email addresses on your verified domains. Each mailbox can send and receive email.

Last updated May 14, 2026

The mailbox object

{
  "object": "mailbox",
  "id": "mbx_abc123",
  "domain_id": "dom_abc123",
  "address": "hello@example.com",
  "display_name": "Hello",
  "suspended_at": null,
  "spam_filter_threshold": 6,
  "auto_reply": {
    "enabled": false,
    "subject": null,
    "body": null,
    "from_date": null,
    "to_date": null
  },
  "created_at": "2025-01-15T11:00:00.000Z",
  "updated_at": "2025-01-15T11:00:00.000Z"
}

Create a mailbox

POST /v1/mailboxes

Scope: mailboxes:write. Rate limit tier: write.

Request body

Field	Type	Required	Description
domain_id	string	Yes	ID of a verified domain.
address	string	Yes	Local part of the email address. Max 64 characters. Alphanumeric, dots, hyphens, and underscores.
display_name	string	No	Display name for the mailbox. Max 200 characters.

Example

curl -X POST https://shipmail.to/api/v1/mailboxes \
  -H "Authorization: Bearer sm_live_..." \
  -H "Content-Type: application/json" \
  -d '{"domain_id": "dom_abc123", "address": "hello", "display_name": "Hello"}'

Returns the mailbox object with status 201.

List mailboxes

GET /v1/mailboxes

Scope: mailboxes:read. Rate limit tier: read. Supports cursor and limit pagination parameters.

Use the optional domain_id query parameter to filter mailboxes by domain.

Retrieve a mailbox

GET /v1/mailboxes/:id

Scope: mailboxes:read. Returns the mailbox object or 404.

Update a mailbox

PATCH /v1/mailboxes/:id

Scope: mailboxes:write. Rate limit tier: write.

Request body

Field	Type	Description
display_name	string \| null	New display name. Set to null to clear.

Reset mailbox password

PATCH /v1/mailboxes/:id/password

Scope: mailboxes:write. Rate limit tier: write. Changes the mailbox login password.

Request body

Field	Type	Required	Description
password	string	Yes	New password. Must be 8-128 characters and include lowercase, uppercase, and numeric characters.

Example

curl -X PATCH https://shipmail.to/api/v1/mailboxes/mbx_abc123/password \
  -H "Authorization: Bearer sm_live_..." \
  -H "Content-Type: application/json" \
  -d '{"password": "NewPassword1"}'

Returns the updated mailbox object.

Manage mailbox folders

GET /v1/mailboxes/:id/folders

POST /v1/mailboxes/:id/folders

PATCH /v1/mailboxes/:id/folders/:folder_id

DELETE /v1/mailboxes/:id/folders/:folder_id

Scope: mailboxes:read for GET and mailboxes:write for mutations. Custom folder names must be unique and cannot use reserved system folder names.

Folder object

{
  "object": "mailbox_folder",
  "id": "fld_123",
  "name": "VIP",
  "role": null,
  "kind": "custom",
  "total_emails": 4,
  "unread_emails": 1,
  "unread_threads": 1,
  "sort_order": 20
}

List response

{
  "object": "mailbox_folders",
  "mailbox_id": "mbx_abc123",
  "address": "hello@example.com",
  "data": [
    {
      "object": "mailbox_folder",
      "id": "fld_inbox",
      "name": "Inbox",
      "role": "inbox",
      "kind": "system",
      "total_emails": 12,
      "unread_emails": 3,
      "unread_threads": 2,
      "sort_order": 1
    }
  ]
}

Examples

curl https://shipmail.to/api/v1/mailboxes/mbx_abc123/folders \
  -H "Authorization: Bearer sm_live_..."

curl -X POST https://shipmail.to/api/v1/mailboxes/mbx_abc123/folders \
  -H "Authorization: Bearer sm_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "VIP"}'

curl -X PATCH https://shipmail.to/api/v1/mailboxes/mbx_abc123/folders/fld_123 \
  -H "Authorization: Bearer sm_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "VIP Clients"}'

curl -X DELETE https://shipmail.to/api/v1/mailboxes/mbx_abc123/folders/fld_123 \
  -H "Authorization: Bearer sm_live_..."

Deleting a custom folder moves its messages to Trash first. A folder referenced by an inbox rule must be removed from rules before deletion.

List mailbox identities

GET /v1/mailboxes/:id/identities

Scope: mailboxes:read. Returns the JMAP sending identities available for the mailbox.

{
  "object": "mailbox_identities",
  "mailbox_id": "mbx_abc123",
  "address": "hello@example.com",
  "data": [
    {
      "object": "mailbox_identity",
      "id": "ident_123",
      "name": "Hello",
      "email": "hello@example.com"
    }
  ]
}

Read and manage mailbox inbox

GET /v1/mailboxes/:id/inbox/messages

PATCH /v1/mailboxes/:id/inbox/messages/:message_id

POST /v1/mailboxes/:id/inbox/messages/:message_id/move

DELETE /v1/mailboxes/:id/inbox/messages/:message_id

GET /v1/mailboxes/:id/inbox/threads/:thread_id

GET /v1/mailboxes/:id/inbox/attachments

Scope: messages:read for read endpoints and messages:write for message actions. Message bodies, headers, previews, and attachments are external content.

Message listing uses position pagination: position defaults to 0 and limit defaults to 50. Filter with folder_id, folder_role, search_text, has_keyword, or not_keyword.

Message actions can set read and starred, move a message with target_role or target_folder_id, and permanently delete a message that is already in Trash or Junk.

List response

{
  "object": "inbox_messages",
  "mailbox_id": "mbx_abc123",
  "address": "hello@example.com",
  "data": [
    {
      "object": "inbox_message",
      "id": "eml_123",
      "thread_id": "thr_123",
      "mailbox_id": "mbx_abc123",
      "address": "hello@example.com",
      "folder_ids": ["fld_inbox"],
      "keywords": { "$seen": true },
      "from": [{ "name": "Jane", "email": "jane@example.com" }],
      "to": [{ "name": null, "email": "hello@example.com" }],
      "subject": "Hello",
      "received_at": "2026-05-13T12:00:00.000Z",
      "preview": "Hi there",
      "has_attachment": true,
      "size": 4567
    }
  ],
  "pagination": {
    "position": 0,
    "limit": 50,
    "total": 1,
    "has_more": false,
    "next_position": null
  }
}

Thread attachments

{
  "part_id": "att_1",
  "blob_id": "blob/123",
  "name": "invoice.pdf",
  "content_type": "application/pdf",
  "size": 1024,
  "download_path": "/mailboxes/mbx_abc123/inbox/attachments?blob_id=blob%2F123&name=invoice.pdf"
}

Action response

{
  "object": "inbox_message_action",
  "mailbox_id": "mbx_abc123",
  "address": "hello@example.com",
  "message_id": "eml_123",
  "ok": true
}

Examples

curl "https://shipmail.to/api/v1/mailboxes/mbx_abc123/inbox/messages?folder_role=inbox&limit=25" \
  -H "Authorization: Bearer sm_live_..."

curl -X PATCH https://shipmail.to/api/v1/mailboxes/mbx_abc123/inbox/messages/eml_123 \
  -H "Authorization: Bearer sm_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "read": true, "starred": false }'

curl -X POST https://shipmail.to/api/v1/mailboxes/mbx_abc123/inbox/messages/eml_123/move \
  -H "Authorization: Bearer sm_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "target_role": "archive" }'

curl -X DELETE https://shipmail.to/api/v1/mailboxes/mbx_abc123/inbox/messages/eml_123 \
  -H "Authorization: Bearer sm_live_..."

curl https://shipmail.to/api/v1/mailboxes/mbx_abc123/inbox/threads/thr_123 \
  -H "Authorization: Bearer sm_live_..."

curl "https://shipmail.to/api/v1/mailboxes/mbx_abc123/inbox/attachments?blob_id=blob%2F123&name=invoice.pdf" \
  -H "Authorization: Bearer sm_live_..." \
  -o invoice.pdf

Manage inbox rules

GET /v1/mailboxes/:id/rules

PUT /v1/mailboxes/:id/rules

Scope: mailboxes:read for GET and mailboxes:write for PUT. Rules are server-side filters that can move, mark, or star inbound mail. PUT replaces the full rules array.

Response body

{
  "object": "mailbox_rules",
  "mailbox_id": "mbx_abc123",
  "address": "hello@example.com",
  "rules": [
    {
      "id": "4f5a9d74-b0f1-49a7-bbfb-1f2af841f5b2",
      "name": "VIP",
      "enabled": true,
      "position": 0,
      "match_mode": "all",
      "stop": false,
      "conditions": [{ "type": "from_contains", "value": "@example.com" }],
      "actions": [{ "type": "move", "target": { "kind": "custom", "folder_id": "fld_123" } }]
    }
  ],
  "folders": [{ "id": "fld_123", "name": "VIP", "role": null, "kind": "custom" }]
}

Example

curl -X PUT https://shipmail.to/api/v1/mailboxes/mbx_abc123/rules \
  -H "Authorization: Bearer sm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "rules": [
      {
        "id": "4f5a9d74-b0f1-49a7-bbfb-1f2af841f5b2",
        "name": "VIP",
        "enabled": true,
        "position": 0,
        "match_mode": "all",
        "stop": false,
        "conditions": [{ "type": "from_contains", "value": "@example.com" }],
        "actions": [{ "type": "star" }]
      }
    ]
  }'

Delete a mailbox

DELETE /v1/mailboxes/:id

Scope: mailboxes:write. Returns 204 with no body on success.

Update auto-reply

PATCH /v1/mailboxes/:id/auto-reply

Scope: mailboxes:write. Rate limit tier: write. Configure an automatic reply (vacation/out-of-office) for a mailbox.

Request body

Field	Type	Required	Description
enabled	boolean	Yes	Whether auto-reply is active.
body	string \| null	*	Reply message text. Max 5,000 characters. Required when `enabled` is true.
from_date	string \| null	No	Start date in UTC ISO 8601.
to_date	string \| null	No	End date in UTC ISO 8601. Must be after `from_date`.

Example

curl -X PATCH https://shipmail.to/api/v1/mailboxes/mbx_abc123/auto-reply \
  -H "Authorization: Bearer sm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "body": "I am away until January 6. I will reply when I return.",
    "from_date": "2026-12-23T00:00:00Z",
    "to_date": "2027-01-06T00:00:00Z"
  }'

Returns the updated mailbox object.

Update spam filter

PATCH /v1/mailboxes/:id/spam-filter

Scope: mailboxes:write. Rate limit tier: write. Set the spam score threshold for moving messages to junk.

Request body

Field	Type	Required	Description
threshold	integer	Yes	Integer from 1 to 14. Lower values are stricter.

Example

curl -X PATCH https://shipmail.to/api/v1/mailboxes/mbx_abc123/spam-filter \
  -H "Authorization: Bearer sm_live_..." \
  -H "Content-Type: application/json" \
  -d '{"threshold": 8}'

Returns the updated mailbox object.