Rate limits

BoostMail enforces two rate limit windows. Both are measured per minute, and one runs before the other.

The two windows

• Per account: 120 requests per minute per account. This window applies once BoostMail has resolved your API key to an account. Every request counts against your account’s limit, regardless of which endpoint it hits.
• Pre-auth per IP: 30 requests per minute pre-auth per IP. This window applies before BoostMail resolves your key, checked against the calling IP address. It is the one case where a request that would otherwise fail with 401 fails with 429 instead: if you exceed the pre-auth window, BoostMail rejects the request for rate limiting before it looks at your key at all.

Response headers

On a request where BoostMail has resolved your account, every response carries:

• RateLimit-Limit: the size of your per-account window.
• RateLimit-Remaining: requests left in the current window.
• RateLimit-Reset: seconds until the window resets. This is a delta, not an epoch timestamp.

These headers are not in the generated API reference; this guide is the source of truth for them.

A pre-auth per-IP rejection carries none of the RateLimit-* headers, since BoostMail has not resolved an account to report a limit for. It carries only Retry-After (see below).

The 429 response

Exceeding either window returns 429 with this body:

{
  "error": {
    "code": "rate_limited",
    "message": "rate_limited"
  }
}

Every 429, account-resolved or pre-auth, includes a Retry-After header: the number of seconds to wait before retrying.

Handling a 429

Honor Retry-After. Wait the number of seconds it gives you before your next attempt, and back off if you hit the limit repeatedly rather than retrying immediately.

See the Errors guide for the full error envelope and status code table.