# Design This file fixes the parts that are easy to get wrong. Choose the language and framework that fit the person's project; nothing here depends on them. ## Data model Use the database in the `database` input. | Table | Columns | | --- | --- | | `emails` | `id`, `template`, `recipient`, `data` (JSON, emptied once sent), `dedupe_key`, `message_id`, `state`, `attempts`, `next_attempt_at`, `provider_id`, `last_error`, `queued_at`, `sent_at` | | `email_suppressions` | `address` (primary key, lowercase), `reason`, `created_at` | | `email_reports` | `id` (the service's id for the report, primary key), `kind`, `provider_id`, `at` | `state` is one of `queued`, `sending`, `sent`, `failed` and `skipped`. A unique index on `template`, `recipient` and `dedupe_key`, where the key is set, does the work of R1. A job clears the key on rows older than 24 hours. ## The transport One interface with one operation, `deliver(message)`, which answers "accepted" with the service's id, "try again" or "refused" with a reason. | `transport` | Notes | | --- | --- | | `http_api` | One `POST` to the email service with `EMAIL_API_KEY`. Map its statuses: 2xx accepted; 429 and 5xx try again; other 4xx refused. Time out after 10 seconds. | | `smtp` | STARTTLS, then authenticate. Replies of 4yz mean try again; 5yz mean refused. | Tests use a third one that keeps messages in a list. ## Rules - Choose the `Message-ID` when the message is queued and store it: a random part, `@`, and the domain of the `from_address` input. - Build the `From` header from the `from_name` and `from_address` inputs. Quote the name. - Check for suppression when sending, not when queueing, so a bounce that arrives while a message waits still stops it. - A worker claims rows that are `queued` with `next_attempt_at` passed. In Postgres claim with `FOR UPDATE SKIP LOCKED`; in SQLite with a single `UPDATE` that sets `sending` where the state is `queued`. A row left in `sending` for more than 2 minutes is claimable again. - The waits after failures 1 to 4 are 60, 300, 1800 and 7200 seconds. - Derive the text part by hand, not from the HTML. A machine-made text part reads badly and mail filters notice. ## Reports Services name things differently. Map what the service sends onto these: | Kind | Typical names at services | | --- | --- | | delivered | delivered, delivery | | bounced for good | hard bounce, permanent failure, invalid recipient | | bounced for now | soft bounce, deferred, transient failure, mailbox full | | complained | spam complaint, complaint | A person whose service speaks otherwise puts a few translating lines in front. ## Configuration | Secret | Purpose | | --- | --- | | `DATABASE_URL` | Connection string for the chosen database. | | `EMAIL_API_KEY` | Sends the emails, or the SMTP password. Not needed in development. | | `EMAIL_API_URL` | Where the `http_api` transport posts each message. Only with `http_api`. Not needed in development. | | `EMAIL_EVENTS_SECRET` | Checks the signature on reports. Only with `provider_events`. | ## Named here - The `http_api` transport makes one `POST` to `EMAIL_API_URL` with `Authorization: Bearer ` and a JSON body of `from`, `to`, `subject`, `text`, `html` and `message_id`. - A report arrives with the header `X-Email-Signature`, the HMAC-SHA-256 of the raw body under `EMAIL_EVENTS_SECRET`, in hex. The raw bytes are read for the check and parsed only after it passes. ## What this spec leaves to you Where this spec names something, use that name, so that two builds of it agree. Where it does not, the choice is yours. List what you chose in the README.