An email deliverability incident runbook is the written plan your team follows when delivery suddenly falls: bounces jump, mail sits in queues, complaints climb or customers say messages never arrive. Having the steps decided in advance matters because the first hour is when most of the damage is either contained or made worse. This guide gives us a practical runbook: a 30-minute triage, a decision table, evidence to collect, recovery steps, message templates, a review format and guardrails.
What counts as a deliverability incident
Not every dip is an incident. Normal traffic moves around with the calendar, the audience and the content. We call something an incident when a key measure leaves its normal range quickly and the cause is not obvious: bounce rate, deferral volume, complaint rate, delivery time for important messages, or inbox placement at a major mailbox provider. Reaching for the runbook early costs little. Waiting costs reputation.
Write down your severity levels in advance. A simple three-level scheme works well: a low-level watch item that one person monitors, a standard incident with a named lead and updates every hour, and a critical incident where transactional mail such as password resets or payment receipts is affected or a credential may be compromised. The definitions below are examples to adapt, not a standard.
| Level | Example trigger (tune to your traffic) | Response |
|---|---|---|
| Watch | One metric moves outside its usual range for a single send | Owner checks within the hour, notes findings |
| Incident | A metric doubles against its baseline, or one major provider defers or rejects a large share of mail | Open the runbook, name a lead, pause non-critical bulk, update stakeholders hourly |
| Critical | Transactional mail delayed or rejected, suspected compromised credentials, or a blocklist listing on a main sending IP or domain | Full runbook, all four roles staffed, update every 30 minutes until contained |
The first 30 minutes: triage and containment
The goal of the first half hour is not to find the root cause. It is to stop the damage from growing and to classify the problem well enough to know where to look. Work through these steps in order and record the time of each one.
- Minutes 0 to 5: declare. Open a shared channel, name the incident lead, write down the time the problem was first noticed and the time it probably began. Use UTC for every timestamp so logs, reports and people in different places line up.
- Minutes 5 to 10: protect transactional mail. Confirm that password resets, one-time codes and receipts are still being delivered by sending a few test messages to mailboxes you control at the major providers. If they are failing, treat the incident as critical.
- Minutes 10 to 15: pause or throttle the rest. Pause promotional campaigns, newsletters and any scheduled automation that can wait. For streams you cannot pause completely, lower the sending rate. Do not delete queued mail yet, because it is evidence.
- Minutes 15 to 25: classify. Read bounce, deferral and complaint counts by mailbox provider for the last day, compared with the previous week. Use the decision table below to pick the most likely family of causes.
- Minutes 25 to 30: assign work and send the first update. Give each investigator a specific question, and send a short internal update with the facts known so far and the time of the next one.
Keeping transactional mail on its own stream, domain and IP pool makes this triage far easier, because you can pause promotions without touching receipts. If you have not done that yet, see separating transactional and marketing email streams and make it a project once the incident is over.
A rule for the first hour: Change one thing at a time and write it down with the time. If three people alter DNS, content and sending rate at once, nobody can tell which change helped.
Symptom-to-cause decision table
Use this table to turn what you see into the first thing to check. It lists likely causes, not certainties, and several can occur together. The first column is what your dashboards show. The second says which question to ask. The third points to the check that confirms or rules it out.
| Symptom | Scope | Likely causes | First checks |
|---|---|---|---|
| Bounce spike (5xx rejections) | All providers, starting at an exact time | Broken authentication, expired or removed DNS record, wrong credential, sending from an unverified domain | DNS records for SPF, DKIM and DMARC; recent DNS or provider changes; error text in bounce responses |
| Bounce spike (5xx rejections) | One provider | Policy block or reputation listing at that provider, sudden volume or content change | Bounce text from that provider, its postmaster data, recent send history to that provider |
| Bounce spike with unknown user errors | Mostly one campaign or import | Stale, purchased or mistyped addresses added to a list | Source of the list, age of addresses, validation results |
| Deferral spike (4xx) | One or two providers | Rate limiting, early reputation concerns, too many connections | Deferral text, current sending rate and concurrency, queue age |
| Deferral spike (4xx) | All providers | Network or DNS trouble on your side, TLS failures, resource limits on sending servers | Timeouts and TLS errors in logs, DNS resolution from sending hosts |
| Complaint spike | One campaign or segment | Unexpected audience, unclear sign-up source, hard-to-find unsubscribe link | Segment definition, sign-up source, unsubscribe link visibility, feedback loop data |
| Opens and clicks fall, bounces flat | One provider | Mail moving to the spam folder without any rejection | Postmaster data, seed or panel test inbox results, recent content or volume changes |
| Opens and clicks fall, bounces flat | All providers | Tracking domain trouble, image blocking, broken links, or a measurement change | Tracking domain certificate and DNS, link tests, any recent template change |
| Mail from unfamiliar sources passes your domain in DMARC reports | Appears in aggregate reports | Spoofing, or a forgotten third-party tool sending as you | DMARC aggregate report sources, list of approved senders, access logs for your sending credentials |
Two patterns deserve special care. A sudden rise in volume that you did not schedule, together with a complaint spike, can mean a compromised account or leaked key sending on your behalf. That is a security event first and a deliverability event second. And a single-provider problem is often a reputation matter at that provider, while an all-provider problem that began at an exact minute usually points to something you changed or that expired. For deeper reading on each family, our guide to SMTP bounce codes explains how to read 4xx and 5xx responses, and the spam folder troubleshooting checklist covers placement problems step by step.
Evidence to collect before you change anything
Evidence disappears quickly. Logs rotate, queues drain and reports are overwritten. Collect first, then fix. Save everything into one shared folder with the incident start time in its name, and note the time zone of every export.
| Evidence | What it tells us | How to capture it |
|---|---|---|
| Event logs for the last 7 days | Accepted, deferred, bounced and complained counts by provider, stream and campaign | Export from your MigoSMTP dashboard, API or webhooks; check your MigoSMTP account or API documentation for exact options |
| Raw bounce and deferral responses | The exact wording providers use to explain the problem | Copy a sample of each distinct message, with the enhanced status code, per provider |
| Full headers of delivered and spam-foldered test messages | Authentication results, routing and any filter verdicts | Send tests to mailboxes you control and save the original source of each |
| DMARC aggregate reports | Which sources send as your domain and whether SPF and DKIM pass and align | Pull the last 7 to 14 days of reports and compare with the previous period |
| Mailbox provider postmaster data | Domain and IP reputation signals, spam rate and authentication results where the provider publishes them | Screenshot or export the dashboards for the affected domains |
| Blocklist and DNS checks | Whether sending IPs or domains are listed, and whether records are correct today | Query the main blocklists you rely on and resolve your SPF, DKIM, DMARC, reverse DNS and tracking records |
| Change history | What was deployed, edited or switched around the start time | Ask the whole team: code releases, DNS edits, new tools, list imports, template changes |
Quick DNS checks can be run from any terminal. The commands below use an invented domain and selector to show the pattern; replace them with your own values.
# Is the SPF record still published and valid?
dig +short TXT example.com
# Is the DKIM key for the selector still published?
dig +short TXT selector1._domainkey.example.com
# What DMARC policy is published?
dig +short TXT _dmarc.example.com
# Does the sending IP have the expected reverse DNS name?
dig +short -x 192.0.2.25
For reading headers, follow our guide on reading email headers to debug delivery and authentication. For reputation dashboards, the article on Google Postmaster Tools explains what the signals mean and how to set them up before you need them.
Containment and recovery steps
Containment stops the harm. Recovery brings volume back safely. They are separate phases, and mixing them is how teams relight a fire. Do not resume paused streams just because the metrics look better for an hour.
Containment actions by cause
- Authentication failure: restore or correct the DNS record, confirm with a test message that SPF, DKIM and DMARC pass and align, and only then resume traffic.
- Compromised credential or account: disable and replace the credential, review what was sent, notify the account owner, and follow your security process. Rotating keys is covered in our API key security guidance.
- Bad list or segment: remove the segment, suppress addresses that bounced or complained, and trace how the addresses entered the list so it cannot happen again.
- Content or link problem: pull the template, remove the suspect link or attachment, and test the revised version before it goes out again.
- Blocklist listing: find out why the listing happened first, fix that cause, then follow the delisting process of the specific list. Our blocklist removal guide covers the steps.
- Provider rate limiting: reduce concurrency and messages per connection for that provider, and let the queue drain at the pace it allows.
A staged recovery plan
- Resume the most engaged and most recent subscribers first, at a fraction of normal volume.
- Hold each stage for at least one full day of provider feedback, and longer for providers that report data with a delay.
- Raise volume only while bounce, deferral and complaint rates stay at or below your pre-incident baseline.
- If a signal worsens, step back to the previous stage rather than holding position.
- Bring colder segments back last, and consider a re-engagement pass or removal for contacts that have not interacted for a long time.
- Declare recovery only after the signals stay healthy at full volume for a period you agreed at the start.
The same careful ramp is described for new infrastructure in our warm-up article, and it applies here too. Think of recovery as a smaller version of warm-up, using your best traffic first.
Communication templates
Good communication lowers the number of questions that interrupt the people fixing the problem. Keep messages short, factual and regular. State what is known, what is not, what we are doing and when the next update comes. Avoid blame and avoid promising a fix time that you cannot control. Adapt the invented text below to your own tone.
Internal stakeholder update
Subject: Email delivery incident - update 1 (14:30 UTC)
Status: Investigating, contained.
Impact: Promotional emails to one large mailbox provider are being
delayed or filtered. Order confirmations and password resets are
being delivered normally in our tests.
Actions taken: Promotional sends paused at 14:10 UTC. Evidence
collection in progress. No changes made to DNS yet.
Next steps: Review provider responses and authentication reports.
Needed from you: Please do not schedule new campaigns until we confirm.
Next update: 15:30 UTC or sooner if anything changes.
Incident lead: [name]
Message for support and customer-facing teams
Subject: For support: delayed or missing marketing emails
What customers may report: Some people have not received recent
newsletters or promotions.
What we know: We are investigating a delivery problem affecting one
mailbox provider. Account and transactional emails are working.
What to say: We are aware that some emails are delayed and are working
on it. Please ask the customer to check their spam folder and to add
our sending address to their contacts.
What not to say: Do not name a cause or promise a time until the
incident lead confirms.
Escalate to the incident lead if: a customer reports missing password
reset or payment emails.
Next update: 16:00 UTC.
A worked example with invented numbers
A team normally sends about 200,000 promotional emails and 15,000 transactional emails a day. Their normal bounce rate is around 0.6 percent and their normal complaint rate is around 0.05 percent. On a Tuesday at 09:00 UTC a campaign to 80,000 contacts goes out. By 09:40 the dashboard shows 2,400 hard bounces from that campaign, which is 3 percent, and one large provider is deferring most of the remaining messages.
At 09:45 the on-call investigator opens the runbook. By 09:55 the promotional stream is paused and test receipts are confirmed delivered. The decision table points to a bounce spike with unknown user errors, concentrated in one campaign. Checking the list history shows that 30,000 of the 80,000 addresses were imported from an old event spreadsheet two days earlier and never validated. About 2,000 of the 2,400 bounces come from that import.
Containment is simple: suppress the bounced addresses, remove the unvalidated import from all segments and run it through validation before any further use. The team resumes the stream at 10 percent of normal volume to its most engaged contacts the next morning, raises it to 25, 50 and 100 percent over the following days while bounce rate stays under 1 percent, and confirms recovery after three clean days at full volume. The review adds a guardrail: any new import must pass validation and be held out of campaigns until a named person approves it. The cost of the incident was one paused day and a few delayed campaigns, instead of a long reputation repair.
Guardrails and alert thresholds to tune
Most incidents are found by customers because nobody was watching the right number. Guardrails move the discovery earlier. The values below are examples chosen to show the shape of a sensible alert. They are not universal standards, and the right numbers depend on your audience, your providers and your history. Measure your own baseline for several weeks, then set thresholds relative to it. Check the current sender guidelines of the mailbox providers you care about for any published limits, and read our guide on the metrics to measure to decide what to track.
| Signal | Example alert (tune to your baseline) | Suggested automatic action |
|---|---|---|
| Hard bounce rate per campaign | Warn above 2 times your baseline, stop above 4 times, or when your own absolute limit is crossed | Pause the campaign and alert the owner |
| Complaint rate per provider | Warn at half of the limit a provider publishes, page at three quarters of it | Pause the segment and review sign-up source |
| Deferral share per provider | Warn when deferrals exceed a share you normally never see, for example 10 percent for 15 minutes | Lower sending rate to that provider |
| Queue age for transactional mail | Warn when the oldest message waits longer than a few minutes | Page the on-call investigator |
| Sending volume | Warn when hourly volume exceeds a multiple of the usual for that hour | Check for compromised credentials or runaway jobs |
| DNS and certificate health | Daily check that SPF, DKIM, DMARC and tracking records resolve; warn weeks before certificate expiry | Open a ticket to fix before it fails |
| New list imports | Block use in campaigns until validated and approved | Require named approval in the workflow |
Beyond alerts, add structural guardrails: separate streams, per-campaign send caps, a holdback for new sources, and a standing owner for each domain and IP. Rate and retry behavior also matters, which is explained in the guide to rate limits, retries and backoff on our help centre.
On-call roles
A runbook works best when roles are known before the pager rings. In a small business one person may fill several seats, but each seat should have a named person and a backup.
| Role | Responsibility | Does not do |
|---|---|---|
| Incident lead | Declares and closes the incident, makes decisions, sets update times | Run every investigation personally |
| Technical investigator | Reads logs, headers and DNS, tests fixes, proposes containment | Change production settings without telling the lead |
| Sender or campaign owner | Knows what was sent, to whom and why; pauses and resumes streams | Resume traffic without the lead agreeing |
| Communicator | Sends stakeholder and support updates, keeps the timeline | Speculate about causes |
Post-incident review
Hold the review within a few days, while memories and logs are fresh. Keep it blameless: the aim is to find what in the system let the problem through, not who clicked the button. A one-page record is enough for most incidents.
- Summary: what happened and what the impact was, in two or three sentences.
- Timeline: when it started, when it was detected, when contained, when recovered. All in UTC.
- Root cause and contributing factors: the direct cause, and the gaps that let it happen or slowed detection.
- What went well: steps that worked and should be kept.
- Actions: each with an owner and a date, such as a new alert, a validation step, a DNS check or a changed approval flow.
- Follow-up: a date to confirm the actions are done and the metrics are stable.
Incident checklist
- Incident declared, lead named, start time recorded in UTC.
- Transactional mail verified with test messages and kept on its own stream.
- Non-critical bulk and promotional streams paused or throttled.
- Symptom classified with the decision table: bounce, deferral, complaint or engagement drop; one provider or all.
- Evidence saved: event logs, raw responses, headers, DMARC reports, postmaster data, blocklist and DNS checks.
- Change history gathered from the whole team.
- Cause fixed and verified with a test message before any resume.
- Recovery staged from engaged contacts at reduced volume, with agreed pass criteria.
- Stakeholder and support updates sent on schedule.
- Review held, actions assigned, guardrails and alerts updated.
MigoSMTP provides sending, logs and events that help with several of these steps. Check your MigoSMTP account or API documentation for exact details on the reports, webhooks and controls available to you.
Want a second pair of eyes during an incident? Tell us what your dashboards show, which providers are affected and what changed recently, and we will help you work through the runbook.
Further reading and sources
- RFC 5321: Simple Mail Transfer Protocol (reply codes and retry behavior)
- RFC 3463: Enhanced Mail System Status Codes
- RFC 7489: Domain-based Message Authentication, Reporting, and Conformance (DMARC)
- RFC 6591: Authentication Failure Reporting Using the Abuse Reporting Format
- Google: Email sender guidelines
Frequently asked questions
What is the very first thing to do when delivery drops suddenly?
Stop making it worse. Pause or throttle non-critical bulk and promotional streams, keep transactional mail running on its own stream, and open an incident with a named lead and a start time. Diagnosis comes second, because every extra message sent into a damaged reputation adds to the harm.
Should I stop sending everything?
Usually not. Password resets, one-time codes and receipts are time sensitive and people are waiting for them. Pause the streams that are optional and risky, protect the ones that are essential, and only stop everything if the problem is a security event such as a compromised credential sending mail you did not write.
How do I tell a reputation problem from a technical fault?
A technical fault such as broken DNS, an expired certificate or a wrong credential tends to start at an exact time, affects every provider and shows clear error text. A reputation problem usually shows up first at one or two providers as deferrals or spam folder placement, and grows over days. The decision table in this guide helps you separate the two.
Why do deferrals matter if the mail is not rejected?
A deferral is a temporary 4xx answer that means try again later. Providers often use it to slow down a sender they do not yet trust. If your queue grows, messages may expire before they are delivered, so a deferral spike is an early warning that deserves attention before it turns into rejections.
Can opens dropping alone mean an incident?
Not by itself. Apple Mail Privacy Protection and image blocking make open data unreliable, so use opens as a hint and confirm with delivery events, click data and Postmaster style reputation data. A fall in opens together with more spam folder placement is more convincing than a fall in opens alone.
Which thresholds should we alert on?
There is no universal number. Start from your own normal range over several weeks, then alert on a clear departure from it, such as a bounce rate or complaint rate that doubles from its baseline or crosses a limit your mailbox providers publish. The example values in this guide are starting points to tune, not standards.
How long does recovery take?
It depends on the cause and the provider. A fixed DNS record can recover within hours, while a damaged domain reputation can take days or weeks of careful sending to rebuild. Plan for gradual recovery and measure it, rather than promising a date to stakeholders.
Who should be on call for a deliverability incident?
At least an incident lead, a technical investigator who can read logs and DNS, a sender or campaign owner who knows what was sent, and a communicator who updates stakeholders and support. In a small team one person may hold two roles, but the roles should still be written down.
Do we need a post-incident review for a small incident?
Yes, a short one. Even a half-page record of what happened, why, and which guardrail will catch it next time turns a bad day into a lasting improvement. Keep it blameless so people share facts freely.