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

Quickstart

This quickstart takes you from an API key to working mailboxes: confirm who you are, check and fund the wallet, check that a domain is available, buy it, create mailboxes on it, and wait until they are active. Every example calls the live API.
There is no test mode. Three steps in this guide spend money: topping up the wallet charges your card, buying the domain charges your wallet, and provisioning mailboxes charges your wallet. Each step is marked.
https://api.zapmail.ai/api/v3

Before you start#

An API key. Get it from Developers > Keys in the dashboard. See Authentication.
An active base plan on the account. Provisioning buys mailbox slots as add-ons to your plan and fails with a 400 (No active base plan found) without one. Step 1 shows your plan.
Billing details on file for the workspace. Add them in the dashboard or with Add Billing Details.
A domain name you want to register. The examples use acmeoutreach.com; replace it with your own.
Store the key in an environment variable named ZAPMAIL_API_KEY and keep it out of source control.

Set up a client#

The curl examples pass the key on every request. For JavaScript and Python, define one helper that sends the key, parses the JSON and raises on any error status. Later steps call it.
JavaScript
Python

1. Confirm your identity#

Get Current User returns the account the key belongs to, its active plan and its wallet balance. There is no separate whoami endpoint.
curl
JavaScript
Python
Check data.email is the account you expect. activePlan is omitted when the account has no active plan; you need one for step 6. To act in a workspace other than your primary one, add the x-workspace-key header to every call below.

2. Check the wallet and top up#

Get Wallet Balance returns the balance in USD. This response is not wrapped in the usual data object: walletBalance is at the top level.
curl
JavaScript
Python
If the balance will not cover the domain price (step 3) plus the mailbox slots (step 6), top it up with Add Wallet Balance.
This charges your card. The call returns a Stripe Checkout link in paymentLink; your card is charged when you complete that checkout, and the wallet is credited shortly afterwards. Poll Get Wallet Balance until the new balance shows. The call returns 400 if any wallet debit happened in the last minute, so wait and retry if you top up right after a purchase.
curl
JavaScript
Python
You can also enable auto recharge so the balance refills from a saved card.

3. Check domain availability#

Search Available Domains accepts a keyword or a full domain name and returns prices. Send the full name to get an exact match.
curl
JavaScript
Python
Proceed only if data.exactMatch.status is AVAILABLE. data.exactMatch.domainPrice is the registration price in USD as a string. exactMatch is null when the name is blocked or already being registered; pick another name from data.availableDomains. This endpoint has its own limit of 100 requests per 30 minutes per key. See Rate Limits.

4. Buy the domain#

Buy Domains registers 1 to 20 domains in one call.
This charges your wallet. With useWallet set to true, the wallet balance is applied to the domain price first and any remainder is billed on the invoice returned in invoiceLink. Pay that invoice promptly: unpaid reservations are discarded after about 5 minutes. With useWallet set to false the wallet is not used and invoiceLink is a card checkout page.
curl
JavaScript
Python
The response has no status or data fields; the link is invoiceLink. The call returns 409 if a Google Workspace or Microsoft tenant already exists for the name.
Registration is asynchronous. Poll List Domains until the domain shows ACTIVE. Filters are sent in the body even though the call only reads data.
curl
JavaScript
Python
A domain that cannot be registered after payment is refunded.

5. Plan the mailboxes#

A domain holds at most 5 mailboxes unless the limit is raised on your account. Usernames may contain letters, digits, ., _ and -, and must not start or end with those characters or repeat them back to back.

6. Provision the mailboxes#

Provision Mailboxes creates mailboxes on domains you already own and buys any missing mailbox slots in the same call. The domain must be ACTIVE in the workspace.
This charges your wallet. The workspace owner's wallet is charged immediately, before the mailboxes are created, for the slots in slotsPurchased, at your plan's per-mailbox add-on price. The call fails with 400 if the balance does not cover the cost. The charge is not reversed if an individual mailbox fails afterwards; unused slots stay on the add-on.
curl
JavaScript
Python
The status is 200 even when some mailboxes were not created. Check failedCount; each entry in failed carries a reason. One provisioning request runs per workspace at a time, so a concurrent call returns 409; retry after a short delay.

7. Wait until the mailboxes are active#

New mailboxes start as IN_PROGRESS. Poll GET /mailboxes with the mailbox.id from each entry in succeeded until data.mailbox.status is ACTIVE or FAILED.
curl
JavaScript
Python
Re-queue mailboxes that end in FAILED with Retry Failed Mailboxes. Keep polling gentle: the API allows 5 requests per second and 200 per minute per key across all calls. To avoid polling altogether, subscribe to Webhooks.

What to do next#

Export the new mailboxes to your sequencer. See Export to Sequencer.
Set DMARC, forwarding and catch-all on the domain. See Domains.
Receive status changes by webhook instead of polling. See Webhooks.
Invite teammates or create more workspaces. See Team Management.
Related: Authentication, Rate Limits, Errors, Wallet.
Previous
Introduction
Next
Authentication
Built with