Changing the emails your product sends: new domains, redesigns, and the phishing problem

Somewhere in your product is a folder of email templates nobody thinks of as a public interface: the receipt, the password reset, the weekly digest, the alert that pages someone at 3am. Then one quarter you rebrand the templates, or move sending from mail.acme.com to notify.acmehq.com, and you discover what those emails actually were: an interface with three kinds of consumers, every one of which you just broke silently.

Products announce API changes, UI changes, even policy changes — and change the emails they send with no announcement at all. This guide is about treating your outbound email like the interface it is: what counts as a breaking change, why the announcement itself is uniquely hard (it looks exactly like the attack your users were trained to spot), and what to publish where.

Three readers of every email you send

  • The human pattern-matcher. Years of security-awareness training taught your users one heuristic: an email that suddenly looks different is suspicious. Different sender, different design, different tone — that’s the phishing checklist. Your users don’t read your emails so much as recognize them; change the pattern and you spend trust, whether or not anything else changed.
  • Inbox infrastructure. Filters that file by from-address. Rules that forward invoices to accounting. VIP lists, vacation responders, and — highest stakes — the regex in an alert-routing tool that turns your monitoring email into a page for the on-call engineer. None of this is visible to you, all of it keys on your sender address and subject format, and all of it fails silently when you change them.
  • Machine parsers. Expense tools ingest your receipts. Bookkeeping software reads your invoices. Zapier email triggers, ticketing systems that convert mail to tickets, scripts that scrape order confirmations. Your email body is these tools’ API response, and a template redesign is a response-shape change you never announced.

Once you see the three readers, the rule follows: changes to sender, subject format, or template structure are breaking changes, and the breaking-change playbook — announce ahead, give dates, say exactly what to do — applies to email like anything else.

The sending-domain change is your highest-stakes migration

Moving to a new sending address or domain is the email equivalent of moving your API to a new hostname — except the failure mode is worse. A missed API migration returns errors someone sees. A missed email migration just… delivers less. Filters stop matching, messages drift to spam, and — the death spiral — confused users who do see the unfamiliar sender report it as spam, teaching every mailbox provider that your brand-new domain with no reputation is a spammer. That verdict takes months to appeal.

So run it like a migration, not a switch:

  • Announce before anything changes, from the old address. The one message guaranteed to reach the readers who filter on your old sender is the last one sent from it. State the new address exactly, in plain text they can copy into a filter or allowlist, and the date the change happens.
  • Give a window, not a day. Sending-domain reputation is warmed gradually; your ESP will ramp traffic on the new domain over weeks. Say so: “between March 3 and March 31, emails will arrive from the new address” beats a precise date that’s wrong for half your users.
  • Keep the old address alive. Monitored, forwarding, and — if it ever sent security-relevant mail — never re-registrable by someone else. Sunsetting a domain that used to send your password resets is a sunset announcement with a security dimension.
  • Tell users what to update, concretely. “If you have a rule that files our invoices, it matches the sender — add the new address to it” does more than any paragraph of reassurance. Write it per the plain-language rules: most people who filter email don’t think of themselves as having built an integration. They have.

The announcement that looks like phishing

Here is the paradox that makes email changes unlike every other change you announce: “we’re changing our emails” is itself a phishing template. Attackers send exactly this — new domain, new look, please trust it — because it pre-legitimizes the fake mail that follows. Your genuine announcement is indistinguishable from the attack it enables, and your most security-conscious users will (correctly!) refuse to trust it.

You cannot fix that inside email. You fix it by giving the announcement a home outside the channel being changed:

  • A dated changelog entry is the verification surface. Suspicious user gets the email, types your domain by hand, finds the entry saying the same thing — now it’s true. This only works if the entry exists before the first email lands and lives at a stable permalink your support team can send to everyone who asks “is this really you?” — and they will ask. That’s the system working.
  • An in-product notice closes the loop. A line on the settings or notifications screen — inside the product the user already trusts — outranks anything you can put in an inbox.
  • Make the announcement email demand nothing. No login link, no “verify your account,” no urgency. The email that says “you don’t need to do anything; details are on our site — navigate there yourself” reads as legitimate precisely because a phisher can’t profit from it.

Redesigns read as phishing too

A visual redesign keeps the sender but breaks the recognition pattern — and pattern recognition is how humans authenticate email. Banks learned this decades ago; it’s why they announce redesigns of their statements. Three rules transfer:

  • Show the new template before it ships. A screenshot in the announcement entry — per the screenshot rules, of the actual template, not a marketing mock — turns “unfamiliar email” into “the redesign they showed me.”
  • Change templates in one release, not a drip. A months-long rolling redesign means months of “some of their emails look different” — the exact condition that trains users to stop noticing inconsistency. That skill protects them; don’t erode it.
  • Brief support before the first send. The “is this email legit?” tickets are not noise to deflect — they’re users doing security right. Support should confirm quickly and link the entry, per the release-comms checklist.

Subject lines and headers are API

The least visible breaking change in email is a subject-format change. Somewhere, a rule matches your [Acme] prefix; an on-call tool’s regex extracts the alert severity from your monitoring subjects; an accounting inbox files anything matching “Invoice #”. Reformat the subject and those rules don’t error — they just stop matching, which for an alert-routing rule can mean a page that never fires.

  • Treat machine-consumed subjects as versioned strings. Alert and notification subjects deserve the discipline of a schema change: announce the old and new formats side by side, with a date, ahead of time.
  • Keep a stable token when you must reformat. An invariant like an alert ID or a [acme] tag that survives the redesign gives every downstream regex something to hold onto.
  • Threading is a header contract too. Mail clients thread on Message-ID and References; ticketing systems dedupe replies with them. Changing how your reply chains set headers scatters existing threads — worth a line in the entry even though almost nobody will know to ask.

Receipts and invoices are documents with dependents

Transactional documents — receipts, invoices, statements — have the most machine readers and the most rigid ones. Expense tools were taught your layout by example; the totals line, the tax field, the order number are all positional. Changes that feel cosmetic from inside (“we moved the VAT line into the summary table”) are parser breakage outside. Two habits help:

  • Announce document-structure changes as such. “Receipt emails have a new layout starting June 1; the order number, totals, and tax fields are all still present — here’s a sample” is enough for a vendor’s parser team to act on. A linked sample of the new document is the changelog equivalent of an example API response.
  • Never drop the plain-text part silently. The text/plain alternative is what the oldest and most brittle parsers — and some accessibility setups — actually read. If a redesign rebuilds it (or, worse, reduces it to “view this email in a browser”), that’s a breaking change to the interface’s most-compatible format, and it belongs in the entry.

Preference and cadence changes count too

The settings that govern email are part of the interface. Splitting one “notifications” toggle into three, merging categories, changing a digest to instant sends — each changes what arrives in inboxes without any template changing at all. The rules:

  • Publish the mapping. “If you had X off, the new Y and Z default to off” — the same explicit old→new table you’d publish for a rename. Users should never have to re-derive their own preferences.
  • New categories default to the old setting’s spirit, not to on. A category split that quietly opts everyone into a new stream is how products end up in spam-filter training data. If a new stream is genuinely new, it launches opt-in, announced in the changelog — not pre-checked.
  • Cadence is a promise. People who chose a weekly digest chose weekly. Making it daily — or folding marketing content into a transactional stream, the classic list-burning move — is a unilateral change to an agreement, and reads that way.

The announcement entry

A sending-domain change entry, as a template:

Our emails are moving to notify.acmehq.com

Starting March 3, emails from Acme will arrive from
no-reply@notify.acmehq.com instead of mail@acme.com.
The change rolls out gradually and completes by March 31.

What this means for you:
- Nothing, for most people. Same emails, new address.
- If you have inbox rules or filters that match
  mail@acme.com, add no-reply@notify.acmehq.com to them.
- If your company allowlists senders, forward this entry
  to your IT team.

What stays the same: email content, your notification
settings, and reply handling. mail@acme.com remains ours
and forwards to the new address indefinitely.

Security note: this entry is the authoritative statement
of the change. We will never email you asking to click a
link to “re-verify” because of this migration. When in
doubt, type acme.com into your browser and check this page.

Note what the template does: exact addresses in copyable plain text, a window not a day, the nothing-required reassurance, the IT-team escape hatch, and the entry positioning itself as the verification surface.

Six anti-patterns

  • The silent sender switch. New domain, no announcement. Deliverability craters, spam reports pile up, and the domain’s reputation is poisoned during the one window — its first weeks — when reputation is decided.
  • Announcing the email change only by email. The one channel guaranteed to be unreliable during the change — and indistinguishable from phishing about it. The canonical announcement lives on your site; email points at it.
  • The dripped redesign. Templates restyled one by one over a quarter, training users that inconsistent-looking email from you is normal. That lesson is a gift to whoever phishes them next.
  • Subject reformats with no stable token. Every downstream regex breaks at once, silently, including the ones that page humans about outages.
  • “Check your spam folder” as the migration plan. If your plan for the transition is users rescuing your mail from spam, you’ve outsourced your deliverability migration to your customers.
  • The pre-checked new category. A preferences “improvement” that enrolls everyone in a stream they never chose. The unsubscribe link it earns doesn’t distinguish the new stream from the emails they actually wanted.

Running email-change announcements on Wakelog

The load-bearing artifact in every section above is the same thing: a dated entry at a stable permalink that exists before the first changed email lands. That’s what Wakelog provides: write the entry as a draft, schedule it with publish_at so it goes live the moment the ramp starts, tag it announcement (or breaking for the subject-format change your integrators’ regexes depend on), and hand support the permalink for every “is this really you?” ticket. The RSS and JSON feeds give the vendors who monitor your changelog — including the expense-tool team that parses your receipts — a tripwire that fires before their parser breaks. The honest boundary: Wakelog doesn’t send your email or warm your domain — it’s the public, dated receipt that the change was real, announced, and yours.

Start your changelog — free   Next: product update emails →

Related guides

Last updated 2026-08-02 · All guides