Documentation

Rate limits and quotas.

Three different limits can stop a send. They look alike and need different fixes.

429 rate_limit_exceeded

Requests to the API are limited per organization to a number per second. Every response, errors included, carries ratelimit-limit, ratelimit-remaining and ratelimit-reset, and a request over the limit gets 429 rate_limit_exceeded with a Retry-After header. Back off for that long and retry. The limit is on requests, not emails: to send many messages at once, use POST /api/v1/emails/batch so a hundred messages cost one request. See pagination and rate limits for the current numbers.

daily_quota_exceeded

The Free plan has a daily cap on emails. When it is reached, sends are refused until it resets at 00:00 UTC. Other plans have no daily cap.

monthly_quota_exceeded

The plan's monthly email limit was reached. Sending stops at the limit instead of billing for more, so there are no surprise charges; it resumes next month or when you upgrade. The Usage page shows how much of the month is used.

Sending-rate throttling

Separately from your API limit, the network that delivers mail can throttle throughput when a burst exceeds the sending quota. Mailtruss's worker retries with backoff automatically; you do not need to resend the message. If it happens often, contact support to raise the sending quota.

Retrying safely

Pass an idempotency key with each send. Then retrying a request that timed out or returned 429 or a 5xx can never deliver the message twice. Without a key, a client should not retry a send. See Idempotency.