Core concepts

Five ideas explain nearly everything Calder does. Learn them once and the whole platform — API, dashboard, webhooks — reads like one coherent system.

1. The email lifecycle

Every email moves through states: created → queued → sending → sent → delivered, with bounced, complained, and failed as terminal detours. Opens and clicks attach after delivery. Each transition is recorded as an event you can query — the timeline in your dashboard is this lifecycle, rendered.

2. Async by default

POST /v1/emails validates, persists, enqueues, and answers 202 in milliseconds. Delivery happens in a background worker with retries. Your request path never waits on a mail server — that separation is the single most important architectural decision in the system.

3. Idempotency

Networks fail mid-request, and clients retry. The Idempotency-Key header makes retries safe: the first request stores its result, repeats return the original. Anything that could cause harm if duplicated — sends, charges — requires one.

4. Events and webhooks

Every lifecycle transition emits an event (email.sent, email.delivered, …). Events fan out to your webhook endpoints signed and retried. If you can handle webhooks, you can build on- delivery onboarding, on-bounce cleanup, and on-complaint suppression without polling us.

5. Suppression

Addresses that bounced, complained, or unsubscribed are blocked before sending — with a logged reason, never silence. Suppression protects your domain reputation automatically; the dashboard shows you exactly who is suppressed and why.