Rate limits
Rate limits protect the API and ensure fair usage.
Every API-key request counts against a per-account, per-minute window sized by your plan. When the window is exhausted the API returns 429 — back off and retry after a short delay. SMTP submissions draw from a separate per-minute budget and are capped in simultaneous connections; over the rate you get a 452 temporary failure (retry), over the connection cap a 421 (reuse a connection). GET /v3/usage reports the API limit that applies to you.
| Parameter | Type | Required | Description |
|---|---|---|---|
API requests | per second · all endpoints | Optional | Free: 10/s (600 per minute). Professional: 100/s (6,000 per minute). Enforced as a per-minute window; higher ceilings on request. |
SMTP submissions | per second · separate budget | Optional | Free: 10/s. Professional: 100/s. Over it the relay answers 452 4.7.0 — a temporary failure your library retries automatically. |
SMTP connections | simultaneous | Optional | Free: 5. Professional: 20. Over it the relay answers 421 — hold a small pool of long-lived, authenticated connections and send many messages through each (the relay advertises PIPELINING) instead of opening one per email. |
Data retention
Message history and the event log (GET /v3/events) are retained for 30 days on Free and 12 months on paid plans; the free workspace inside a paid organisation inherits the organisation’s window. Aggregated metrics accept windows up to 366 days. Suppression lists and unsubscribe records never expire. Downgrading from a paid plan keeps the paid window for a 30-day grace period so you can export first.
Message-shape limits: up to 1,000 recipients combined across to/cc/bcc per single send (larger audiences use POST /v3/messages.batch, up to 5,000 personalized recipients), up to 1,000 addresses in any one field, and messages up to 20 MB via SMTP.
What can return 429
| Parameter | Type | Required | Description |
|---|---|---|---|
Account request rate | per minute · all endpoints | Optional | The per-plan window above (Free 600/min, Professional 6,000/min, or a negotiated ceiling). Applies to every authenticated request made with an API key. |
Verification route limits | per minute | Optional | POST /v3/validate is additionally capped at 100 requests/min and POST /v3/validate/bulk at 10 jobs/min per account. |
Bulk suppression & import routes | per minute | Optional | POST/DELETE /v3/suppressions/bulk and POST /v3/suppressions/import are additionally capped at 10 calls/minute per account (up to 10,000 entries a minute through bulk). Exceeding it returns 429 rate_limit_exceeded with Retry-After; retry the same payload after the window — bulk adds are idempotent. |
Sending quotas | per month / per day | Optional | Live sends reserve against your monthly plan volume (including any overage policy) and daily ceiling. When a quota is reached the send is rejected with 429. |
Test allowances | per month | Optional | Test keys draw from the free monthly test send/verify allowance (see Test keys) and return 429 when it's exhausted. |
Rate-limit response headers
Every API response reports the current window state, and a 429 additionally tells you exactly how long to wait before retrying:
| Parameter | Type | Required | Description |
|---|---|---|---|
X-RateLimit-Limit | integer | Optional | The size of your per-account request window (requests per minute). |
X-RateLimit-Remaining | integer | Optional | Requests remaining in the current per-account window. |
X-RateLimit-Reset | integer | Optional | Seconds until the current window resets. |
Retry-After | integer · on 429 | Optional | Seconds to wait before retrying the request. Honour this before applying your own backoff. |
Data retention
| Parameter | Type | Required | Description |
|---|---|---|---|
Events (GET /v3/events) | 30 days Free · 12 months paid | Optional | Message lifecycle events queryable through the API and the Console Activity grid. |
Webhook delivery history | 30 days Free · 12 months paid | Optional | Every delivery attempt with response code, latency and outcome (Console → Webhooks → Activity). |
Webhook resend window | 90 days | Optional | How far back POST /v3/webhooks/deliveries/resend can re-deliver, bounded by your plan’s history retention. |
Retention is enforced daily: data older than your plan’s window is deleted permanently. The same numbers are stated on the events, webhooks and resend pages.