Limits — send caps, payload sizes, and rate limits

Sending is capped per plan, on three windows — monthly, hourly, and daily. Caps are counted per recipient: a message with three to addresses plus one cc counts as four against your caps.

Send caps by tier

See pricing for what each tier includes and the per-event metered rates. Hitting a cap returns a 429 with a specific code and a Retry-After header you should honor:

• Hourly cap → hourly_limit_exceeded, Retry-After: 60.
• Daily cap → daily_limit_exceeded, Retry-After: 3600.
• Monthly cap → monthly_limit_exceeded (or free_tier_exceeded on Free).

{
  "error": {
    "type": "rate_limit_error",
    "code": "hourly_limit_exceeded",
    "message": "Hourly send limit reached for this workspace.",
    "param": null,
    "request_id": "req_01KVF4..."
  }
}

Payload limits on a single message

The hard limits on one POST /v1/messages body:

• Recipients — up to 50 each in to, cc, bcc.
• Subject — up to 998 characters.
• Body — up to 1,000,000 characters each for body_text and body_html.
• Attachments — up to 10 files, 25 MB total decoded.
• Metadata — up to 64 string key/value pairs (keys ≤64, values ≤500 chars).
• Tags — up to 10 { name, value } pairs.
• Batch — up to 100 messages per POST /v1/messages/batch.

Exceeding any of these returns 400 invalid_field with the offending field in param — see errors.

Staying under the caps

• Back off on 429. Read Retry-After and wait that long rather than retrying immediately.
• Batch where you can. One POST /v1/messages/batch of 100 is a single round-trip, though it still counts each recipient against your caps.
• Schedule to smooth bursts. Pass scheduled_at to spread a large run across time and stay under the hourly window.
• Use idempotency keys. Pair retries with an Idempotency-Key so a retried send never double-charges a cap or a recipient.