Email Notification System

Email is cheap, durable, and universal. It is also slow, messy, and full of deliverability traps. A production email system is not just an API call to SendGrid.

Email Categories

Category          Example                 User Can Opt Out
Transactional     invoice, order receipt   usually no
Security          password changed         no
Product activity  mention, comment         often yes
Marketing         newsletter, offers       yes

The category determines template tone, unsubscribe behavior, and compliance rules.

Send Flow

Worker
  |
  v
Load recipient and preferences
  |
  v
Load email template
  |
  v
Render subject and HTML
  |
  v
Spam and variable validation
  |
  v
SendGrid or SES
  |
  v
Store provider message id

Template Rendering

function renderEmail(template: string, variables: Record<string, string>) {
  return template.replace(/\{\{(\w+)\}\}/g, (_, key) => {
    const value = variables[key];
    if (!value) {
      throw new Error(`Missing email variable: ${key}`);
    }
    return escapeHtml(value);
  });
}

Always escape user-controlled values. An order name, company name, or comment excerpt can contain unsafe text.

MJML and Responsive HTML

Raw HTML emails are painful because email clients behave differently. MJML lets you write a higher-level template and compile it to email-safe HTML.

MJML template
  |
  v
Compiled HTML
  |
  v
Provider payload

Store the source template and compiled output version. That makes debugging easier when Gmail renders differently than Outlook.

Attachments and Images

Invoices may require PDF attachments. Marketing may use images. Both create risk.

Rules:

1. Keep attachment size limits.
2. Generate files before enqueue or store a signed URL.
3. Do not attach sensitive files without access control.
4. Use CDN-hosted images for heavy content.
5. Include useful alt text.

Tracking Pixel

A tracking pixel is a tiny image URL embedded in the email. When the email client loads it, your system records an open event.

<img src="https://api.example.com/email/open/msg_123.png" width="1" height="1" />

This is imperfect. Apple Mail and privacy tools may preload or block pixels. Treat open rate as directional, not absolute truth.

Provider Webhooks

Providers send events:

delivered
bounced
opened
clicked
complained
unsubscribed

Verify webhook signatures before trusting them.

function verifyWebhook(signature: string, body: string, secret: string) {
  const expected = hmacSha256(body, secret);
  return timingSafeEqual(signature, expected);
}

Deliverability Basics

1. Configure SPF, DKIM, and DMARC.
2. Use a verified sending domain.
3. Keep bounce rate low.
4. Separate transactional and marketing sending pools.
5. Avoid deceptive subjects and spam-heavy wording.

Common Mistakes

1. Sending marketing mail from the same domain reputation as critical invoices.
2. Ignoring bounce and complaint webhooks.
3. Rendering templates without escaping values.
4. Attaching large PDFs directly.
5. Using open rate as exact truth.

Interview Questions

1. Why is provider accepted different from delivered?
2. What are SPF, DKIM, and DMARC?
3. Why should templates be versioned?
4. How would you process bounce events?

Exercise

Design the email flow for an invoice notification. Include template, attachment generation, provider send, webhook update, and retry policy.