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

Errors

The API reports failures with standard HTTP status codes and a JSON body. Most errors share one envelope, but a few do not, so build your error handling around the HTTP status first and the body second. This page describes the formats, lists the statuses the API returns, and says which ones are worth retrying.

Response formats#

Success#

Most successful responses use this envelope:
{
  "status": 200,
  "message": "Domains fetched successfully",
  "data": {}
}
Some endpoints return a different success body, for example wallet balance, wallet top-up, subscription purchase, Pre-Warmed purchase, quick setup, domain purchase and ZapShield purchase. The Zapbox endpoints return Zapbox's own JSON with success in place of status. The endpoint page shows the exact shape.

Errors#

Errors use this envelope:
{
  "status": 404,
  "message": "Workspace not found",
  "errorId": "b3a1f0c2-6d47-4f1e-9a52-0c8e5d7a1b34"
}
FieldDescription
statusThe HTTP status code, repeated in the body.
messageA human-readable reason. Branch on the HTTP status, not on message text, because wording can change.
errorIdA UUID for this occurrence. Quote it when you contact support@zapmail.ai.
Some 4xx responses add extra fields with context for that error. Ignore fields you do not recognise.

Responses that do not use the envelope#

WhereShape
Rate limit exceeded (429 from the API gateway){ "error": "Too many requests" }. See Rate Limits.
A few inline failures on money-moving endpoints (wallet, purchases){ "message": "..." } without status or errorId. The endpoint page notes where.
A path that does not existA non-JSON 404 page, because no endpoint handled the request.
A 429 can also come from an individual endpoint, for example when an export or a mailbox operation is throttled. Those use the standard envelope, so a 429 with errorId is endpoint-level and a 429 with only error is the API rate limit.

Validation errors#

A request that fails validation returns 422. The message joins every failed rule with a comma and a space. There is no errors array.
{
  "status": 422,
  "message": "domains must be a non-empty array, useWallet must be a boolean",
  "errorId": "0f6c3a9e-7b21-4c85-8d14-3e92a6b5c7d0"
}
List endpoints can also return 400 Invalid pagination parameters when page or limit is not a valid number. See Pagination.

Server errors#

For 5xx responses the API never exposes internal details. The message is Internal server error, whatever went wrong behind it. The exceptions are two infrastructure failures that return 500 with Database connection error or Redis error, and the throttled-dependency 503 described below. Use errorId to identify the failure when you contact support.
{
  "status": 500,
  "message": "Internal server error",
  "errorId": "d41f7e0a-91b3-4a2c-bb6e-5a8c2f9e3d17"
}
If a third-party service that Zapmail depends on answers with a 4xx, the API passes that status through with the message Internal server error. Rely on the status and errorId.
If a third-party service is throttling Zapmail, you receive 503 with Service temporarily unavailable. Please try again later. rather than a 429.

HTTP status codes#

StatusMeaningTypical causes
200Success.Some partial successes also return 200, for example Provision Mailboxes with entries in failed. Check the body.
201Created.Creating a webhook endpoint, a Zap Site or a Zapbox label.
202Accepted for background processing.Connecting mailboxes with custom OAuth, sending Zapbox mail, deploying or regenerating a Zap Site.
207Multi-status. The call ran but not everything finished or succeeded.Retry Failed Mailboxes (some domains failed), Connect Domains (names still in progress), Purchase Deliverability Test (some mailboxes not allocated).
400The request is understood but cannot be processed.Invalid values, a failed business rule, or insufficient wallet balance.
401The API key is missing, malformed, unknown or expired.See Authentication.
403The key is valid but not allowed to do this.API access is disabled, or you are not an OWNER or ADMIN of the workspace in x-workspace-key.
404The resource does not exist in the selected workspace.Unknown domain, mailbox or workspace ID.
406Not acceptable.Remove Connected Domains when an eligible domain still has mailboxes. Nothing is removed.
409Conflict with the current state.A provisioning request already running for the workspace, a Google Workspace or Microsoft tenant that already exists for a domain you are buying, or a duplicate workspace, tag or third-party account.
422Validation failed.See Validation errors above.
425Too early.Billing details are missing for the workspace. Add them, then retry.
429Too many requests.The API rate limit, or an endpoint-level throttle.
500Unexpected server error.The message is masked.
503A dependency is temporarily unavailable.A third-party provider is throttling or down.
Insufficient wallet balance is reported as 400, not 402.

Retrying requests#

StatusRetry?What to do
400, 401, 403, 404, 406, 422NoThe request will fail again. Fix the input, key or permissions first.
409SometimesFor a provisioning request already in progress, wait a few seconds and retry. For other conflicts, change the request.
425After a fixAdd billing details, then retry.
207NoRead the body to see what completed, then handle the remainder.
429YesWait the number of seconds in Retry-After, then retry. See Rate Limits.
500With careRetry reads with exponential backoff: 1 s, 2 s, 4 s, then stop. For requests that buy something, see below.
503YesRetry with exponential backoff, starting at several seconds.

Do not blindly retry purchases#

The API has no idempotency keys. If a request that moves money, such as Buy Domains, Provision Mailboxes or a subscription purchase, times out or returns 500, you cannot tell from the response whether it ran. Check the resulting state before you send it again:
After a domain purchase, call List Domains.
After provisioning, call List Mailboxes.
After any purchase, call Get Wallet Balance and compare it with your expected balance.
Related: Authentication, Rate Limits, Pagination.
Previous
Versioning
Next
Webhooks
Built with