# YourMail — Transactional Email API

Base URL: https://api.yourmail.dev
All endpoints are authed by a Bearer API key.

## 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
  to           string | string[]
  subject      string
  html         string  — provide html or text (or both)
  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         object              (optional)
  headers      object              (optional; ≤ 10 custom MIME headers; protected headers blocked)
  idempotencyKey string            (optional)
  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" } }, … ],
  "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.

## Retrieve one email
GET /v1/emails/:id
Response: {
  "id", "status", "from", "to", "subject", "tags",
  "sesMessageId", "error",            — null until known
  "createdAt", "sentAt", "openedAt", "clickedAt",   — ms epoch, null if not yet
  "events": [ { "type", "occurredAt", "meta" } ]
}
status ∈ queued | sent | delivered | bounced | complained | failed
`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=…
- 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.
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 normalized (lowercased)
  before storage, so matching against recipients is case-insensitive.

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.

## Webhooks
Configure endpoints in the dashboard. 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
  deliverability.degraded | quota.threshold   — account-level, no email attached

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-serialized
  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" } }
- 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)
- 404 not_found
- 413 payload too large
- 422 recipient suppressed — recipient previously hard-bounced or complained
        (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        — daily/monthly plan limit, the sandbox daily cap, or a
        rate limit; includes a Retry-After header (seconds) on rate-limit responses
- 500 internal

Retry taxonomy: 400/401/403 unverified/422 are configuration to fix, not to retry.
429 is the retryable one — back off by Retry-After. 403 deliverability_blocked is
neither: sending is paused account-wide until the bounce/complaint rate recovers,
so retrying never clears it.

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, 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 toward your deliverability status.
- Live send (from a verified domain): one shot per address, and it counts. 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 — but it
  also counts toward your YourMail deliverability status exactly like a real
  one. Past roughly 5% bounce or 0.1% complaint over your recent volume, sending
  is paused account-wide with a 403 until the rate recovers. Repeated live
  bounce testing on a low-volume account can therefore lock you out.

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.

## Plan limits
Only Free carries a per-tenant daily cap; the paid tiers are metered monthly.
- Free:       3,000/month, 100/day, 1 domain,  1 webhook
- Starter:    5,000/month,          2 domains, 2 webhooks   (retired — existing customers only)
- Growth:    20,000/month,          5 domains, 5 webhooks   (retired — existing customers only)
- Pro:       50,000/month,         10 domains, 10 webhooks
- Enterprise: unlimited (contact sales)
Free and Pro are the tiers on sale. Starter and Growth are retired: they can no
longer be bought, but they are still enforced exactly as listed for anyone
already on one.
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. See /pricing for current prices.

## 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.
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.