REST API basics: keys, idempotency and errors

Every request uses Authorization: Bearer cm_live_.... Keys are shown once and stored only as a hash.

Scopes

• emails:send – send email
• emails:read – read message status
• contacts:read / contacts:write – manage campaign audiences

Give each system only the scopes it needs, and optionally lock a key to one sending domain.

Idempotency

Network failures happen. Send an Idempotency-Key header (for example order-1234-receipt). Repeating the same key with the same body returns the original email instead of sending twice. The same key with a different body returns 409.

Status codes

• 202 accepted for sending · 200 idempotent replay
• 401 bad key · 403 missing scope, unverified domain or sandbox
• 413 too large · 422 validation error or every recipient suppressed
• 429 rate limit or quota (see Retry-After) · 503 sending paused

Statuses

queued → accepted → delivered, or bounced, complained, failed. "Accepted" means the upstream server took the message; "delivered" comes only from real delivery events.

See the full API reference.