Zapmail
Overview
API Reference
Overview
API Reference
  1. Capabilities
  • Introduction
  • Quickstart
  • Authentication
  • MCP
  • Versioning
  • Errors
  • Webhooks
  • Rate Limits
  • Pagination
  • Changelog
  • Capabilities
    • Mailboxes
    • Pre-Warmed
    • Deliverability
    • Domains
    • Export to Sequencer
    • Zapbox
    • Team Management
    • ZapShield
    • ZapCare
    • AI Insight
    • Deliverability Tests
    • ZapSites
    • Zapwarm
    • ZapPulse
  • Billing
    • Understanding Zapmail billing
    • Wallet
  1. Capabilities

Mailboxes

Mailboxes are the sending accounts that live on your domains. This page covers how to create them, how to follow their status, and how to update, schedule removal of, and sign in to them.
Before you start: the domain must be ACTIVE in the workspace (see Domains), billing details must be on file (Add Billing Details), and the account needs an active mailbox plan or add-on. A domain holds at most 5 mailboxes unless the account has a higher limit.

Provision mailboxes#

Provision Mailboxes creates mailboxes on your domains and buys any missing slots in the same call. It is keyed by domain name and returns per-mailbox results, successCount, failedCount and slotsPurchased. One provisioning request per workspace runs at a time; a concurrent call returns 409.

Provision with purchase#

1.
Call Provision Mailboxes with domains, each holding its mailboxes.
2.
Read failed and failedCount in the response. The status is 200 even when some mailboxes fail.
3.
Poll each succeeded[].mailbox.id (see Statuses and polling).
Before any purchase the endpoint skips duplicate usernames in the request, mailboxes that already exist, and mailboxes beyond the per-domain limit. Slots bought equal the eligible mailboxes minus unused capacity left on today's add-on, billed at your plan's per-mailbox add-on price.
This charges your wallet. The workspace owner's wallet is charged immediately, before mailboxes are created, for the slots in slotsPurchased. The request fails with 400 if the balance does not cover the cost. The charge is not reversed when an individual mailbox then fails; the unused slots stay on the add-on subscription and are reused the same day.
To go from nothing to sending mailboxes in one request, including domain registration, see Start Quick Setup and follow it with GET /quick-setup (see Quick setup).

Statuses and polling#

Mailbox creation is asynchronous. A new mailbox starts as IN_PROGRESS.
StatusMeaning
IN_PROGRESSBeing created
CREATING_PASSWORDBeing set up
ACTIVEReady to use
FAILEDCreation failed
EXPIREDThe mailbox term ended
Poll GET /mailboxes with the mailbox id until status is ACTIVE or FAILED. To follow many mailboxes at once, use List Mailboxes, which groups mailboxes by domain and paginates by domain. The full address is username@domain.
If a mailbox ends as FAILED, fix the cause (for example update the domain's nameservers) and call Retry Failed Mailboxes with domainIds. It sets the failed mailboxes back to IN_PROGRESS and queues creation again, so poll again. A domain can be retried 3 times per 24 hours. Per-domain problems return 207 with the skipped domains in data, while domains that passed are still retried. Retrying uses existing slots and does not charge.
Mailbox credentials (appPassword, secret, and in the list also password) are returned by the read endpoints. Treat responses as sensitive.

Update mailboxes#

Update Mailboxes changes the first name, last name, username or profile picture. The body is mailboxData, an array of instructions, each targeting one mailbox with mailboxId.
A 200 means the change was queued, not applied. Poll GET /mailboxes and compare the fields.
Each instruction is processed independently and reported at the same index in data. A rejected instruction appears as { "error": {} } while the request still returns 200, so check every element.
Changing username changes the email address.

Schedule removal#

Schedule Mailbox Removal schedules mailboxes to be removed at their next renewal, so you stop paying for them without deleting them now. Send either mailboxIds or domainIds (both or neither returns 422) and remove: true. Mailboxes keep working until the removal date. Send remove: false before then to clear the schedule. The admin mailbox of a domain can only be scheduled together with all other mailboxes of that domain.
The schedule cannot be read back from the mailbox response. A mailbox.updated webhook is emitted when it changes (see Webhooks).

Authenticator code#

If signing in to a mailbox asks for a two-factor code, call Get Authenticator Code with mailboxId. It returns the current code in otp and the seconds left in expiresIn; codes rotate every 30 seconds. A mailbox without a two-factor secret returns 400. For a Microsoft domain's admin account, send domainId instead. If both are sent, mailboxId is used.

Connect mailboxes to other platforms#

To send from mailboxes in a sequencer, see Export to Sequencer. Connect Mailboxes With Custom OAuth is described there.
Related: Domains, Pre-Warmed, Understanding Zapmail billing, Wallet.
Previous
Changelog
Next
Pre-Warmed
Built with