Quickstart

Three things have to be true before a message can go out: a verified sending domain, an API key with the right scope, and a recipient who isn't suppressed. This page walks through the first two.

1. Verify a sending domain

Use a subdomain per purpose — mail.example.com for transactional mail, news.example.com for campaigns. Mailbox providers score reputation per domain, so keeping them apart is what stops a campaign's complaint rate affecting password reset delivery.

Adding a domain returns the DNS records to publish. GET /v1/domains then shows each record beside what is currently resolving, so a stuck verification tells you which record is missing rather than just failing.

curl -X POST https://api.example.com/v1/domains \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"domain": "mail.example.com", "risk_class": "transactional"}'

2. Send

Always pass an Idempotency-Key. If the request times out, retrying with the same key returns the original result instead of delivering a second copy — which matters more here than in most APIs, because the duplicate lands in someone's inbox.

curl -X POST https://api.example.com/v1/emails \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "from": "Team <team@mail.example.com>",
    "to": "someone@example.com",
    "subject": "Hello",
    "html": "<p>Hi there.</p>"
  }'

3. Watch what happened

GET /v1/emails/{id} returns the message with its full event timeline — send, delivery, bounce, complaint, open, click. This is the call to reach for when someone asks why an email didn't arrive.