Rate limits

The gateway rate-limits requests at the edge. Limits are keyed by API key when one is present, and fall back to the client IP otherwise, so one integration’s traffic never eats into another’s budget.

Response headers

Every response carries your current budget:

When you’re over the limit

Exceeding the limit returns 429 Too Many Requests as problem+json with code rate_limited (see the problem type):

1
{
2
  "type": "https://docs.usglobalmail.com/api/problems/rate_limited",
3
  "title": "Rate limit exceeded.",
4
  "status": 429,
5
  "code": "rate_limited",
6
  "request_id": "req_1a2b3c4d5e",
7
  "instance": "/v1/mails"
8
}

Staying within limits

• Back off on 429. Wait for the Retry-After interval, then retry. The official SDKs do this automatically with exponential backoff.
• Page efficiently. Use the largest sensible limit (up to 100) to fetch more per request rather than making many small calls.
• Cache what doesn’t change (e.g. folders, addresses) instead of re-fetching on every operation.