API reference
Versioned from the first release at /v1/…. Authenticate with a Bearer API key, send idempotency keys on mutating calls, and expect the same error shape every time.
Authentication
Authorization: Bearer calder_sk_live_… Test keys (…_test_…) simulate everything and deliver nothing. Keys are scoped to one project and one environment, hashed at rest, revocable anytime.
Endpoints
| Method | Path | What it does |
|---|---|---|
| POST | /v1/emails | Send an email. Returns 202 with the email id. |
| GET | /v1/emails | List emails in your project, newest first. |
| GET | /v1/emails/:id | Fetch one email with its current status. |
| GET/POST | /v1/domains | List domains / add a domain for verification. |
| POST | /v1/domains/:id/verify | Check verification and mark verified. |
| GET | /v1/projects | List projects in your organization. |
| GET/POST | /v1/webhooks | List endpoints / register an endpoint. |
Idempotency
Send Idempotency-Key: <your-unique-key> on POST /v1/emails. Repeating a key within 24 hours returns the original result with a 200 instead of sending twice.
Errors
Always { error: { code, message, request_id } }. Common codes: validation_error, authentication_error, authorization_error, domain_not_verified, suppressed, rate_limit_error. Quote the request_id when contacting support.
Rate limits
Sending: 100/min. Verification: 10/min. Auth: 20/min. Every 429 includes limit, remaining, reset, and Retry-After headers.