Zapmail
Overview
API Reference
Overview
API Reference
  1. Overview
  • 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. Overview

Authentication

Every request to the Zapmail API must carry an API key in the x-auth-zapmail header. There is no login flow, token exchange or session: the key identifies the account on each request. To act inside a workspace other than your primary one, add the x-workspace-key header.
Your API key is a secret with the full access of its owner. Anyone who holds it can spend your wallet balance and change or delete your domains and mailboxes. Keep it out of client-side code, browser extensions, mobile apps and public repositories.

Get your API key#

Open Developers > Keys in the Zapmail dashboard and copy the key. API access must be enabled on your account before the key works. If you do not see your key, contact support through the chat bubble in the dashboard or at support@zapmail.ai.
An API key is a UUID. Keys have no scopes: a key can call every endpoint its owner can use, and there are no read-only keys.

Send the key#

Pass the key in the x-auth-zapmail header on every request.
Get Current User is a good first call: it returns the account the key belongs to.

Headers#

HeaderRequiredDescription
x-auth-zapmailYesYour API key.
x-workspace-keyNoID of the workspace to run the request in. Defaults to the key owner's primary workspace.
Content-TypeFor requests with a bodyapplication/json.

Workspace scoping#

By default a request runs in the primary workspace of the key owner. To run it in another workspace, send that workspace's ID in x-workspace-key. Find IDs with List Workspaces.
What the header changes:
Domains, mailboxes, subscriptions and wallet figures are those of the selected workspace.
Endpoints that charge money charge the owner of that workspace, not the key owner.
You must be an OWNER or ADMIN of the workspace. A member with a lower role gets 403, and an unknown workspace ID gets 404.
A few endpoints ignore the header and work across every workspace you belong to, or are scoped to your user rather than a workspace. The endpoint page says so when that is the case. Webhook endpoints, for example, belong to the user and are not affected by x-workspace-key.

Key security#

Keep keys on your server. Read them from environment variables or a secrets manager, never from source code.
Never send a key in a URL or query string, which ends up in logs.
Call the API from a backend you control. Do not call it directly from a browser.
Share one key with as few systems as possible. An account has one current key, so every system that uses it must be updated when you rotate.
Rotate a key if you suspect it leaked, and revoke old keys you no longer use.

Rotate and revoke keys#

On the Developers > Keys page you can rotate the current key. Rotating issues a new key and lets you choose when the old key stops working: immediately, in 1 hour, in 24 hours, in 3 days or in 7 days. A grace period lets you deploy the new key before the old one expires. An account can hold at most 3 live keys at a time, so wait for an expiring key to lapse or revoke it before rotating again. You can revoke any key except the current one; rotate the current key instead.

Authentication errors#

StatusMessageCause
401Invalid API keyThe x-auth-zapmail header is missing, is not a valid UUID, or matches no account.
401API key has expiredThe key was rotated or revoked and its grace period has ended.
403You are not permitted to perform this action, please contact supportAPI access is not enabled on the account.
403You must be the owner or admin of this workspace to access this APIx-workspace-key names a workspace where you are neither OWNER nor ADMIN.
404Workspace not foundx-workspace-key names a workspace that does not exist.
A 401 means the credential was not accepted: fix the key, do not retry. A 403 means the key is valid but the account or role is not allowed to do this: retrying does not help until the account setting or your role changes. Other 403 responses can come from individual endpoints for their own reasons; the endpoint page lists them.
{
  "status": 401,
  "message": "Invalid API key",
  "errorId": "6c0a0a4d-4a3e-4a9d-bf5d-0a2f7f5f4f31"
}
Authentication failures use the standard error envelope. See Errors for the full format and Rate Limits for the limits that apply to every key.
Related: Introduction, Quickstart, Errors, Rate Limits.
Previous
Quickstart
Next
MCP
Built with