API
Batching, idempotency, and limits
Build an efficient retry-safe event producer within documented request and workspace limits.
Updated 2026-08-237 min
Use messageId on every event
messageId is the idempotency key. Reusing the same messageId for a retry lets AttuneMail return the request safely without creating another customer event. If you omit it, AttuneMail generates an ID and cannot deduplicate your retry.
Request and throughput limits
| Surface | Limit |
|---|---|
| Single compatible call | 32 KiB |
| Compatible batch | 500 KiB and 500 messages |
| Canonical AttuneMail request | 256 KiB |
| Native provider request | 512 KiB |
| Canonical event properties | 50,000 JSON bytes |
| Workspace ingestion safety limit | 250,000 events per hour |
Batch for efficiency
- ✓Use batches for normal server traffic
- ✓Flush before a server process terminates
- ✓Keep each message's original messageId
- ✓Split before reaching 500 messages or 500 KiB
- ✓Do not hold events so long that lifecycle automation becomes stale
Retry only transient failures
| Status | Action |
|---|---|
| 400 | Fix the payload; do not retry unchanged |
| 401 | Fix or rotate credentials |
| 413 | Split or reduce the request |
| 429 | Honor Retry-After and retry with jitter |
| 503 | Retry with capped exponential backoff and the same messageId |