Skip to content

ResourcesMailboxes

Mailboxes API

A mailbox is an email address on one of your verified domains, like hello@example.com. This page covers creating, listing, updating, suspending, securing, deleting, exporting and importing them. To read a mailbox's mail, see Mailbox inbox. For forwarding, out of office and delivery routing, see Mail handling.

Last updated

The mailbox object

{
  "object": "mailbox",
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "domain_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "address": "hello@example.com",
  "display_name": "Hello",
  "suspended_at": null,
  "suspension_reasons": [],
  "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"
}

The mailbox ID is the id field. Pass it to the mailbox endpoints for messages, inbox threads, folders, identities, and rules. When you send, the from field takes either this ID or the mailbox's address.

Create a mailbox

POST/v1/mailboxesscope mailboxes:writetier write

Request body

FieldTypeRequiredDescription
domain_idstringYesID of a verified domain.
addressstringYesLocal part of the email address. Max 64 characters. Alphanumeric, dots, hyphens, and underscores.
passwordstringOne ofFirst mailbox password. 8 to 128 characters. Common passwords are rejected. The API never returns it. Also needs the mailbox_credentials:write scope.
generate_passwordbooleanOne ofSet to true to have the server generate the primary password. It is never returned.
display_namestringNoDisplay name for the mailbox. Max 128 characters.

Example

curl -X POST https://shipmail.to/api/v1/mailboxes \
  -H "Authorization: Bearer sm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "domain_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "address": "hello",
    "display_name": "Hello",
    "password": "UniqueSecret123"
  }'

Returns the mailbox object with status 201. Send exactly one of password or generate_password: true. A generated password is never returned. Whoever runs the mailbox can set their own password later.

Setting password needs both mailboxes:write and mailbox_credentials:write. API keys created before 2026-09-29 can still set it with mailboxes:write alone. Those responses carry Deprecation and Sunset headers. The exception ends on 2027-09-29 at the earliest, so add mailbox_credentials:write to those keys now.

List mailboxes

GET/v1/mailboxes

Scope: mailboxes:read. Rate limit tier: read. Page with cursor and limit.

Add domain_id to list only the mailboxes on one domain.

Find a mailbox ID

Call this endpoint and copy the id for the mailbox address you want.

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

{
  "data": [
    {
      "object": "mailbox",
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "address": "hello@example.com"
    }
  ]
}

Retrieve a mailbox

GET/v1/mailboxes/:id

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

Update a mailbox

PATCH/v1/mailboxes/:idscope mailboxes:writetier write

Request body

FieldTypeDescription
display_namestring | nullNew display name. Set to null to clear.
agent_security_holdbooleanHolds content from API agents for review. Off by default. Turning it on or off also needs messages:review.

Suspend or resume a mailbox

POST/v1/mailboxes/:id/suspend
POST/v1/mailboxes/:id/resume

Scope: mailboxes:write. Suspend adds a manual reason. The mailbox then can't log in, send, receive, run inbox rules, or run AI assistant automations. Resume removes only the manual reason. A billing, security, or abuse reason stays until it is cleared on its own.

The returned mailbox includes suspended_at and suspension_reasons. You can safely send either request twice.

curl -X POST https://shipmail.to/api/v1/mailboxes/f47ac10b-58cc-4372-a567-0e02b2c3d479/suspend \
  -H "Authorization: Bearer sm_live_..."

Reset mailbox password

PATCH/v1/mailboxes/:id/password

Scope: mailbox_credentials:write. Rate limit tier: write. Changes the mailbox login password. The key must act for an Owner or Admin who can read the mailbox, or for the mailbox's own sign-in principal. Only the Owner can reset a mailbox that receives an Owner login address. API keys created before 2026-09-29 can still call it with mailboxes:write alone. Those responses carry Deprecation and Sunset headers. The exception ends on 2027-09-29 at the earliest, so add mailbox_credentials:write to those keys now.

Request body

FieldTypeRequiredDescription
passwordstringYesNew password. 8 to 128 characters, with at least one lowercase letter, one uppercase letter, and one digit.

Example

curl -X PATCH https://shipmail.to/api/v1/mailboxes/f47ac10b-58cc-4372-a567-0e02b2c3d479/password \
  -H "Authorization: Bearer sm_live_..." \
  -H "Content-Type: application/json" \
  -d '{"password": "NewPassword1"}'

Returns the updated mailbox object.

App passwords

GET/v1/mailboxes/:id/app-passwords
POST/v1/mailboxes/:id/app-passwords
DELETE/v1/mailboxes/:id/app-passwords/:app_password_id

Give each IMAP, SMTP, JMAP, or embedded client its own app password, so you never share the mailbox's main password. Listing needs mailbox_credentials:read. Creating and revoking need mailbox_credentials:write. An app password reads and sends mail but cannot manage the mailbox's Sieve scripts.

A mailbox can have 5 active app passwords. Each expires after 90 days unless you pick another date, up to one year. You can limit one to 20 IPv4 or IPv6 CIDR ranges. The create response shows the plaintext secret once, so save it. Shipmail doesn't store it, and the list never returns it.

Create request

{"name":"Desktop mail","expires_at":"2026-10-01T00:00:00.000Z","allowed_cidrs":["203.0.113.0/24"]}

One-time response

{"object":"mailbox_app_password","id":"appwd_...","mailbox_id":"f47ac10b-58cc-4372-a567-0e02b2c3d479","name":"Desktop mail","state":"active","purpose":"operator_client","expires_at":"2026-10-01T00:00:00.000Z","allowed_cidrs":["203.0.113.0/24"],"last_used_at":null,"created_at":"2026-07-15T00:00:00.000Z","revoked_at":null,"secret":"save-this-now"}

Delete a mailbox

DELETE/v1/mailboxes/:id

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

Returns 422 while something still uses the mailbox: an active application sender that sends its replies there, delivery routing that sends mail there, or a newsletter sending domain. The error message names it. Remove it, then delete again. Returns 409 while the mailbox is being archived or deleted, or while its organization is being deleted or changing owners.

Exports

POST /mailboxes/{id}/exports builds a private ZIP of the mailbox. It holds the messages as EML, the folder layout, calendar ICS objects, contact VCards, a manifest, and checksums. Scope: mailboxes:export. Send an Idempotency-Key when you retry.

For a live mailbox, it returns 202 and a background worker builds the ZIP. For an archived mailbox, it returns 201 and reuses the exact current-format snapshot saved when billing archived it. The mailbox is not restored. A suspended mailbox must be resumed first.

Calling again is cheap. If the mailbox has a finished export less than 15 minutes old, you get that one back with 200, and nothing new is built.

A mailbox can make 24 exports in any 24 hours. After that you get 429, with a Retry-After header that says how many seconds to wait. Reused exports and exports already running don't count. See rate limits.

Read status and download

GET /mailboxes/{id}/exports/{export_id} returns pending, processing, completed, failed, or expired. A completed export has a private download_url that works for five minutes at most. The export record expires after seven days. The failure codes are source_unavailable, snapshot_changed, and export_failed.

Instead of polling, subscribe to mailbox.export.completed and mailbox.export.failed. Both carry the same export object this endpoint returns. Its download_url works for up to six hours after the event was created. After download_url_expires_at, call GET /mailboxes/{id}/exports/{export_id} for a fresh link. Subscriptions cover the whole organization, so your endpoint gets these events for every mailbox in it. See webhooks.

Imports

Move mail from another provider, like Gmail or Yahoo, into a mailbox. Imports run in the background and keep folders, read state, and dates. They skip messages already imported, so you can run one again. See the mailbox import docs for details.

Start an import

POST /mailboxes/{id}/imports. Scope: mailboxes:write. Tier: write.

curl -X POST https://shipmail.to/api/v1/mailboxes/f47ac10b-58cc-4372-a567-0e02b2c3d479/imports \
  -H "Authorization: Bearer sm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "type": "imap",
      "provider": "gmail",
      "email": "you@gmail.com",
      "password": "your-app-password"
    },
    "options": { "range": "12m" }
  }'

The source is either an IMAP connection or staged files with { "type": "files", "provider": "takeout", "file_ids": ["impf_..."] }. The IMAP providers are gmail, yahoo, aol, icloud, fastmail, zoho, titan, namecheap, migadu, purelymail, gmx, mail_com, mailbox_org, mxroute, infomaniak, ovh, gandi, and imap. Use the provider's app, device, or mailbox password. Titan and OVHcloud let you override the server. MXroute and custom IMAP need a host. For Outlook, use Sign in with Microsoft in the dashboard. Returns the import object (201), or 409 if this mailbox already has an import running. Shipmail encrypts the credentials, uses them only for this import, and deletes them when it finishes.

Upload an export file

POST /mailboxes/{id}/imports/files with { "provider": "takeout", "file_name": "takeout.zip", "size_bytes": 1048576, "source_fingerprint": "<sha256>" }. The fingerprint is a lowercase SHA-256 that identifies your local file. You get back file_id, part_size_bytes, the completed_parts already uploaded, and fresh presigned URLs for the missing parts. Split the file at that part size and PUT each raw part to its URL. Keep the ETag header from each response, then send all part numbers and ETags to POST /mailboxes/{id}/imports/files/{file_id}/complete. Accepted: .mbox, .mbox.gz, .zip, .eml, plus .vcf for Google Takeout, up to 100 GB per file. A file import always moves the whole archive, spam and trash included. A Takeout ZIP also imports the contacts inside it. To resume an interrupted upload, repeat the same POST with the same fingerprint, and skip the completed_parts it returns. Upload sessions expire after six days. A finished file that no import uses is deleted after 24 hours. To abort an unfinished upload, DELETE the file URL.

{
  "object": "import_upload",
  "file_id": "impf_abc123",
  "part_size_bytes": 33554432,
  "completed_parts": [],
  "parts": [
    { "part_number": 1, "upload_url": "https://storage.example/...?partNumber=1" }
  ],
  "expires_in_seconds": 518400
}

Track progress

GET /mailboxes/{id}/imports lists recent imports. GET /mailboxes/{id}/imports/{import_id} returns one import with live counters and the per-folder report. status values: queued, running, paused_throttle (the source provider's daily download limit was hit; it resumes by itself), paused_quota (mailbox storage full), completed, failed, cancelled, undo_queued, undoing, undone, undo_failed.

Each folder in the report carries a state: pending, importing, completed, failed, or skipped. skipped means the source server refused the folder. The import finished without it, and the folder's error says why.

Cancel an import

POST /mailboxes/{id}/imports/{import_id}/cancel. Mail already imported stays in the mailbox. Uploaded files are kept for 7 days, along with how far the import got.

Resume an uploaded import

POST /mailboxes/{id}/imports/{import_id}/resume. A stopped file import picks up where it left off, with no new upload. Returns 409 if the original file is missing or expired.

Restore a missing uploaded source

POST /mailboxes/{id}/imports/{import_id}/restore. Upload the original file again with the upload endpoints above, then pass its file_ids. Shipmail matches each new file to an unfinished file on the same import by organization, mailbox, provider, format, exact size, cleaned-up name, and the versioned source fingerprint in the object key. That fingerprint is a SHA-256 of the file size plus samples from the start and end of the file, not a hash of the whole file. Once every file is back, the same import queues by itself. Returns 409 if a file is missing, expired, doesn't match, or belongs to another import.

Undo an import

POST /mailboxes/{id}/imports/{import_id}/undo. Queues the deletion of the messages that import created. Mail that was already there, and duplicates the import skipped, stay.