Skip to content
Tutorials Center
My learning

Topics

Lesson 125 of 133 ยท Projects

Project: Email and Notification Service

Build a notification service in Node.js. Safe templates with HTML escaping, user preferences, multiple channels, a delivery queue with exponential backoff, dead letters and de-duplication.

Welcome emails, password resets, order confirmations, "your build failed" messages, SMS codes and push notifications all share one problem: your application wants to say "tell this user X", and a long list of things can go wrong between that wish and a message in someone's inbox. The mail server may be down, the address may not exist, the user may have unsubscribed, a retry may send the same message twice, and a slow provider may block the web request that asked for the notification.

In this project you build the core of a notification service that handles those problems in one place. Your application code will say notify(user, 'password-reset', { link }) and the service will render a template, check the user's preferences, queue one message per channel, send it with retries and exponential backoff, and move hopeless messages to a dead-letter list for a human to inspect.

Real email delivery needs an SMTP account and a library such as Nodemailer. Our editor has no network, so the transports here are stand-ins with the same shape as the real ones (send(message) that resolves or throws). Replace them with a Nodemailer, an SMS provider or a push gateway at the end, and the rest of the service stays unchanged.

Plan

  1. Templates: render subject, text and HTML from data, with HTML escaping by default.
  2. Preferences and channels: who wants what, and which types cannot be switched off.
  3. The queue: durable-style list of pending messages with attempts, due time, backoff and dead letters.
  4. The service: a facade that joins them and protects against duplicates.

Stage 1: templates that cannot inject HTML

A template is a string with placeholders. Two rules keep it safe and boring. First, {{value}} escapes HTML: if a user's name is <script>alert(1)</script>, the email shows those characters as text instead of running them. Triple braces {{{html}}} insert trusted markup unescaped and should be rare. Second, a placeholder with no value should fail loudly. A message that says "Hi , your order undefined has shipped" is worse than no message.

Node.js A tiny template engine with escaping and strict variables

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The script tag in the name came out as harmless text in the HTML version, the & in the URL became &amp; (which is correct inside an HTML attribute), and the footer, which we marked as trusted with triple braces, kept its tags. The missing-variable error stops a half-empty message from ever being queued. Production systems use a template library (Handlebars, MJML for responsive email layouts, or Nunjucks) with the same escaping rules; the idea carries over.

Escaping in HTML email protects the reader's mail client from injected markup. Never put unescaped user input into a Subject or other header either: a newline inside a header value lets an attacker add headers (such as extra recipients). Strip \r and \n from anything that ends up in a header.

Stage 2: preferences, channels and required messages

Users decide how they are contacted. A preference record says which channels are on, and which categories of message they want. Marketing messages need explicit consent and an unsubscribe path; transactional messages (password resets, receipts, security alerts) must always go out, because the user asked for them by performing the action. The rule is small, but it has legal weight in many countries, so it belongs in code, in one place.

Node.js Deciding which channels get a message

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Read the second and third lines: Ben opted out of the digest, so nothing is sent, but his password reset goes out anyway. Cy has no email address, so the email part of a required message is skipped, and the SMS goes out. The plan is data, not side effects: planDeliveries returns what would happen, which is easy to test and to show in an admin screen ("why did this user not get the email?").

Stage 3: a queue with retries, backoff and dead letters

Sending inside the web request is a mistake: if the mail server is slow, your page is slow, and if it is down, your request fails after the user already did the thing. Instead the request enqueues a message and returns at once, and a worker sends it. This is the same idea as the background job queue; here we build a compact in-memory version focused on delivery rules.

When a send fails, the right reaction depends on why:

  • A transient failure (timeout, 451 try again later, provider down) is worth retrying. Wait longer after each failure (exponential backoff: 1 s, 2 s, 4 s, ...) so a struggling provider can recover, and give up after a maximum number of attempts.
  • A permanent failure (invalid address, 550 mailbox does not exist) will never work. Retrying wastes time and can hurt your sender reputation, so the message goes straight to the dead-letter list.

The code takes now as a parameter instead of reading the clock, and sleep is not used at all: runDue(now) processes what is due at that moment. A test (or this lesson) can then "advance time" instantly.

Node.js Retries with exponential backoff and dead letters

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Follow message 1 (email): it failed at t=0 and t=1 s, then succeeded at t=3 s, after waits of 1 s and 2 s. Message 2 (SMS) failed four times with growing waits (1, 2 and 4 seconds) and was then moved to the dead letters because it ran out of attempts. Message 3 (push) failed with a permanent error and was dead on the first attempt, with no retry. The dead-letter list is the part people forget: without it, undeliverable messages vanish silently. In production you alert on its size and let a human fix the address and re-enqueue.

Backoff usually adds jitter, a small random amount, so that thousands of failed messages do not all retry at the same second and hammer the provider again. Add Math.random() * 0.2 * delay (use a seeded or injected random source in tests).

Stage 4: the service facade

Finally one function that the rest of your application calls. It does the work in order: validate and plan (stage 2), render (stage 1), de-duplicate, enqueue (stage 3). A de-duplication key protects against the same event producing two emails, for example when a checkout webhook is retried and your code runs twice (payment webhooks). Two requests with the same key within the window produce one set of messages.

In the final program, the transports write to an in-memory "outbox", a pattern that is also useful in tests: assertions check the outbox instead of a real mailbox.

Node.js The complete notification service

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Check the results: the duplicate login-77 produced nothing, Ben's opt-out blocked the digest but not the password reset, the missing count variable was caught while rendering (so nothing half-built was queued), and the newline injection in Ben's name was flattened in the subject line. The email transport failed once and the queue retried it at t=1000 ms. The messages reached the outbox once each.

Going to production

  • Real transports. For email use a library such as Nodemailer with an SMTP account or an API of a provider such as SES or Postmark; it implements send(message) for you. Use SPF, DKIM and DMARC records on your domain so mail is not marked as spam. For SMS and push use the provider's SDK or REST API.
  • Persistent queue. Store queued messages in a database table or Redis so a restart loses nothing; claim them atomically as in the job queue project.
  • Rate limits. Providers cap messages per second. A worker should never send faster than your plan allows.
  • Unsubscribe and bounces. Include a one-click unsubscribe link in marketing mail, process bounce and complaint webhooks, and stop sending to addresses that bounce.
  • Observability. Log every attempt with the message id (never the full body of personal messages), and alert when the dead-letter count or the queue age grows (Logging).
  • Idempotency. Keep the de-duplication keys in a database with an expiry, not in memory, so a restart cannot replay a notification.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why should a web request enqueue a notification instead of sending it directly?

    The user's action should not depend on a third-party service being fast and available. The queue decouples the two and lets a worker retry.
  2. 2. Which failure should go straight to the dead-letter list without retrying?

    A permanent failure will fail the same way every time. Retrying wastes time and can damage your sender reputation. Timeouts and "try again" replies are transient.
  3. 3. What is the purpose of exponential backoff?

    Each retry waits longer than the previous one. Together with jitter and a maximum number of attempts it spreads load and keeps one outage from becoming two.
  4. 4. Why does {{name}} escape HTML in the HTML version of an email?

    A name such as <script>...</script> would otherwise become markup. Escaping turns it into visible text.
  5. 5. A password-reset message is sent to a user who unsubscribed from marketing. Is that correct?

    Opt-outs apply to optional categories such as marketing. Messages the user needs for an action they started, like a password reset or a receipt, are required.

Summary

  • A notification service renders templates, applies preferences, queues messages per channel, sends with retries and keeps a dead-letter list.
  • Escape HTML by default, fail on missing variables and strip newlines from header values.
  • Required (transactional) messages ignore opt-outs; optional categories respect them. Planning is pure data and easy to test.
  • Retry transient failures with exponential backoff and a limit; send permanent failures straight to dead letters.
  • Use de-duplication keys, inject the clock, and test against an outbox. Swap in real transports (SMTP, SMS, push) and a persistent queue for production.

Next: Project: Cron-Style Task Scheduler