Mailboxes

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

The mailbox object

{
  "object": "mailbox",
  "id": "mbx_abc123",
  "domain_id": "dom_abc123",
  "address": "hello@example.com",
  "display_name": "Hello",
  "suspended_at": null,
  "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.

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.