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
/v1/mailboxesscope mailboxes:writetier writeRequest 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. |
| password | string | One of | First mailbox password. 8 to 128 characters. Common passwords are rejected. The API never returns it. Also needs the mailbox_credentials:write scope. |
| generate_password | boolean | One of | Set to true to have the server generate the primary password. It is never returned. |
| display_name | string | No | Display 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
/v1/mailboxesScope: 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
/v1/mailboxes/:idScope: mailboxes:read. Returns the mailbox object or 404.
Update a mailbox
/v1/mailboxes/:idscope mailboxes:writetier writeRequest body
| Field | Type | Description |
|---|---|---|
| display_name | string | null | New display name. Set to null to clear. |
| agent_security_hold | boolean | Holds content from API agents for review. Off by default. Turning it on or off also needs messages:review. |
Suspend or resume a mailbox
/v1/mailboxes/:id/suspend/v1/mailboxes/:id/resumeScope: 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
/v1/mailboxes/:id/passwordScope: 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
| Field | Type | Required | Description |
|---|---|---|---|
| password | string | Yes | New 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
/v1/mailboxes/:id/app-passwords/v1/mailboxes/:id/app-passwords/v1/mailboxes/:id/app-passwords/:app_password_idGive 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
/v1/mailboxes/:idScope: 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.