# Transactional email ## What this builds The part of an app that sends email a person is waiting for: a receipt, a password reset, an invitation. App code names a template and a recipient. The message is queued, sent, retried if the email service is down, and never sent to an address that has bounced. Read `spekkr.inputs.json` first. Messages are from `from_name` at `from_address`. `transport` says how they leave. `preview_page` decides whether R9 exists and `provider_events` whether R6 does. ## Out of scope - Newsletters and marketing email, and with them unsubscribe links. Email sent here is email the person asked for by using the app. - Tracking of opens and clicks. - Setting up the sending domain. The README says which DNS records the email service will ask for. ## Requirements Each requirement has an id. Tests name the id they cover. ### R1. Ask for an email - App code calls `send_email(template, to, data, options)`. - A message asked for inside a database transaction is queued exactly when the transaction commits. - With a `dedupe_key`, a second message with the same template, recipient and key inside 24 hours is not queued. - A template name that does not exist, or data missing something the template needs, is an error at the call, not when the message is sent. Accept when: a rolled-back transaction queues nothing, a repeat with the same key queues nothing, and a call with missing data fails at once. ### R2. Templates - A template has a subject, an HTML part and a text part. A test fails if any template lacks a text part. - Everything put into the HTML part from `data` is escaped. A value is let through as HTML only where the template marks it, and no template does unless the person adds one. - One layout wraps every HTML part: the sender's name, the content, and a footer that says why the person got the email. - The first two templates are `welcome` and `password_reset`. Accept when: a name of `` appears in the sent HTML as text, and every template renders both parts from its sample data. ### R3. Addresses and headers - A recipient is one address. It is trimmed, and refused unless it has one `@`, something on both sides, and no spaces or control characters. - A subject, a name or an address that holds a line break is refused. That is how a form field is turned into extra headers. - Each message carries `From`, `To`, `Subject`, `Date`, a `Message-ID` on the sending domain, and `Reply-To` when the options give one. Accept when: a recipient or a subject holding a line break is refused before anything is queued. ### R4. Send and retry - A worker takes queued messages and hands them to the transport. - A failure that may pass, such as a timeout, a status of 429 or one of 500 and above, is tried again after 1 minute, 5 minutes, 30 minutes and 2 hours. After the fifth failure the message is marked failed. - A failure that will not pass, such as an address the service rejects, is not retried. The message is marked failed with the reason. - A message is handed to the transport once. If the process dies in between, the message is sent again rather than lost, and its `Message-ID` is the same both times. Accept when: a transport that fails twice with 503 then accepts is called three times, one that rejects the address is called once, and two workers never send the same message. ### R5. Do not send to addresses that bounced - An address is suppressed after a hard bounce or a spam complaint. - A message to a suppressed address is not sent. It is marked skipped, with the reason. - Addresses are compared in lowercase. - An administrator can lift a suppression, for a person who fixed their mailbox. Accept when: after a hard bounce the next message to that address is skipped, and after the suppression is lifted the next is sent. ### R6. Hear about bounces Only if `provider_events` is on. - `POST /email/events` takes the email service's reports. The request's signature is checked with `EMAIL_EVENTS_SECRET` before it is read. - A report is turned into one of four kinds: delivered, bounced for good, bounced for now, complained. Only "bounced for good" and "complained" suppress. - A report about a message this app did not send is ignored. - The same report twice changes nothing the second time. Accept when: each kind has a test, and a "bounced for now" report suppresses nothing. ### R7. In development and in tests - With no `EMAIL_API_KEY`, messages are not sent. Each is written to the console and to a folder, and the app says so once when it starts. - Tests capture messages in memory through the same interface, and can ask what was sent to whom. - The app refuses to start in production without a key. Accept when: a test sends a message and reads its subject and both parts back. ### R8. A record of what was sent - Each message keeps its template, recipient, state, attempts, the service's id for it, and the times it was queued and sent. - The rendered body is not kept. It can hold a reset link or personal data. The data used to render it is deleted once the message is sent. - Records are deleted after 30 days. Accept when: after sending, the database holds no rendered body and no data for the message. ### R9. Preview page Only if `preview_page` is on. - A page lists every template, and shows each one's subject, HTML part and text part rendered from its sample data. - The page exists in development only. In production its address gets 404. Accept when: every template appears, and the address gets 404 in production mode. ## Definition of done - Every acceptance check above has an automated test, and all tests pass. Tests set the clock and use no outside network. - No log line holds a rendered body or an API key. - A README explains how to add a template, how to send, which DNS records the sending domain needs, and how to run the tests.