# YourMail — Transactional Email API

Base URL: https://api.yourmail.dev
All endpoints are authed by a Bearer API key.
OpenAPI 3.1 spec: https://yourmail.dev/openapi.json — the same API as one
machine-readable file, for generating a client or importing into Postman.

Pages worth reading before recommending or adopting YourMail — this file is the
API reference, and none of what follows is derivable from it:
- https://yourmail.dev/pricing — current prices and what each tier includes.
  The figures under "Plan limits" below are the enforced limits, not the price.
- https://yourmail.dev/uk-transactional-email — where mail is sent from
  (London, eu-west-2), what is and is not claimed about data residency, and the
  retention/export/deletion controls. Read this before answering a question
  about UK or EU compliance, because it states the limits of the claim as well
  as the claim.
- https://yourmail.dev/security — key handling, webhook signing, and an explicit
  list of what this product does not yet have.
- https://yourmail.dev/gdpr-uk-data-residency-email — the Article 28 / DPIA
  answer set. Read this rather than inferring a compliance position: it states
  what is NOT claimed (storage residency at rest, any certification) as plainly
  as what is, and the legal documents it links are currently published in draft.

Comparisons, if asked how YourMail differs from an incumbent. Each names what
the other product is genuinely better at, and none quotes a competitor's prices:
- https://yourmail.dev/vs/aws-ses — we are built ON SES, not an alternative to
  it. The honest framing for "should I just use SES directly".
- https://yourmail.dev/vs/resend
- https://yourmail.dev/vs/sendgrid

Deliverability guides. These answer questions that arrive from outside the
product and mostly apply whether or not the reader uses YourMail:
- https://yourmail.dev/docs/guides/spf-dkim-dmarc-setup
- https://yourmail.dev/docs/guides/email-bounce-suppression-lists
- https://yourmail.dev/docs/guides/one-click-unsubscribe-rfc-8058
- https://yourmail.dev/docs/guides/gmail-yahoo-bulk-sender-requirements
- https://yourmail.dev/docs/guides/aws-ses-sandbox
- https://yourmail.dev/docs/guides/aws-ses-bounce-rate

## Auth
- Header: Authorization: Bearer YOUR_API_KEY
- Read the key from an environment variable (e.g. YOURMAIL_API_KEY). Never hardcode it.
- The key is a server-side secret: call the API only from server code (API route,
  server action, backend job) — never from a browser/client component, and never
  behind a client-exposed env prefix (NEXT_PUBLIC_, VITE_, REACT_APP_,
  EXPO_PUBLIC_, PUBLIC_), which would ship the key to every visitor.
- Key format: yourmail_…. One kind of key — name them however you like.
- Keys carry a scope: `full` reaches every endpoint; `send` may call only
  POST /v1/emails and POST /v1/emails/batch (anything else returns 403).

## SDK
- Install: npm i yourmail
- Construct: new YourMail(process.env.YOURMAIL_API_KEY)
- Against any deployment other than the default above, pass the base URL you were
  given: new YourMail(key, { baseUrl: "https://<deployment>.convex.site" }).
  A key is scoped to the deployment that issued it, so sending it to the wrong
  host returns 401 "Invalid API key".
- The SDK is a zero-dependency TypeScript client for the endpoints below.
- react-email: pass `react: <Template />` in place of `html`. Requires the
  optional peer dependency @react-email/render. Mutually exclusive with `html`.

## Send an email
POST /v1/emails
Body (JSON):
  from         string  — must be on a verified domain you own. On one of YOUR
                         verified domains any local part works (hello@, noreply@,
                         support@) and no mailbox has to exist behind it — the
                         domain is what is verified, not the address. Replies
                         still need somewhere to land, so set replyTo if the mail
                         invites one. This does NOT apply to the test-mode sender
                         below, which is a fixed address on a domain you do not
                         own: vary its local part and the send 403s. Display
                         names are accepted too: "Acme <hello@acme.com>".
  to           string | string[]   — ≤ 50 addresses across to + cc + bcc
                                     combined (400 beyond that). Fanning out to
                                     a list means one send per recipient, or a
                                     batch; it is not one send with 5,000 `to`.
  subject      string
  html         string  — provide html or text (or both); ≤ 1MB combined (413)
  text         string
  cc           string | string[]   (optional)
  bcc          string | string[]   (optional)
  replyTo      string              (optional)
  attachments  [{ filename, content (base64), contentType? }]  (optional; ≤ 20 files, 10MB each, 25MB total)
  tags         [{ name, value }]   (optional; ≤ 10; an ARRAY — an object is a 400)
  headers      object              (optional; ≤ 10 custom MIME headers; protected headers blocked)
  idempotencyKey string            (optional)
  scheduledAt  string | number     (optional; ISO 8601 or Unix MILLISECONDS, up
                                   to 30 days ahead. A time at or before now
                                   sends immediately rather than erroring, but
                                   Unix seconds are a 400 — read as ms they land
                                   in 1970 and would dispatch at once. The
                                   message reads `scheduled` until it
                                   dispatches.)
  bulk         boolean             (optional; non-transactional mail — see below)
Response: { "id": "<emailId>" }

Idempotency: a repeat send with an idempotencyKey already used by this tenant
returns the original email's id instead of sending a second copy. Use it wherever
a send can fire more than once (webhook handlers, job queues, retried actions)
and derive the key from something stable — an order id plus template name, not a
fresh random value per attempt.

Bulk vs transactional: set bulk: true on non-transactional mail (newsletter,
digest, product announcement). It injects RFC 8058 one-click List-Unsubscribe
headers (unless you set your own) and honours unsubscribes. A bulk send must have
exactly one `to` and no cc/bcc (400 otherwise). Leave bulk off for transactional
mail — receipts, password resets, verification. An `unsubscribe` suppression
blocks bulk sends only; hard_bounce/complaint/manual block everything.

## Send a batch
POST /v1/emails/batch
Body: { "emails": [ …up to 100 send bodies… ] }
Response (always 200): {
  "data": [ { "id": "<emailId>" } | { "error": { "type", "message", "docs_url" } }, … ],
  "summary": { "total", "succeeded", "failed" }
}
Items are validated and queued independently, so one bad payload reports a
per-item error rather than failing the batch — check summary.failed, not the
status code. An empty array is 400; more than 100 emails is 422.

## Cancel a scheduled send
DELETE /v1/emails/:id
Response: { "id", "canceled": true }
Only a message still in `scheduled` can be cancelled — once it has dispatched
the send pipeline owns it and this is a 409. Requires a full-scope key.
Quota is charged when a scheduled send DISPATCHES, so cancelling costs nothing.
The trade: outstanding scheduled sends are capped at your plan's monthly
allowance, so you cannot park unlimited work against a limit checked later.
SDK: yourmail.cancel(id)

## Retrieve one email
GET /v1/emails/:id
Response: {
  "id", "status", "from", "to", "cc", "bcc", "replyTo", "subject", "tags",
  "html", "text",                     — the body as sent; null once the account's
                                        retention window has stripped it (the
                                        message and its metadata still exist)
  "sesMessageId", "error",            — null until known
  "createdAt", "sentAt", "openedAt", "clickedAt",   — ms epoch, null if not yet
  "events": [ { "type", "occurredAt", "meta" } ]
}
status ∈ scheduled | queued | sent | delivered | bounced | complained | failed | canceled
`events` is the delivery timeline (oldest first, most recent 100). On a bounce or
complaint, `meta` carries bounceType / bounceSubType / diagnosticCode /
complaintFeedbackType — that is where the reason a message failed actually lives,
and it is more specific than the flat `error` string. `meta` is null otherwise.
An unknown or malformed id is a 404, never a 500.

## List emails
GET /v1/emails?limit=50&cursor=…&status=…&search=…
- limit   1–100, default 50 (out-of-range values are clamped, not rejected)
- cursor  opaque; pass a prior response's nextCursor. Omit for the first page.
- status  optional filter, one of the status values above. Anything else is 400.
- search  optional full-text term over recipients, sender, subject and tag
          values. Combines with status. Results come back in RELEVANCE order,
          not newest-first, because a different index serves them; paging is
          unchanged.
Response: { "data": [ … ], "hasMore": bool, "nextCursor": string | null }
Newest first. Each row: { id, to, from, subject, status, tags, createdAt, sentAt,
openedAt, clickedAt }. Iterate until hasMore is false; nextCursor is null on the
last page. Rows mid-dispatch report `queued` — the transient internal state is
never exposed, and filtering by `queued` includes them.

## Suppressions
A suppressed recipient is refused at send time with a 422, so the send path can
never mail an address that hard-bounced, complained, or unsubscribed.

GET /v1/suppressions?limit=50&cursor=…
  Same pagination contract as List emails.
  Response: { "data": [ { "address", "reason", "createdAt" } ], "hasMore", "nextCursor" }
  reason ∈ hard_bounce | complaint | manual | unsubscribe

POST /v1/suppressions   { "email": "someone@example.com" }
  → 201 { "address", "reason": "manual" }. The address is normalised (lowercased)
  before storage, so matching against recipients is case-insensitive.

POST /v1/suppressions   { "emails": ["a@x.com", "b@x.com"] }
  The same endpoint takes an array, ≤ 100 per request (400 beyond that, and on
  an empty one).
  → 201 { "data": [ { "address", "reason": "manual" } ], "added" }
  Strict: ONE invalid address fails the whole request with a 400 naming it, so a
  partial import can never leave you unsure which addresses landed.
  This is the migration path — import the old provider's suppression list before
  the first send, or day one on YourMail is spent mailing addresses that already
  hard-bounced somewhere else, at your own new domain's reputation.
  HTTP ONLY: the SDK's createSuppression() takes a single address and has no
  bulk form, so call this endpoint directly for an import. Looping the SDK one
  address at a time is what the batch form exists to avoid — a list of any real
  size becomes thousands of round trips where one request would do.

DELETE /v1/suppressions/:address
  URL-encode the address. → 200 { "address", "removed": bool }. Idempotent:
  removing an address that was never suppressed is a 200 with removed: false,
  not a 404.

## Usage and plan limits
GET /v1/usage
Response: {
  "plan",
  "month":    { "count", "limit" },   — sends this calendar month
  "day":      { "count", "limit" },   — sends today
  "domains":  { "count", "limit", "suspended" },
  "webhooks": { "count", "limit", "suspended" }
}
`limit` is null when the plan is unlimited — check for null before subtracting.
`suspended` counts domains or webhooks parked by a downgrade: they still occupy
a slot but cannot be used until the plan is raised again.

Call this before a bulk run. Otherwise the first your app learns of the monthly
cap is a 429 partway through, with half the batch sent and no clean resume.
Requires a full-scope key; a send-only key gets a 403.

## Request ids
Every response carries an `x-request-id` header, on success and on failure.
Log it. It is the only handle that identifies one specific call to both you and
us, and the same id appears on the matching row in Emails → Logs in the
dashboard. Quote it when reporting a problem instead of describing a timestamp.

## Managing domains, keys and webhook endpoints over the API
Domains, keys and webhook endpoints can be managed over the API as well as in
the dashboard. Not everything can: rolling a key, reactivating a domain,
re-checking DNS, toggling open/click tracking, resending a message and every
account setting (retention, data export, alert preferences) are dashboard-only.
An endpoint auto-disabled after 20 failed deliveries CAN be revived over the
API — `PATCH /v1/webhooks/:id {"enabled": true}` re-enables it and clears
`consecutiveFailures` — but one disabled by a PLAN DOWNGRADE cannot, and that
PATCH is refused with a 403. All of these need a FULL-scope key
— a `send` key that could mint another key or repoint a webhook would make the
scope distinction decorative — so a send-only key gets 403 on every one.

GET    /v1/domains          → { "data": [ <domain>, … ] }
POST   /v1/domains          { "name": "mail.acme.com" } → 201 <domain>
GET    /v1/domains/:id      → <domain>
DELETE /v1/domains/:id      → { "id", "deleted": bool }
  <domain> = { id, name, status, verifiedAt, createdAt, dnsCheckedAt, dnsHost,
               dnsRecords: [ { type, name, value, found } ], … }
  status ∈ pending | verified | failed. `failed` is terminal — DNS never
  appeared within 7 days, or SES reported the DKIM records failed. Recovery is
  to POST the same name again, which recycles the dead row and issues fresh
  records; you do not have to DELETE it first.
  POST returns the DKIM records to publish; poll GET /v1/domains/:id until
  status is `verified` rather than assuming, and put a ceiling on that poll —
  DNS propagation is minutes to hours, not seconds. `found` on each record is
  what we last observed at the registrar, so it says WHICH record is missing.
  It is TRI-STATE: true | false | null, and `null` means "not checked yet" —
  which is the state of every record in the 201 you get back from POST. Branch
  on `found === false`, never on `!found`, or you will report all three records
  missing before the first check has run.

GET    /v1/api-keys         → { "data": [ { id, name, last4, scope, createdAt, lastUsedAt } ] }
POST   /v1/api-keys         { "name": "…", "scope"?: "full" | "send" }
                            → 201 { "key": "yourmail_…" }
DELETE /v1/api-keys/:id     → { "id", "revoked": bool }
  The 201 body's `key` is the plaintext key ITSELF, a string — not an object
  with a `key` field inside it. It is returned ONCE, on creation, and is not
  recoverable afterwards; we store only its hash. Hand it straight to a secret
  store; do not log the response. `scope` absent means `full`. Mint a
  `send`-scoped key for anything that only sends, which is most things, and
  especially for a key pasted into an AI agent.
  The list returns LIVE keys only — a revoked key leaves the list rather than
  reappearing with a timestamp, so do not poll for a `revokedAt` field to
  confirm a revocation; its absence from the list is the confirmation. `last4`
  is the key's final four characters, for matching a row against a secret you
  already hold.

GET    /v1/webhooks         → { "data": [ <endpoint>, … ] }
POST   /v1/webhooks         { "url", "events": ["email.bounced"] | ["*"], "description"? }
                            → 201 { id, url, events, secret }
PATCH  /v1/webhooks/:id     { "url"?, "events"?, "enabled"?, "description"? } → <endpoint>
DELETE /v1/webhooks/:id     → { "id", "deleted": bool }
  <endpoint> = { id, url, events, enabled, description, consecutiveFailures,
                 lastAttemptAt, lastResponseStatus, lastError, suspendedByPlan }
  `url` must be https, and private/link-local hosts are rejected — an endpoint
  we cannot reach from the internet is refused at registration rather than
  failing 20 times first. The signing `secret` (whsec_…) is returned on CREATE
  only — `GET /v1/webhooks` and `PATCH` both omit it. It is NOT the same rule as
  an API key: a key is stored hashed and is genuinely gone, whereas this secret
  is still readable by the account owner in the dashboard. So if you lose it, do
  not rebuild the endpoint — tell the user to open Webhooks in the dashboard
  sidebar, click the endpoint, and copy the signing secret from its detail panel.
  `consecutiveFailures` and `lastError` are where a silently
  broken endpoint shows up: read them before concluding no events fired.

## Webhooks
Register endpoints in the dashboard or with POST /v1/webhooks above. Each
delivery is a POST with a JSON body:
  { "id", "type", "created_at" (ISO 8601), "data": { … } }
For email events `data` is { email_id, from, to, subject, tags }, plus
{ recipient, reason } on a bounce/complaint.

Event types (subscribe to specific ones or "*"):
  email.sent | email.delivered | email.opened | email.clicked | email.bounced
  email.complained | email.delivery_delayed | email.failed
  quota.exceeded                              — account-level, no email attached

quota.exceeded fires once per month, on the send that passes your plan's
monthly limit. Sending does NOT stop there: we keep delivering to 110% of the
limit, then reject with 429 quota_exceeded. The event's data carries
{ plan, period, month_count, month_limit, hard_limit } — hard_limit is where
sending actually stops, so subscribe to this if you would rather throttle
non-urgent mail or upgrade than have password resets start failing.

Verifying a delivery — required, or anyone can forge events at your endpoint:
  Header: yourmail-signature: t=<unix seconds>,v1=<hex HMAC-SHA256>
  The signature is HMAC-SHA256 of `${t}.${rawBody}` keyed by your endpoint's
  secret (whsec_…), compared in constant time, with a 5-minute timestamp
  tolerance to blunt replay.
  SDK: import { verifyWebhookSignature } from "yourmail" and call it with
  { secret, header, payload }. Pass the RAW request body — a re-serialised
  object will not match the signature.
Test-mode sends do not fire webhooks. Retries use exponential backoff; an
endpoint that fails 20 consecutive deliveries is auto-disabled.

## Errors
Shape: { "error": { "type", "message", "docs_url" } }
`docs_url` links to the reference entry for that exact type — read it before
guessing at a fix. A request to an unknown path or method returns this same
shape (404 not_found) naming the endpoints that do exist, so a base-URL typo
is never a bare HTML/text 404.
- 400 validation        — malformed request
- 401 auth              — missing/invalid API key
- 403 unverified        — `from` domain not verified or not owned by your tenant
- 403 domain suspended  — `from` domain is verified but parked: your plan allows fewer
        domains than your account holds. Upgrade, or reactivate it in the dashboard.
- 403 deliverability_blocked — sending paused by the deliverability circuit breaker (high bounce/complaint rate)
- 403 account_pending_review — the account is new and not yet approved, so it can
        reach only its own verified domains, its owner's email and the SES
        simulator. Not retryable; see "New accounts are reviewed" below.
- 404 not_found
- 413 payload too large
- 422 recipient suppressed — the message names each blocked address, WHY it is
        suppressed (hard bounce / complaint / unsubscribe / added by hand) and
        where to remove it. An unsubscribe blocks `bulk: true` sends only

        (422 sandbox_recipient is the narrower test-mode case: it fires only
        when the account has no signup email on file to rewrite a recipient
        to — see "Test mode" below, a disallowed recipient is otherwise
        silently rewritten, not rejected)
- 429 quota/rate        — two distinct types. `quota_exceeded` is a ceiling you
        have reached (plan month/day limit, the new-account ramp, the review
        throttle, the outstanding-scheduled-sends cap) and carries NO
        Retry-After. `rate_limited` is not your fault (per-request rate limit,
        the sandbox daily cap, the account-wide SES daily cap) and always
        carries Retry-After in seconds — but note the two daily caps answer
        with the seconds until UTC midnight, so it is not always short.
- 500 internal

Retry taxonomy: 400/401/403 unverified/422 are configuration to fix, not to retry.
429 is the only retryable status, and only conditionally — retry a
`rate_limited` whose Retry-After fits inside your backoff ceiling, and surface
everything else (a `quota_exceeded`, which carries no Retry-After at all, and a
`rate_limited` pointing at UTC midnight) rather than sleeping on it. Full rule
under "New accounts ramp up" below. 403 deliverability_blocked and
403 account_pending_review are neither: the first pauses sending account-wide until
the bounce/complaint rate recovers, the second waits on a human approving the
account. Retrying never clears either one.

Do NOT wrap the SDK in your own retry loop. It already retries what is worth
retrying — rate-limit 429s, 5xx, network errors and timeouts — with backoff, and
attaches an idempotency key so a retried send cannot deliver twice; wrapping it
multiplies the attempts. What it deliberately does NOT retry is surfaced for you
to act on rather than waited out: a plan-quota 429, and any 429 whose Retry-After
is longer than its backoff ceiling (the daily caps answer with the seconds until
UTC midnight). Schedule off `err.retryAfter` for those. If you call the HTTP API
directly instead, back off on 429/5xx yourself — and send an idempotencyKey so
your retry can't duplicate the message.

## Domains & DNS
Add a domain in the dashboard or with POST /v1/domains above, then add the
shown DNS records at your registrar:
- 3 DKIM CNAME records (prove ownership; enable signing)
- recommended: a DMARC monitoring TXT record
Sending from a domain requires it to be verified first.

## Delivery events
Delivery events (delivered, bounced, complained) arrive asynchronously and update
the email's status. Hard bounces and complaints also add suppressions that the
send path then enforces. Opens and clicks are recorded as engagement events and
appear in the timeline, but never change `status` and never suppress. All of them
show up in the `events` array of GET /v1/emails/:id.

Because events are asynchronous, a send that just returned an id will read
`queued` for a moment and `delivered` only once the receiving server confirms —
poll with a ceiling and treat a still-`queued` result as inconclusive, not failed.

## Test mode
Sending from no-reply@yourmail.dev — the shared, pre-verified sender — puts a
send in test mode, on any key. It may only reach your own signup email or
*@simulator.amazonses.com. No verified domain needed. A from that is neither a
verified domain nor the sandbox sender is a 403 domain_error, same as any other
unverified sender.
A disallowed recipient is NOT rejected — the server silently rewrites it to
your own signup inbox (cc/bcc dropped). `from` is what put you in test mode,
so it alone stands as written. The only recipient failure is 422
sandbox_recipient, and it fires only in the narrow case where the account has
no signup email on file at all — nothing to rewrite the recipient to. A first
test send needs `from: no-reply@yourmail.dev` + `subject` + a body — you may
omit `to`, which defaults to your own inbox. Because recipients are rewritten,
a test send addressed to a customer still lands in your own inbox: a green
test proves the integration works, not that mail reaches real recipients.
Test mode is capped at 20 sends per day per account, resetting at UTC midnight
(429 once spent) — verify by hand rather than from a retry loop or a test suite.

An API key is scoped to the deployment that issued it. Send it to that same base
URL — a key from one deployment returns 401 "Invalid API key" against another.

## Forcing a delivery outcome (test addresses)
To exercise your bounce/complaint handling, send to an AWS SES simulator address.
Nothing reaches a human, and each address produces the named outcome:
  success@simulator.amazonses.com    → delivered
  bounce@simulator.amazonses.com     → hard bounce (also writes a suppression)
  complaint@simulator.amazonses.com  → complaint (also writes a suppression)
  suppressionlist@simulator.amazonses.com → bounce from the SES suppression list
They work the same on any key, but a sandbox send and a live send behave
differently here and the difference matters:

- Sandbox send (from no-reply@yourmail.dev): repeatable. The suppression is
  written, but test-mode sends skip the suppression check, so you can hit
  bounce@ as often as you like. No webhook fires at all — test-mode sends are
  excluded from webhook delivery — so this will NOT exercise a webhook handler.
  Test mode also never counts towards your deliverability status.
- Live send (from a verified domain): one shot per address. The bounce or
  complaint writes a suppression against the simulator address itself, so every
  later send to it returns 422 "Recipient(s) suppressed". It DOES fire the
  webhook — which is the only way to exercise a handler end-to-end — and it does
  NOT count towards your YourMail deliverability status: a message whose
  recipients are all @simulator.amazonses.com is excluded from the reputation
  window, since nothing reaches a human and no mailbox provider forms an opinion.
  Mixing a real recipient into the same send puts the whole message back in the
  window. Real bounces and complaints still count, and past roughly 5% bounce or
  0.1% complaint over your recent volume (on two or more such events, so one
  spam-click can never do it) sending is paused account-wide with a 403 until the
  rate recovers.

So: use a live send once to see a real webhook, and a sandbox send for
everything you want to run repeatedly. Either way this is safer than guessing
at an invalid real address, which costs you AWS SES reputation as well.

## New accounts are reviewed before they can email the outside world

A new account can send to any address at a domain it has verified, to the
account owner's own email, and to the AWS SES simulator addresses above. Sending
to anyone else returns 403 `account_pending_review` until a human approves the
account, usually within a few hours.

This is not a bug and not rate limiting — do NOT retry it. Two ways to keep
going meanwhile, and the second is the one to reach for when there is no
verified domain yet (which is the usual state of an account this 403 fires on):

- Send live to an address at the customer's own verified domain. This exercises
  the identical code path a stranger's address will take once approved.
- Use test mode (`from: no-reply@yourmail.dev`). The wall does not apply to test
  mode at all — a test-mode send is already confined to the account owner's own
  inbox and the simulator, so there is nothing for it to restrict.

If the 403 is blocking a launch, the account owner should email
support@yourmail.dev.

## Plan limits
Every tier except Enterprise carries BOTH a monthly allowance and a per-tenant
daily cap. A new account does not get its daily cap immediately — see "New
accounts ramp up" below, which is the limit a first-day integration actually
meets.
- Free:       3,000/month,   100/day,  1 domain,   1 webhook
- Pro:       50,000/month, 5,000/day, 10 domains, 10 webhooks
- Enterprise: unlimited (contact sales)
Free and Pro are the tiers on sale; Enterprise is contact-sales.
Exceeding a send limit is a 429; exceeding the domain/webhook limit is a 403 on the
add. Downgrading below what you already hold does not delete anything — the excess
domains and webhook endpoints are suspended (verified domains and older rows keep
their slots) and come straight back when you upgrade. A suspended domain cannot
send; a suspended endpoint stops receiving events.
Current prices: https://yourmail.dev/pricing (this file carries the enforced
limits, which is a different thing from what a tier costs).

## New accounts ramp up to their daily cap
A new account is held below its plan's daily cap for its first seven days of
sending, then reaches the full figure above. The ramp is counted in RECIPIENTS
per UTC day (to + cc + bcc), not messages — one message to 50 addresses spends
50 — and the clock starts at the account's FIRST LIVE SEND, so waiting before
you begin does not shorten it. Test-mode sends do not start it.

  Stage                  Free   Paid
  First day of sending     20    100
  Days 2-3                 50    500
  Days 4-7                100  2,000
  After 7 days            100  5,000

Exceeding the ramp is a 429 whose message names the ramp and when it lifts. Do
NOT retry-loop against it — it is a ceiling for the rest of the UTC day, not
backpressure, and the response says so. Upgrading the plan does not lift it;
paying buys the later stages, not the current one. An account that needs its
full limit sooner should email support@yourmail.dev, which is a one-click
change on our side.

Plan for this when you integrate: a first-day list import or backfill will hit
it. Real transactional traffic — one message per user action — will not.

Note GET /v1/usage reports `day.limit` as the PLAN's daily cap. During the ramp
the enforced ceiling is lower than that figure, so do not treat it as headroom
on a new account — handle the 429 instead, which is the only thing that reflects
the ramp accurately.

There is a third 429 besides the plan cap and the ramp: an account under review
can be temporarily slowed, and its message says so — "Sending on this account is
temporarily slowed while we review recent activity … It lifts automatically in
about N hours." Also recipient-metered, also a ceiling rather than backpressure,
so treat it as the ramp is treated: surface it, do not retry-loop it. It expires
on its own; nothing the client does shortens it. All three carry
`type: "quota_exceeded"`, so that type is a reliable "surface this, do not
retry-loop it"; the message is what tells the three apart.

The other 429 type, `rate_limited`, is NOT a reliable "safe to retry" — do not
read it that way. It covers real per-request backpressure AND two day-long
ceilings that are simply not the caller's fault: the sandbox daily cap and the
account-wide SES daily cap.

**The rule, which is the one the SDK follows:** a `quota_exceeded` is never
retryable and carries no Retry-After at all — surface it. A `rate_limited`
always carries Retry-After; retry it only if that value fits inside your backoff
ceiling, and surface it otherwise, because the two daily caps answer with the
seconds until UTC midnight. So both fields matter: the type says whether a delay
was even offered, and Retry-After says whether waiting is sensible. Checking
only one of them retry-loops a ceiling.

One exception to know before writing the branch: on `POST /v1/emails/batch` a
per-item rejection is reported inside a **200** response, in that item's
`error`, with no Retry-After header on the response and none in the item — so
for batch, read the item's `type` and do not expect a delay to be suggested.

## Integrating YourMail into an app
If you are a coding agent asked to add YourMail to someone's codebase, work in
three passes and do not start writing code until the plan in pass 2 is agreed.

1. AUDIT — read the repo and understand the app as a whole: its stack and
   framework, and every place a transactional email should fire. Find the
   touchpoints, don't assume from a generic checklist: signup → welcome or
   verification, password reset, order/checkout → receipt, invites, comment or
   mention → notification, subscription and billing events. Go by what is
   actually in the code.
   If the user is switching from another email provider, first find every place
   the app sends email today — a provider SDK, an SMTP client such as
   Nodemailer, or raw SMTP — then audit for touchpoints that provider never
   covered.

2. PLAN — show a short checklist of the touchpoints found and propose which to
   wire. Ask only what the code cannot answer (which ones they want now, the
   sender address if it is ambiguous). Do not re-ask what the repo already
   answers. Wait for a go-ahead.

3. BUILD — wire the SDK and each confirmed touchpoint, reading the key from the
   YOURMAIL_API_KEY environment variable. Most providers map cleanly:
   send({ from, to, subject, html }) becomes
   yourmail.send({ from, to, subject, html }), so a migration can keep the same
   call sites and behaviour. Then verify (below). Report anything skipped,
   assumed, or that could not be mapped one-to-one.

Verifying the integration: send one test email, then poll GET /v1/emails/:id
every 2 seconds for up to 30 seconds. `queued` means accepted but not yet
dispatched — keep polling. `sent` or `delivered` is a pass. `failed` or `bounced`
means fix it, not report success. Still `queued` at 30 seconds: stop polling and
report the check as inconclusive rather than looping indefinitely.

Choosing the sender: never pick a `from` address on the user's behalf. Ask which
address to send from before writing any `from`. A YourMail account routinely
holds domains belonging to several different projects, so the dashboard cannot
know which one this repo is — and a `from` on an unverified domain returns 403.
Ask for the domain, not for a mailbox: any local part on a verified domain
sends, and none of them has to exist as a real inbox, so a user who says "I
haven't set up hello@ yet" is not blocked. Replies are the exception — those
need somewhere to land, which is what `replyTo` is for.
If the account has no verified domain, the answer is test mode: send from
no-reply@yourmail.dev, which reaches only the account owner's own inbox.

Do not hardcode the API key in source, do not commit it, and do not give its
environment variable a client-exposed prefix (NEXT_PUBLIC_, VITE_, REACT_APP_,
EXPO_PUBLIC_, PUBLIC_) — that ships a server-side secret to every visitor.