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

Domains

Domains are the base of every Zapmail sending setup. Through the API you can search for and buy new domains, connect domains you already own, manage their DNS records, apply domain-level settings such as forwarding and catch-all, organise them with tags, and renew them. This page walks through each workflow and names the endpoint for every step.
Before you start: save Add Billing Details for the workspace, because purchases are refused without billing details. Connecting a domain needs an active mailbox subscription. Top up your wallet before buying (see Wallet and Understanding Zapmail billing). There is no test mode, so purchase and renewal calls charge for real.

Search and buy domains#

1
Find names
Use Search Available Domains with a keyword (acme) or a full name (acme.com) to get availability and prices. Supported TLDs are com, net, org, biz, live, info and co. To check a shortlist of up to 20 exact names, use Check Availability of Multiple Domains. To have names suggested from keywords, use Find Domains With AI and call it repeatedly with the same body until status is completed; results are cached for 5 minutes.
2
Buy
Call Buy Domains with 1 to 20 domains and the number of years for each. The response contains a payment link in invoiceLink, not the standard status and data fields. Unpaid reservations are discarded after about 5 minutes, so pay the link promptly. With useWallet set to true your wallet balance is applied first and any remainder is billed on the invoice.
3
Wait for registration
Registration is asynchronous and starts after payment. Poll List Domains until the new domains show status ACTIVE. A domain that cannot be registered after payment is refunded.
This charges your wallet. The owner of the target workspace is charged for the domains, and for ZapShield or Zap Care if you enable them in the same request.
Aged (previously registered) domains have their own catalogue. Browse it with List Aged Domains and buy with Purchase Aged Domains. Every aged domain has the same fixed price, the call returns an invoice in redirect, and a listed domain can still be refused at purchase if it is not in the latest batch. This charges your wallet in the same way as Buy Domains. For pre-warmed domains see Pre-Warmed.

Connect a domain you already own#

Use this flow when the domain is registered elsewhere. Zapmail manages its DNS after you point the nameservers at Zapmail.
1
Submit the names
Call Connect Domains with domainNames. The first call returns status: pending and starts background jobs. Subdomains, invalid names and names that are already connected are reported as FAILED without a reason.
2
Read the nameservers to set
Call List Domain Connection Requests. While Zapmail waits for you, a request has the status CHECKING_NS_IN_WHOIS and its metadata.expectedNameservers lists the nameservers to set at your registrar.
3
Poll
After you change the nameservers at your registrar, call Connect Domains again with the same names. It returns 207 while any name is unfinished and 200 with status: completed once every name has a final status. Zapmail re-checks with increasing delays for up to 36 hours, then ends the request as NS_NOT_CHANGED.
A request that ended in an error status is not resubmitted by Connect Domains. Remove it with Remove Domain Connection Requests and submit the name again. Sending an empty domainNames there removes every request in the workspace that matches your filters, or all of them when you send none.

Manual nameserver flow#

If you want each step under your control, use these instead of Connect Domains:
1.
Get Nameservers to Connect a Domain returns the nameservers to set. The domain must already be registered, must not be a subdomain, and must not be connected to any Zapmail account. nameServers is one comma-separated string. With maskForwarding set to true you get the ClouDNS nameservers (zapmaildns.com); otherwise you get the Cloudflare nameservers assigned to the domain's zone.
2.
Set those nameservers at your registrar and wait for propagation.
3.
Verify Nameservers to Connect a Domain checks the live nameservers. A mismatch returns 400 with expectedNameServers and gotNameServers; retry later. This call does not add a domain that is not already in the workspace, so use Connect Domains to add one.

Nameservers and DNS management#

Zapmail manages DNS for connected and purchased domains at an approved DNS provider. Domain settings only apply to domains whose nameservers are the approved Zapmail ones; other domains are skipped silently, so compare domainsMatched in the response with the number of IDs you sent.

DNS records#

TaskEndpoint
Read every record in a domain's zoneGet DNS Records
Add records to one domainAdd DNS Records
Add the same records to many domainsPOST /dns/bulk
Change one recordUpdate DNS Record
Delete one recordDelete DNS Record
Check SPF, DMARC, DKIM and MXCheck DNS Records
Behaviour to know:
Records are read live from the DNS provider. Take the record id and zone_id from Get DNS Records for update and delete calls.
Adding a record of a kind Zapmail manages replaces the existing one: SPF records at the same host are merged, and a new DKIM, DMARC, Google site-verification or Google or Microsoft MX record replaces the existing record of that kind.
Add DNS Records to Multiple Domains returns once jobs are queued. There is no status endpoint for them, so confirm results with Get DNS Records or Check DNS Records. Without domainIds, domains are chosen from tagIds, status and contains, and with none of those from every domain in the workspace.
Check DNS Records with an empty domainIds checks every domain in the workspace and lists every checked domain, not only the failing ones.
Deleting a record removes it from the live zone immediately.

Domain settings#

Update Domain Settings applies DMARC, domain forwarding, email forwarding and catch-all to one or more domains, and can run a DNS check, in a single call. Send only the settings you want to change, plus domainIds (required).
SettingWhat it doesRemove it
dmarc.emailAdds a DMARC record to the domain's DNS using this address as the DMARC contact for reports.Cannot be removed with this endpoint.
forwarding.urlDomain forwarding: visitors to the domain are forwarded to this URL. A value without :// gets https:// prepended. URLs containing linkedin are rejected with 400.Send null for url.
emailForwarding.emailEmail forwarding: mail for the domain is forwarded to this address.Send null for email.
catchAll.emailCatch-all: mail sent to any address on the domain that has no mailbox is delivered to this address.Send null for email.
checkDnsWhen true, runs a live SPF, DMARC, DKIM and MX check and returns it as dnsStatus.Not applicable.
Notes:
Send at least one of dmarc, forwarding, emailForwarding, catchAll or checkDns: true, otherwise the call returns 422. checkDns: false counts as not provided.
Changes are queued. Values are saved on the domain at once, and DNS and routing changes are applied in the background, so a 200 does not mean they are live yet. Email forwarding and catch-all are applied through the domain's active admin mailboxes.
Settings run in this order: DMARC, forwarding, email forwarding, catch-all, DNS check. If one fails, earlier ones stay applied.
forwarding.maskForwarding, contains, status and tagIds are accepted but have no effect. The email fields are checked only for type, not for address format, so validate them before sending.
Compare domainsMatched in the response with the number of IDs you sent. If none match, the call returns 400.

Tags#

Tags group domains so you can select them in other calls (tagIds).
1.
Create tags with Create Domain Tags. The body is an array with one object per tag, and each tag can be attached to domains in the same call. A duplicate name and color returns 409, and nothing is created if any tag fails.
2.
List tags with List Domain Tags. The response is a plain array and is not paginated.
3.
Attach existing tags with Assign Tags to Domains. It returns 400 if every pair already exists.
4.
Detach tags with POST /domains/tags/remove. An empty tagIds detaches all tags from the selected domains, and an empty domainIds with no other selector selects every domain in the workspace, so check the selection before sending.
5.
Delete a tag with POST /domains/tags/delete. It returns 200 even for an unknown tag ID.

Renewals#

1
Find domains due
GET /domains/renewal-soon (or Search Domains Due for Renewal with a body) lists domains expiring within 2 months or expired within the last 7 days. Listing a domain does not mean it can be renewed: renewal needs a domain bought through Zapmail.
2
Check the price
Get Domain Renewal Prices returns the 1-year renewal price for each domain. Nothing is charged.
3
Renew
Renew Domains starts a 1-year renewal and returns an invoice link in paymentLink. Your wallet balance is applied first and the rest is payable at the link. The registrar renewal is processed after the invoice is paid. The listed domains are marked as renewing immediately, so repeating the call returns 400 for them.
This charges your wallet. The renewal is billed to the workspace owner: wallet balance first, then the invoice for the remainder.
To renew automatically, turn on auto-renew with Update Domain Auto-Renew. A daily job then bills the owning account when a domain is within 7 days of expiry, applying wallet credit first and charging the saved payment method for the rest. This charges your wallet and your saved payment method whenever it runs. Turn auto-renew off to stop automatic charges. Only active domains bought through Zapmail are eligible, and ineligible IDs are skipped silently.

Other domain operations#

List Domains lists domains with DNS, health, tag and mailbox details. Filters go in the request body. Set global to true to search every workspace the key owner belongs to.
List Assignable Domains lists domains that can receive new mailboxes.
Get Domain Health Score returns the nameserver reputation of one domain based on Spamhaus scores. For the overall health score and label of every domain use List Domains.
Move Domains to Another Workspace moves domains that have no mailboxes to another workspace. After the move every DNS record except NS and SOA is deleted, and the move cannot be undone with this API.
Remove Connected Domains removes domains you connected from outside Zapmail and that have no mailboxes. Domains bought through Zapmail cannot be removed here.
Add Google Client ID to Domains authorises a Google OAuth client ID on the admin accounts of domains so a sequencer app can connect. See Export to Sequencer.
GET /global/mailbox-domain-search searches mailboxes and domains across every workspace the key owner belongs to. It ignores x-workspace-key.
Lists are paginated with page (default 1) and limit (default 10). The name of the total-count field differs between endpoints, so read the response schema of the endpoint you call.
Related: Mailboxes, Pre-Warmed, Deliverability, Team Management.
Previous
Deliverability
Next
Export to Sequencer
Built with