Transactional Email Catalog

This chapter answers one practical question: which transactional emails does your app need, and what must each one contain? It is a working reference. Use it to decide which emails to build, when to send each one, and what content is required.

This guide includes general information, not legal advice. Where email content touches compliance (for example, what counts as "promotional"), confirm the current rules for your markets with a qualified professional.

Quick answers:

• Which three emails does almost every app need? Verification, password reset, and a non-promotional welcome.
• How do I scope my email system fast? Find your app type below, copy its "Essential" list into your backlog.
• What does each email need? Look it up in the full catalog: when to send, purpose, required content, best practices.
• When is a "feature announcement" transactional? Only when the change forces the user to act. Otherwise it is marketing.
• Where do these messages go reputationally? Almost all transactional mail should leave from a dedicated transactional subdomain that never carries marketing, see Sending Reliability for the subdomain split and warm-up.

How do I use this chapter?

The catalog has two halves. Read them in order:

1. Email combinations by app type. A fast way to scope your email system. Find the app type closest to what you are building and start from its "Essential" list.
2. Full email catalog. The detailed specification for every email referenced above: when to send it, its purpose, required content, and best practices.

A practical workflow: pick your app type, copy its Essential list into your backlog, then look up each email in the full catalog to define its content. The "Optional" items are good candidates for a second iteration.

Universal baseline: almost every app needs email verification, password reset, and a non-promotional welcome email. If you build nothing else, build these three first.

What does "transactional" actually mean for this catalog?

Every email in this catalog shares one property: it is triggered by a specific action or state change tied to one recipient, and the recipient expects it because of something they did. That property is what keeps these messages out of bulk-sender consent and unsubscribe obligations in most jurisdictions, and it is what lets them be sent without prior marketing opt-in. The moment a message stops being a one-to-one consequence of the recipient's own action and starts being a broadcast you decided to send, it is marketing, regardless of the subject line. The boundary, the legal tests behind it, and the grey-zone cases (receipts with cross-sells, "we miss you" emails, double opt-in confirmations) are worked out in detail in Email Types: Transactional vs Marketing and Compliance. This chapter assumes you have internalized that line; if you have not, read those two first.

One consequence matters for everything below: a purely transactional message is exempt from the one-click unsubscribe requirement (RFC 8058) that February 2024 bulk-sender rules impose on marketing, but the exemption is narrow and fragile. Add a single promotional element, a discount banner, a "you might also like" block, a referral nudge, and a regulator or a mailbox provider's filter can reclassify the whole message as marketing, at which point the missing List-Unsubscribe header becomes a compliance gap and the message drags your marketing complaint rate up. The safest engineering posture is to keep transactional streams ruthlessly clean and put every promotional element on the marketing stream covered in Marketing Emails.

Which transactional emails does my app need?

Use the combinations below as a starting point based on what you are building. Each one lists the emails you should treat as Essential (build first) and Optional (build in a later iteration), plus why that mix fits the app type.

What does an authentication-focused app need?

This covers apps where user accounts and security are core: login systems, identity providers, account management.

Essential:

• Email verification
• Password reset
• OTP / 2FA codes
• Security alerts (new device, password change)
• Account update notifications

Optional:

• Welcome email (must not be promotional)
• Account deletion confirmation

Why this mix: for an identity product, the emails are the product surface. Security alerts and 2FA codes carry the trust that everything else depends on, so they get top priority and the cleanest deliverability. Send them from a dedicated transactional subdomain that never carries marketing.

What does a newsletter or content platform need?

This covers apps focused on content delivery and subscriptions.

Essential:

• Email verification
• Password reset
• Welcome email (must not be promotional)
• Subscription confirmation

Optional:

• OTP / 2FA codes
• Account update notifications

Why this mix: the subscription confirmation is the transactional anchor. The actual content emails are marketing and live on a separate subdomain with full consent and one-click unsubscribe handling. Do not blur the two, or a complaint about the newsletter will damage the reputation of your password-reset mail.

What does an e-commerce or marketplace app need?

This covers apps where users buy products or services.

Essential:

• Email verification
• Password reset
• Welcome email (must not be promotional)
• Order confirmation
• Shipping notifications
• Invoice / receipt
• Payment failed notices

Optional:

• OTP / 2FA codes
• Security alerts
• Subscription confirmations (for recurring orders)

Why this mix: each purchase generates a chain of expected emails: confirm, charge, ship. Missing any link generates support tickets and chargebacks, so this category has the longest essential list. The confirm-charge-ship chain is the minimum; abandoned-cart and review-request emails are marketing and belong on a separate stream.

Marketplace addendum. A marketplace has two parties per transaction, and each needs its own thread. A buyer gets order confirmation, shipping, and receipt; a seller gets a "you have a new order" notification, a "payout sent" notification, and dispute/refund alerts. Treat the seller stream as a distinct set of transactional templates with their own triggers, do not bolt seller notices onto buyer templates. Payout notifications in particular are financial records and follow the invoice/receipt rules below.

What does a SaaS or subscription service need?

This covers apps with paid subscription tiers and ongoing billing.

Essential:

• Email verification
• Password reset
• Welcome email (must not be promotional)
• OTP / 2FA codes
• Security alerts
• Subscription confirmation
• Subscription renewal notice
• Payment failed notices
• Invoice / receipt

Optional:

• Account update notifications
• Feature change notifications (for breaking changes)
• Seat / team invitation emails
• Trial-ending notices (transactional only when a charge or downgrade follows automatically)

Why this mix: recurring billing means recurring transactional touchpoints. Renewal notices and payment-failed flows directly protect revenue. A failed-payment email that lands in spam often becomes an involuntary churn, so deliverability on the billing stream is a revenue metric, not a vanity one.

On trial-ending notices: "Your trial ends in 3 days" is transactional when the trial converts to a paid plan automatically (the user must act to avoid a charge) and marketing when it does not (nothing happens to the user's account if they ignore it, you are just trying to convert them). Same subject line, opposite classification, decided entirely by what happens if the user does nothing.

What does a financial or fintech app need?

This covers apps handling money, payments, or sensitive financial data.

Essential:

• Email verification
• Password reset
• OTP / 2FA codes (required for sensitive actions)
• Security alerts (all types)
• Account update notifications
• Transaction confirmations
• Invoice / receipt
• Payment failed notices

Optional:

• Welcome email (must not be promotional)
• Compliance notices

Why this mix: fintech combines the strictest security posture with a regulatory paper trail. Every money movement and account change should generate a confirmation the user can audit later. Keep these records consistent and searchable, because users and regulators may request them years after the fact.

What does a social or community platform need?

This covers apps focused on user interaction and community features.

Essential:

• Email verification
• Password reset
• Welcome email (must not be promotional)
• Security alerts

Optional:

• OTP / 2FA codes
• Account update notifications
• Activity notifications (mentions, replies)

Why this mix: activity notifications can drive engagement, but be careful. Batch them and make them easy to control, or they tip into feeling like marketing and generate complaints. Give users granular preferences (per type, plus a daily-digest option) so the notifications stay wanted.

Activity notifications are the hardest classification call in this catalog. A direct, person-to-person event the recipient opted into (a reply to your comment, a DM, a mention) is defensibly transactional. A "people you may know" or "trending in your network" digest is marketing dressed as a notification. When in doubt, give every activity-notification type a List-Unsubscribe/List-Unsubscribe-Post header (RFC 8058) and honor it even though the message is nominally transactional, the cost is one header, and it inoculates you if a mailbox provider's classifier disagrees with yours. See List Management for how to model these granular preferences.

What does a developer tools or API platform need?

This covers apps targeting developers with API access and integrations.

Essential:

• Email verification
• Password reset
• OTP / 2FA codes
• Security alerts
• API key notifications (creation, expiration)
• Subscription confirmation
• Payment failed notices

Optional:

• Welcome email (must not be promotional)
• Usage alerts (approaching limits)
• Feature change notifications
• Webhook-delivery failure alerts

Why this mix: developers depend on operational signals. An expiring API key or an approaching rate limit that silently fails to email can break a customer's production system. Send usage and key-expiry alerts with enough lead time (for example, 30, 7, and 1 days before an API key expires) so the customer can rotate keys without downtime.

On webhook-delivery failure alerts: if your platform delivers webhooks to your customers, a sustained delivery failure is an operational emergency for them and an email is warranted. Send it once per failing endpoint per incident window, not once per failed delivery, or a single down endpoint will generate thousands of emails and torch your reputation. The events that drive these emails are the same ones you consume when you receive provider webhooks; see Webhooks and Events for the consumer side.

What does a healthcare or HIPAA-compliant app need?

This covers apps handling protected health information (PHI).

Essential:

• Email verification
• Password reset
• OTP / 2FA codes (required)
• Security alerts (all types, detailed)
• Account update notifications
• Appointment confirmations

Optional:

• Welcome email (must not be promotional)
• Compliance notices

Note: healthcare apps have strict requirements. Emails should contain minimal PHI and link to secure portals for sensitive information.

Practical rule for healthcare: treat the email body as public. Never put diagnoses, test results, or other PHI in the email itself. Send a neutral notification ("You have a new message") and require the user to log in to a secure portal to view details. Standard email is not an encrypted-in-transit guarantee even with MTA-STS (RFC 8461) and DANE, because you cannot prove every hop enforced TLS; assume any value placed in the body could be read by an intermediary.

How do the essential sets compare at a glance?

What if my app spans two types? Most products do (a fintech app is also a SaaS, a marketplace is also social). Take the union of the essential lists, then resolve conflicts toward the stricter rule: if either type requires OTP/2FA, build it; if either handles PHI, apply the healthcare portal rule everywhere.

How critical is each email, and what does that imply for engineering?

Not every transactional email deserves the same engineering effort. Use a tier model to decide where idempotency, retries, latency budgets, and a dedicated IP pool are worth the cost. The retry and idempotency mechanics for each tier live in Sending Reliability; this table is the routing decision.

The practical lesson is that Tier 0 and Tier 1 deserve their own sending identity and their own monitoring, and Tier 3 should never share infrastructure with them. A noisy notification stream that earns spam complaints must not be able to poison the reputation that delivers a password reset.

Full Email Catalog

This is the per-email reference. Each entry below specifies when to send, the purpose, the content it should include, and best practices. Treat the content lists as minimum requirements, not a ceiling.

A note on the code in this section. Examples use a provider-neutral emailClient abstraction and Node's standard library. They are deliberately not coupled to any one email service provider (ESP). Concrete ESPs, Amazon SES, Postmark, SendGrid, Mailgun, Resend, Brevo, SparkPost, Mandrill, are named only as interchangeable examples; nothing here assumes you picked any of them. A minimal version of the abstraction looks like this:

// provider-neutral interface; back it with whatever ESP or SMTP relay you use
export interface EmailClient {
  send(message: {
    to: string;
    from: string;
    subject: string;
    html: string;
    text: string;
    headers?: Record<string, string>;
    // idempotencyKey lets the transport collapse duplicate sends; see 09-sending-reliability.md
    idempotencyKey?: string;
  }): Promise<{ messageId: string }>;
}

Authentication and security emails

When and how do I send an email verification?

When to send: immediately after the user signs up or changes their email address.

Purpose: verify that the email address belongs to the user.

Content should include:

• Clear verification link or code
• Expiration time (typically 24 to 48 hours)
• Instructions on what to do
• Security notice if the link is clicked by mistake

Best practices:

• Send immediately (within seconds)
• Include an expiration notice
• Provide a resend option
• Link to support if there are issues

Why it matters: verification proves you can actually reach the user and protects you from typo'd and fraudulent addresses that quietly destroy sender reputation. An unverified address is a liability on every future send. Verifying at signup is the single cheapest way to keep your bounce rate low.

Worked example, generating and storing a verification token. Generate a high-entropy token, store only its hash, and put the raw token in the link. Never store the raw token; if your database leaks, hashed tokens are useless to an attacker.

import { randomBytes, createHash } from "node:crypto";

function createVerificationToken() {
  const raw = randomBytes(32).toString("base64url"); // 256 bits of entropy
  const hash = createHash("sha256").update(raw).digest("hex");
  const expiresAt = new Date(Date.now() + 24 * 60 * 60 * 1000); // 24h
  // persist { userId, hash, expiresAt, usedAt: null }
  return { raw, hash, expiresAt };
}

// the link carries the RAW token; lookup verifies by hashing the incoming value
function verificationUrl(raw: string) {
  return `https://app.example.com/verify?token=${raw}`;
}

Edge cases and failure modes:

• Email change, not signup. When a user changes their address, send the verification to the new address but keep the old address active until the new one is confirmed. Do not switch the address of record until verification succeeds, or a typo locks the user out.
• Resend abuse. Rate-limit resends (for example, one per 60 seconds, with an exponential cooldown) so the endpoint cannot be used to mail-bomb a third party. Re-issuing a token should invalidate the previous one.
• Click-by-bots. Corporate security gateways and link scanners "click" links to inspect them, which can consume a single-use verification token before the human ever sees it. For verification, prefer a token that survives a GET preview and only commits state on an explicit confirmation action, or use a short numeric code the scanner cannot trigger.
• Hard bounce on verification. If the verification email hard-bounces, the address is bad, surface that in-product immediately ("we couldn't reach that address") rather than leaving the user staring at an empty inbox. Suppress the address per List Management.

What goes into an OTP / 2FA code email?

When to send: when the user requests a two-factor authentication code.

Purpose: provide a time-sensitive authentication code.

Content should include:

• The OTP code (clearly displayed)
• Expiration time (typically 5 to 10 minutes)
• Security warnings
• Instructions on what to do if not requested

Best practices:

• Send immediately
• The code should be large and easy to read
• Include the expiration prominently
• Warn about sharing codes
• Provide an "I didn't request this" link

Why it matters: OTP emails are the most latency-sensitive mail you send. A code that arrives after it expires is worse than useless. They are also a phishing target, so the copy must actively discourage code sharing. Never put the code in a clickable link, and never include marketing in the same message.

Engineering specifics:

• Put the code in the subject line as well as the body (123456 is your verification code). Users read it from the notification without opening the message, which is faster and removes a phishing surface.
• Latency budget. This is a Tier 0 send. Aim for inbox delivery in single-digit seconds. If your queue can ever delay, OTP must bypass it on a fast path, or you must offer an alternative channel (authenticator app, SMS). Email OTP is the weakest common second factor precisely because of delivery latency and inbox compromise, treat it as a fallback, not a primary, where security matters.
• Code format. 6 digits is the convention; balance entropy against rate-limiting. A 6-digit code is only ~20 bits, so it is only safe with strict attempt limits (for example, 5 tries then lock) and short expiry.
• Never reflect the code in a link. A link containing the code can be previewed by scanners and leaks the secret into logs and Referer headers.

import { randomInt } from "node:crypto";

function generateOtp(): string {
  // randomInt is CSPRNG-backed; Math.random is NOT acceptable for codes
  return randomInt(0, 1_000_000).toString().padStart(6, "0");
}

What does a password reset email need?

When to send: when the user requests a password reset.

Purpose: allow the user to securely reset a forgotten password.

Content should include:

• Reset link (with token)
• Expiration time (typically 1 hour)
• Security warnings
• Instructions if not requested

Best practices:

• Send immediately
• The link expires quickly (1 hour)
• Include IP address and location if available
• Provide an "I didn't request this" link
• Do not include the old password

Why it matters: a reset link is a temporary key to the account. Short expiry and a "wasn't me" path limit the blast radius if the message is intercepted or sent to the wrong person. Never email the existing password. Store passwords hashed, so you could not even if you wanted to. Invalidate the token the moment it is used or expires, whichever comes first.

Security details that are frequently missed:

• Account enumeration. The reset endpoint must return the same response whether or not the address exists ("If an account exists for this address, we've sent a reset link"). Differing responses, or differing timing, let an attacker enumerate which addresses are registered.
• Single-use, server-side invalidation. Mark the token usedAt atomically on first use. A token reused after a successful reset must fail. Expire all other outstanding reset tokens for that user when one is consumed.
• Invalidate sessions on reset. After a successful password change, revoke existing sessions and refresh tokens. A reset that leaves the attacker's session alive defeats the purpose.
• Link scanners again. As with verification, security gateways may pre-fetch the reset link. Commit the password change only on an explicit POST from the reset form, never on the GET that renders it.

When should I send a security alert?

When to send: when security-relevant events occur (login from a new device, password change, and similar).

Purpose: notify the user of account security events.

Content should include:

• What happened (clear description)
• When it happened
• Location / IP if available
• Action to take if suspicious
• Link to security settings

Best practices:

• Send immediately
• Be clear and specific
• Include actionable steps
• Provide a way to report suspicious activity

Why it matters: security alerts are often the user's first and only warning that their account is compromised. Specificity ("New sign-in from Chrome on Windows in Warsaw") lets a user instantly tell a real event from an attack. Vague alerts ("Your account was accessed") train users to ignore them, so include the device, browser, time, and location every time.

Which events warrant an alert:

Common mistakes: sending the change-of-email alert only to the new address (the attacker controls it), and including a one-click "revert" link that itself becomes an attack vector if the message is forwarded. Make the recovery path require authentication.

Account management emails

What should the welcome email contain?

When to send: immediately after successful account creation and verification.

Purpose: welcome new users and guide them to next steps. It must not be promotional.

Content should include:

• Welcome message
• Key features or next steps
• Links to important resources
• Support contact information

Best practices:

• Send after email verification
• Keep it focused and actionable
• Do not overwhelm with information
• Set expectations about future emails

Why it matters: the welcome email is your highest-engagement message. Open rates peak right after signup. Use that attention to drive activation, not to sell. Adding offers turns a transactional welcome into marketing and forfeits its legal footing, so one clear next step beats five product pitches.

The boundary you must not cross. "Here's how to get started, and here's our support address" is transactional. "Welcome, here's 20% off your first order and our latest features" is marketing, and sending it from your transactional stream without consent and a List-Unsubscribe header (RFC 8058) is exactly the kind of blur that gets a whole stream reclassified. If you want to onboard and nurture, send a clean transactional welcome and trigger a separate, consented onboarding sequence on the marketing stream described in Marketing Emails.

When do I send account update notifications?

When to send: when the user changes account settings (email, password, profile, and so on).

Purpose: confirm account changes and provide a security notice.

Content should include:

• What changed
• When it changed
• Action to take if unauthorized
• Link to account settings

Best practices:

• Send immediately after the change
• Be specific about what changed
• Include a security notice
• Provide an easy way to revert if needed

Why it matters: these notifications are a safety net against account takeover. If an attacker changes the recovery email, the old address still receives the alert and the real owner can react. For email changes specifically, notify both the old and the new address.

Edge cases: do not leak the new value in an alert sent to the old address ("your email was changed to attacker@evil.com" tells the attacker the alert fired and confirms the takeover succeeded). Say "your email address was changed" and direct the recovery action through an authenticated flow. Batch low-risk profile edits if a user makes several in a session, so one settings tweak doesn't generate five emails.

E-commerce and transaction emails

What goes into an order confirmation?

When to send: immediately after the order is placed.

Purpose: confirm order details and provide a receipt.

Content should include:

• Order number
• Items ordered with quantities
• Pricing breakdown
• Shipping address
• Estimated delivery date
• Order tracking link (if available)

Best practices:

• Send within minutes of the order
• Include all order details
• Make it easy to print or save
• Provide a customer service contact

Why it matters: the order confirmation is the customer's proof of purchase and your single biggest deflector of "did my order go through?" support tickets. It is also the most-opened commerce email, which is exactly why it must stay free of upsells to remain transactional.

Idempotency is mandatory here. Order confirmation is a Tier 1 send. If your checkout webhook or queue retries, you must not send two confirmations for one order. Key the send on the order ID so a duplicate trigger is a no-op:

async function sendOrderConfirmation(order: Order, emailClient: EmailClient) {
  await emailClient.send({
    to: order.customerEmail,
    from: "orders@txn.example.com", // dedicated transactional subdomain
    subject: `Order ${order.number} confirmed`,
    html: renderOrderHtml(order),
    text: renderOrderText(order),
    // collapses duplicates if the order-placed event is delivered more than once
    idempotencyKey: `order-confirmation:${order.id}`,
  });
}

The retry semantics and exactly-once concerns behind that key are covered in Sending Reliability, and the upstream event that triggers it is the kind of payment webhook handled in Webhooks and Events.

When do I send shipping notifications?

When to send: when the order ships, with tracking updates.

Purpose: notify the user that the order has shipped and provide tracking.

Content should include:

• Order number
• Tracking number
• Carrier information
• Expected delivery date
• Tracking link
• Shipping address confirmation

Best practices:

• Send when the order ships
• Include the tracking number prominently
• Provide a carrier tracking link
• Update on major tracking milestones

Why it matters: once money has changed hands, the customer's anxiety shifts to "where is it?" Proactive shipping and milestone updates reduce inbound support volume and increase post-purchase satisfaction. The most useful milestones to email are "shipped," "out for delivery," and "delivered."

Failure modes: carrier webhooks fire duplicate and out-of-order events. Coalesce them, one "shipped" email, one "out for delivery," one "delivered", and key each on (orderId, milestone) so a re-delivered carrier event does not re-email the customer. A split shipment (two parcels for one order) needs one notification per parcel with a clear "1 of 2" indicator, not two identical "your order shipped" emails.

What does an invoice or receipt email need?

When to send: after payment is processed.

Purpose: provide payment confirmation and a receipt.

Content should include:

• Invoice / receipt number
• Payment amount
• Payment method
• Items / services purchased
• Payment date
• Downloadable PDF (if applicable)

Best practices:

• Send immediately after payment
• Include all payment details
• Make it easy to download / save
• Include tax information if applicable

Why it matters: receipts are records people keep for taxes, expense reports, and warranties. A stable invoice number and a downloadable PDF turn your email into a document the user can file and retrieve years later. Use a sequential, never-reused invoice number, because finance teams rely on it being unique.

What finance and tax actually require: depending on jurisdiction, a compliant invoice needs the seller's legal name and tax identifier, the buyer's details for business invoices, a unique sequential number, the issue date, a per-line and total breakdown, and the tax (VAT/GST) rate and amount shown separately. The email is a delivery mechanism; the PDF is the record. Generate the PDF once, store it, and let the user re-download it from their account, never regenerate-on-the-fly with a different number, because a number that changes between two downloads is a finance audit failure.

Subscription and billing emails

What does a subscription confirmation need?

When to send: when the user subscribes or changes their subscription.

Purpose: confirm subscription details and billing information.

Content should include:

• Subscription plan details
• Billing amount and frequency
• Next billing date
• Payment method
• Link to manage the subscription

Best practices:

• Send immediately after subscription
• Clearly state billing terms
• Provide an easy cancellation option
• Include a support contact

Why it matters: clear, upfront billing terms prevent the surprise charges that drive disputes and chargebacks. Telling people exactly when and how much you will bill, and how to cancel, builds the trust that keeps subscriptions alive.

Plan changes are distinct events. An upgrade, a downgrade, a proration, and a plan switch each deserve their own confirmation stating the new terms, the effective date, and any prorated charge or credit. Do not reuse the initial-subscription template, a user who downgrades and receives "Welcome to your subscription!" will be confused and may dispute the charge.

When do I send a subscription renewal notice?

When to send: before the subscription renews (typically 3 to 7 days before).

Purpose: notify the user of an upcoming renewal and charge.

Content should include:

• Renewal date
• Amount to be charged
• Payment method on file
• Link to update the payment method
• Link to cancel if desired

Best practices:

• Send with enough notice (3 to 7 days)
• Be clear about the amount and date
• Make it easy to update the payment method
• Provide a cancellation option

Why it matters: renewal notices are increasingly a legal requirement for auto-renewing subscriptions in several jurisdictions, and they reduce the "I forgot I was subscribed" chargebacks that hurt your payment-processor standing. For annual plans, more notice (for example, 14 to 30 days) is both safer legally and kinder to the customer.

Jurisdictional note: several jurisdictions now mandate advance renewal reminders and a cancellation path that is at least as easy as signup. Treat the renewal notice as a legal artifact, not just a courtesy, and confirm the specific lead-time and content requirements for your markets with a qualified professional, see Compliance. Send it far enough ahead that the customer can update an expiring card before the charge, which also reduces failed-payment volume.

How should I handle a payment failed notice?

When to send: when a subscription payment fails.

Purpose: notify the user of the payment failure and provide resolution steps.

Content should include:

• What happened
• Amount that failed
• Reason for failure (if available)
• Steps to resolve
• Link to update the payment method
• Consequences if not resolved

Best practices:

• Send immediately after the failure
• Be clear about the consequences
• Provide an easy resolution path
• Include a support contact

Why it matters: failed payments are the leading cause of involuntary churn. A fast, clear recovery email, part of a "dunning" sequence, directly recovers revenue that would otherwise be lost to an expired card. A typical dunning cadence retries and emails on day 0, day 3, and day 7, with a final notice before suspension.

Designing the dunning sequence:

Failure modes to handle: a "soft decline" (insufficient funds, temporary) deserves automated retries before you email aggressively, while a "hard decline" (card reported lost, account closed) will never succeed on retry and should ask for a new card immediately. Distinguish them from the gateway's decline code rather than treating every failure the same. Stop the sequence the instant the payment succeeds, a "your payment failed" email arriving after the customer already paid is a trust-destroying support ticket, so key the cancellation on the same subscription/invoice ID. This is the most deliverability-sensitive billing email; if it lands in spam the customer never recovers the card and you lose the revenue, so route it on your cleanest transactional identity (see Deliverability).

Notification and update emails

When is a feature announcement transactional, not marketing?

When to send: when a feature the user is actively using changes significantly.

Purpose: notify users of changes that affect their use of the service.

Content should include:

• What changed
• How it affects the user
• What action (if any) is needed
• Link to more information

Best practices:

• Only for significant changes
• Focus on user impact
• Provide clear next steps
• Link to documentation

Note: general feature announcements are marketing emails. Only send as transactional if the change directly affects an active feature the user is using.

Why it matters: this is the most easily abused category. The transactional label only applies when the change forces the user to act (a deprecated API, a removed setting). "Look at our cool new feature" is marketing. Sending it as transactional violates the user's trust and the law. A simple test: if the user does nothing and something breaks for them, it is transactional; if nothing breaks, it is marketing.

What about activity, mention, and digest notifications?

When to send: when a person-to-person event the user opted into occurs (a reply, a mention, a direct message), or on a fixed schedule for digests.

Purpose: bring the user back to relevant activity they asked to be notified about.

Content should include:

• Who did what (the specific actor and action)
• A direct link to the item
• A per-type preference / unsubscribe control

Best practices:

• Batch and coalesce. A burst of ten replies should produce one email, not ten.
• Respect quiet hours and per-type preferences (model these per List Management).
• Include List-Unsubscribe and List-Unsubscribe-Post (RFC 8058) even on nominally transactional notifications, because mailbox-provider classifiers may treat them as bulk.
• Offer a daily or weekly digest as the lower-frequency option.

Why it matters: activity notifications generate more spam complaints than any other "transactional" category, because users who feel spammed do not distinguish your reply-notification from marketing, they hit the complaint button, and February 2024 bulk-sender rules put your domain at risk above a 0.3% complaint rate. The defense is genuine user control and conservative defaults: opt in to high-frequency notifications, not out. Anything you cannot defend as person-to-person should move to the marketing stream entirely.

Cross-cutting requirements for every email in this catalog

These apply regardless of category. They are the parts engineers most often forget.

Authenticate every sending domain. Transactional mail still has to pass authentication or it lands in spam regardless of content. At minimum: SPF (RFC 7208), DKIM (RFC 6376), and DMARC (RFC 7489) with a policy that at least monitors, ideally enforces. Example records for a transactional subdomain:

# SPF (RFC 7208), TXT at txn.example.com; -all once you're sure all senders are listed
txn.example.com.  TXT  "v=spf1 include:_spf.your-esp.example -all"

# DKIM (RFC 6376), TXT at the selector your ESP gives you
sel1._domainkey.txn.example.com.  TXT  "v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQ..."

# DMARC (RFC 7489), published at the ORGANIZATIONAL domain, covers subdomains
_dmarc.example.com.  TXT  "v=DMARC1; p=reject; rua=mailto:dmarc@example.com; adkim=s; aspf=s"

Verify with dig:

dig +short TXT txn.example.com
dig +short TXT sel1._domainkey.txn.example.com
dig +short TXT _dmarc.example.com

The full authentication setup, including ARC (RFC 8617) for forwarded mail, MTA-STS (RFC 8461), TLS-RPT (RFC 8460), and BIMI for verified logos, is in Deliverability. SPF, DKIM, and DMARC are baseline for every sender; the additional February 2024 Gmail/Yahoo/Microsoft bulk-sender requirements (DMARC alignment, a spam-complaint rate under 0.3%, and RFC 8058 one-click unsubscribe on marketing) become mandatory once you send roughly 5,000 messages a day or more to a single mailbox provider.

Always send a plaintext alternative. Every message in this catalog must ship a text/plain part alongside the HTML. OTP and reset emails in particular are read in clients that strip HTML, and a missing text part hurts spam scoring.

Use a reply-able From address where the message invites a reply. no-reply@ is acceptable for OTP and automated alerts, but support and account emails should reach a monitored inbox. A no-reply on an email that says "contact us with questions" is a contradiction users notice.

Idempotency and stable identifiers. Tier 0 and Tier 1 sends must be idempotent on the triggering event ID so a retried webhook or requeued job does not double-send. Receipts, invoices, and orders must carry a stable, never-reused identifier. See Sending Reliability.

Honor suppressions. Even transactional mail must respect hard-bounce and complaint suppressions for the address, continuing to send to an address that bounces or complained damages your reputation for everyone. The exception handling and suppression model is in List Management.

Implementation checklist

• Identified the app type and copied its Essential list into the backlog
• Built the universal baseline first: verification, password reset, welcome
• Every transactional email is free of promotional content
• Security and OTP emails are sent immediately and expire appropriately
• Billing emails (confirmation, renewal, failure, receipt) cover the full lifecycle
• Healthcare/sensitive emails carry minimal PHI and link to a secure portal
• "Feature announcement" emails are only transactional when action is required
• Each email defines a stable identifier (order/invoice number) where relevant
• Tier 0/Tier 1 sends are idempotent on the triggering event ID
• Tokens are stored hashed, single-use, and short-lived; sessions are revoked on password reset
• Security alerts include device/IP/time/location and are sent to old + new address on email change
• Sending subdomain has SPF (RFC 7208), DKIM (RFC 6376), and DMARC (RFC 7489) verified with dig
• Every email ships a plaintext alternative
• Dunning sequence cancels the moment payment succeeds
• Activity notifications are batched, preference-controlled, and carry RFC 8058 unsubscribe headers

What should I read next?

• Email Types: Transactional vs Marketing: the underlying distinction these emails depend on
• Deliverability: making sure these emails actually reach the inbox
• List Management: suppressions, preferences, and modeling notification controls
• Transactional Email Design: how to write and structure the emails in this catalog
• Marketing Emails: where promotional onboarding and nurture sequences belong
• Compliance: legal requirements that shape transactional content
• Sending Reliability: idempotency and retries so critical emails always send
• Webhooks and Events: the upstream events that trigger many of these emails
• Index