Email automation often runs in bursts: a CI matrix creates many inboxes, a webhook receiver retries an event, or a local developer refreshes a message list repeatedly. Without rate-limit awareness, a small workflow can become a request storm. A good client treats rate limits and transient failures as part of the API contract.
Classify before retrying
| Response class | Retry? | Client behavior |
|---|---|---|
| Authentication failure | No | Fix or rotate credentials |
| Invalid resource | No | Verify IDs and state |
| Rate limit | Later | Honor delay and backoff |
| Server failure | Bounded | Retry with jitter |
| Timeout waiting for mail | Workflow decision | End with diagnostics |
Use exponential backoff with a maximum attempt count and a total deadline. Do not retry a request that creates a resource unless the operation is idempotent or you can safely reconcile the response. The OpenAPI reference helps clients understand request shapes, while the TypeScript SDK provides a consistent starting point.
Pagination and polling
Message lists should use the API’s cursor rather than repeatedly requesting the first page. For polling, keep the interval stable, stop on a matching message, and preserve the original deadline through transient retries. Add jitter when many workers start at once so they do not align on the same second.
Observability
Record route, status class, attempt number, elapsed time, and resource ID. Do not record authorization headers, OTPs, links, or full bodies. A useful metric is time from application trigger to confirmed message, split by environment.
Frequently asked questions
Should every 5xx be retried forever?
No. Use a bounded retry policy and return a clear failure.
What should rate-limit handling do?
Honor the server guidance, back off, and avoid parallel retries that multiply load.
Is a timeout an API error?
It can be a normal workflow result; distinguish “no message arrived” from “the API could not be reached.” Read the webhook guide for event-driven alternatives.
Matrix night: twelve workers poll together
Without jitter, every worker hits GET /messages on the same second. Backoff turns a rate-limit response into a recoverable pause instead of a cascading failure.
| Client mistake | Symptom | Fix |
|---|---|---|
| Infinite 5xx retry | Runner hangs | Total deadline on poll loop |
| Parallel inbox creates | Duplicate fixtures | Persist first returned ID |
| Full page fetch each poll | 429 storm | Use limit=5 + cursor |
See disposable email API for developers for idempotent fixture design.