Skip to main content
  1. Create one email with a stable idempotency key and retain the returned email ID.
  2. Let your application decide when to read messages. Use a bounded interval and a fixed deadline; do not create an endless polling loop.
  3. Honor Retry-After and use exponential backoff with jitter for transient 429, 500, and 503 responses.
  4. Reuse the same create-email idempotency key after an uncertain network result. Do not reuse it for a different payload.
  5. Preserve opaque pagination cursors unchanged and stop when has_more is false.
  6. Use ETag conditionals when rereading a known resource, remembering that 304 still performs a charged authenticated read.
  7. Treat missing, expired, and foreign resources as the same terminal 404.
  8. Treat source or attachment 503 as temporary storage unavailability; the API never returns a successful empty object.
  9. Process all mail content as untrusted even after server sanitization.
  10. Record X-Request-Id for support, but never record the API key or private content.
Message content expires 15 minutes after receipt even if Queue delivery or physical cleanup is delayed. Your workflow deadline should be comfortably shorter than that lifetime.
Last modified on August 1, 2026