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

Export to Sequencer

Export sends your mailboxes to a sequencer or another sending platform so you can send from them there. You store the platform login once as a third-party account, then export mailboxes to it and poll the export until it finishes. For platforms that connect through OAuth links, you can connect mailboxes with your own Google client ID instead.
Before you start: the mailboxes must exist and be ACTIVE (see Mailboxes). Exports are scoped to the workspace of the request.

Connect a third-party account#

1.
Call Connect Third-Party Account with app and the credentials that platform needs: email and password, or apiKey (with url for EMAILBISON). The credentials are checked live for most apps; invalid credentials return 400 and no account is stored. A workspace can hold several accounts for the same app.
2.
To change a stored account, call Update Third-Party Account. Fields you leave out keep their stored values. Pass accountId to pick the account; without it the call works only when the workspace has exactly one account for the app.
3.
If the platform has organizations or workspaces, list them with List Third-Party Workspaces and pick the orgId or workspace for the export. It needs exactly one connected account for the app.
There is no validator on the connect and update routes: required fields depend on app, and a missing app or email returns a 500 error. Secrets are never returned by any endpoint. The connect call returns data: null and no endpoint lists accounts, so with several accounts for one app you cannot discover thirdPartyAccountId or accountId through this API. Keep one account per app if you rely on the defaults.
For INSTANTLY, a failed authentication during List Third-Party Workspaces also deletes the stored account.

Export mailboxes#

1
Select mailboxes
Send ids for specific mailboxes, or tagIds, contains, status or filters. With ids set, exactly those mailboxes are exported and no status or tag filter applies. With no selector, every mailbox in the workspace is selected.
2
Start the export
Export Mailboxes with apps as a one-item array, for example ["SMARTLEAD"]. Only the first value is used. For any app other than MANUAL a connected account is required, and thirdPartyAccountId is required when the workspace has more than one account for the app.
3
Poll
The response carries exportId. Poll Get Export Status with it. status moves pending, in_progress, then completed or failed. When it is failed, failure_reason is {"general": "<message>"} for an export-wide failure, or a map of mailbox ID to error message for per-mailbox failures.
Things to know:
["MANUAL"] returns a downloadable file in csvExportedLink. If the file takes longer than 60 seconds you get a 200 without data, and the link is emailed to exportedToEmail (default: the key owner's email) when ready. selectedSheetType picks the columns: ALL, MAILBOX_CREDENTIALS, APP_PASSWORDS or SMTP_IMAP.
For EMAILBISON the response has no exportId, so there is nothing to poll. Name the target with workspace (or orgName or orgId).
Mailboxes that reached their weekly export limit are skipped and listed in rateLimitedMailboxes. If every selected mailbox is capped the call returns 429 with a Retry-After header.
Webhook events export.started, export.completed and export.failed are emitted (see Webhooks). The export_id in those events is a different identifier from the numeric exportId that Get Export Status needs.
There is no validator on /exports/*, so check your fields against the endpoint pages.

Google client ID#

Some platforms connect to Google mailboxes through an OAuth client ID that must be authorised on each domain's Google admin account.
Add Google Client ID To Domain authorises one clientId for one domainId, with the appName it belongs to. It is asynchronous, has no status endpoint, and is limited to 2 requests per minute per account (429 beyond that). A missing domain, admin mailbox or field returns a 500 error.
Add Google Client ID to Domains does the same for many domains in one call, with domainIds, clientId and app. Work is queued per domain admin mailbox, and domains without an admin mailbox are skipped without an error.

Custom OAuth#

Connect Mailboxes With Custom OAuth connects mailboxes to a platform through OAuth links you supply, one link per mailbox. Use it for platforms that give you an authorization URL per mailbox instead of accepting credentials.
1.
Send a google section, a microsoft section, or both. mailboxesPerDomain is keyed by domain ID, and each entry holds a mailboxId and its oauthLink. The google section also needs clientId and appName.
2.
The call returns 202 with exportId, accepted and skipped. Background jobs validate the Google client ID, add it to each domain's Google admin where needed, and run the OAuth flow for each link.
3.
Poll Get Export Status with exportId. Failures are recorded there. A Google client ID that does not match google.appName fails the whole export.
Mailboxes that cannot be used are returned in skipped as NOT_ACCESSIBLE (not found, not ACTIVE, disabled, or outside the key's scope) or RATE_LIMITED (with retryAfterSeconds). The limit is 3 requests per mailbox per 7 days, and if all mailboxes are limited the call returns 429. Attempts are given back when the export fails.
Related: Mailboxes, Domains, Webhooks.
Previous
Domains
Next
Zapbox
Built with