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

Rate Limits

The API limits how many requests each API key can send. When you exceed a limit the API answers with HTTP 429 and tells you how long to wait. This page lists the limits, the headers that report them, and how to stay inside them.

Limits#

LimitWindowRequestsApplies to
Per second1 second5Every request
Per minute60 seconds200Every request
Domain availability30 minutes100POST /domains/available and POST /domains/available-bulk
Limits are counted per API key. They are shared across all endpoints, all workspaces selected with x-workspace-key, and all API versions.
A request to a domain availability endpoint counts against all three limits.
Some keys have higher ceilings. Contact support@zapmail.ai with your use case if the defaults are not enough.
The limiter runs before the key is validated, so requests that carry an invalid key also count against that key value. A request with no x-auth-zapmail header at all is rejected with 401 before the limiter runs.

Rate limit headers#

Responses carry these headers:
HeaderMeaning
RateLimit-PolicyThe limit and its window in seconds, for example 5;w=1.
RateLimit-LimitRequests allowed in the current window.
RateLimit-RemainingRequests left in the current window.
RateLimit-ResetSeconds until the current window resets.
Retry-AfterSeconds to wait before retrying. Sent only on 429 responses.
The headers use the draft-6 form of the IETF rate limit header proposal. When several limits apply, the headers describe the limit that was evaluated last. On a successful response that is the per-second limit, so RateLimit-Limit reads 5; on a 429 it is the limit that was exceeded.

When you exceed a limit#

The API returns 429 Too Many Requests with a body that is not the standard error envelope:
{ "error": "Too many requests" }
There is no status, message or errorId in this body. Detect a rate limit by the 429 status, then read Retry-After. See Errors for how this differs from other 429 responses.
HTTP/1.1 429 Too Many Requests
Retry-After: 1
RateLimit-Policy: 5;w=1
RateLimit-Limit: 5
RateLimit-Remaining: 0
RateLimit-Reset: 1
Content-Type: application/json
Requests that the per-second limiter rejects still count toward your per-minute allowance. A client that retries immediately in a tight loop therefore uses up its minute budget quickly. Wait for Retry-After before sending the next request.

Stay within the limits#

Keep sustained traffic under 200 requests per minute, which is about 3 requests per second. The 5 per second ceiling only allows short bursts.
Use batch endpoints. Buy Domains takes up to 20 domains, Provision Mailboxes takes several domains and mailboxes in one call, and Check Availability of Multiple Domains checks many names at once.
Poll at an interval of 15 to 30 seconds, not in a loop, and stop as soon as the resource reaches a final state. Better, subscribe to Webhooks and skip polling.
Cache data that rarely changes, such as the list of tags or workspaces.
Spread bulk jobs over time with a queue that caps the request rate for your key.

Handle 429 in code#

Honour Retry-After, cap the number of attempts, and fall back to a short exponential delay if the header is missing.
JavaScript
Python
Only use this pattern for requests that are safe to repeat. A 429 means the request was rejected before it ran, so repeating it is safe. Do not apply the same blind retry to a 500 on a request that buys something. See Errors.
Related: Authentication, Errors, Pagination.
Previous
Webhooks
Next
Pagination
Built with