Queue-Backed Email API

Project roadmap

1. 01

   Design the service

   ~2h

   Write DESIGN.md: an email job (id, idempotency key from the caller, to, subject, text and HTML body or a template name with data, status queued, sending, sent, failed or dead, attempts, next attempt time and last error), how jobs are stored (SQLite or PostgreSQL) and claimed by workers, which SMTP errors are temporary (4xx codes and timeouts) and which are permanent (5xx), the rate limit, and the API. Done when: DESIGN.md covers jobs, states, errors and limits.

2. 02

   Build the API

   ~2h

   Build a Node.js API (with Express or Fastify) with POST /emails, validating the input (valid addresses, subject length and body size) and an API key, storing the job and returning 202 with its id; a repeated idempotency key returns the existing job. Add GET /emails/:id and GET /emails with filters. Done when: emails can be queued and their status read, and duplicates are recognized.

3. 03

   Send with workers and retries

   ~2.5h

   Write a worker that claims due jobs one at a time (in a transaction, marking them sending with a lease), renders templates, sends with Nodemailer through the configured SMTP server, and marks jobs sent with the message id. On temporary errors, schedule a retry with exponential backoff and jitter; on permanent errors or after max attempts, mark the job dead with the reason. Test with Mailpit running in Docker. Done when: emails arrive in Mailpit, and simulated failures are retried or marked dead correctly.

4. 04

   Survive restarts and limit the rate

   ~2h

   On startup, return jobs stuck in sending with an expired lease to the queue. Limit sending to N emails per second overall and per recipient domain (with a token bucket), and run a configurable number of workers. Make sure a job is never marked sent twice or sent twice after a crash as far as possible, and document the remaining risk (the email sent but the process crashing before recording it). Done when: killing the service mid-sending loses no jobs, and the rate limit holds.

5. 05

   Build the dashboard

   ~2h

   Build a React dashboard with Vite showing counts per status, a searchable list of emails with their status, attempts and last error, the details of one email with its full history, and buttons to retry dead emails. Protect it with a login or the API key. Done when: the dashboard shows live statuses and can retry dead emails.

6. 06

   Add observability

   ~1h

   Log each attempt with the job id, attempt number, duration and result (never the email body), and expose metrics: emails queued, sent and failed per minute, the queue backlog and the age of the oldest queued email. Done when: the metrics show the service's health.

7. 07

   Test it

   ~2h

   Write tests with a fake transport (or Mailpit's API): validation, idempotency, success, temporary and permanent failures, retries with backoff (using fake timers), recovery after a restart, and rate limiting. Done when: all tests pass.

Resources

• DocsNodemailer documentation
• DocsMailpit: email testing tool
• DocsRFC 5321: SMTP (reply codes)
• ArticleExponential backoff and jitter (AWS)
• DocsVite: getting started