# Delivery Troubleshooting Playbooks

> Symptom-driven decision procedures (symptom → hypothesis → discriminating test → fix) for the four delivery failure modes — not delivered, delayed, in spam, missing — with per-provider branches and a scenario library.

Source: emailmarketing.net — https://emailmarketing.net/learn/operations/delivery-troubleshooting-playbooks

When a customer or a dashboard reports a delivery problem, start from the symptom and run the test that tells the likely causes apart. Each playbook below gives that test and says where each result leads.

A checklist tells you what is true about reputation, content or infrastructure. Diagnosis works differently: you narrow the possible causes one test at a time. The playbooks are written so that a person or an automated agent can follow one from the top and stop at the first branch that matches.

The playbooks point to more detailed material: the error code catalogs for [Gmail](https://emailmarketing.net/learn/providers/gmail-troubleshooting) and [Yahoo](https://emailmarketing.net/learn/providers/yahoo-smtp-error-codes) and the [enhanced status codes](https://emailmarketing.net/learn/bounce-handling/smtp-enhanced-status-codes), the [reputation monitoring stack](https://emailmarketing.net/learn/operations/reputation-monitoring), [Microsoft filtering internals](https://emailmarketing.net/learn/providers/microsoft-filtering-internals) and the [escalation channel map](https://emailmarketing.net/learn/providers/escalation-and-mitigation-channels). When the diagnosis finds systemic damage, [reputation incident recovery](https://emailmarketing.net/learn/operations/reputation-incident-recovery) covers what to do next.

## Step 0: was the message accepted?

Every delivery problem belongs to one of two very different classes, and the first job is always to find out which. Do not run a spam-placement playbook on a message that never received a 250. Do not run a bounce playbook on a message that was accepted and then placed in the junk folder.

| | **Not accepted** (transfer failed) | **Accepted** (transfer succeeded) |
|---|---|---|
| SMTP evidence | 4xx (deferred, will retry) or 5xx (bounced, gave up) | `250 ... OK` recorded in your logs or your MTA |
| Recipient sees | Nothing, or the sender receives a non-delivery report (NDR) or bounce | The message is somewhere on the recipient's side |
| Postmark event | `Bounced`, `Delayed`, `Queued`, `Processed` | `Delivered` |
| Runs playbook | **A** (not delivered) or **B** (delayed) | **C** (in spam) or **D** (missing) |

**How to establish acceptance:**
- **In your own MTA or ESP logs:** read the last SMTP response for that recipient. A `250` means the receiver took responsibility for the message. Any other response means it did not.
- **API senders (the Postmark model):** a `Delivered` event means the remote server returned `250 2.0.0 OK`. `Delivered` means acceptance, not inbox placement: the message can still go to spam or be dropped later. `Processed` means the message was handed to the sending MTA and is waiting for the remote server's verdict. `Queued` means the platform accepted the message but has not sent it yet. Check whether the account or stream is paused for high bounce or complaint rates, and check the platform's status page.
- **Microsoft 365 on the recipient's side:** run a **message trace** (Exchange admin center, then mail flow, then message trace). `Delivered` in the STATUS column means accepted. For any other status, the Details view gives a "How to fix it" explanation. Trace data appears 10 min to 1 hr after sending. Traces older than 7 days are available only as CSV and can take up to an hour to generate.

If you cannot find the message in your logs at all, the problem happened before delivery: the send never took place. Common reasons are a paused stream, an API error, a suppression-list hit, or a filter or rule on the sending side. Check the sending platform's own response code before you blame the receiver.

---

## Playbook A: message not delivered (bounced or rejected, 5xx)

**Symptom:** the sender's logs show a permanent failure, or the sender received an NDR. The receiver refused the message outright.

The signal that tells causes apart is the **rejection text**, not the numeric code alone. Read the full SMTP response and the enhanced status code ([RFC 3463 class](https://emailmarketing.net/learn/bounce-handling/smtp-enhanced-status-codes): `5.1.x` for addressing, `5.7.x` for policy or security). Route by what the text says:

| Rejection says… | Hypothesis | Test that tells causes apart | Fix |
|---|---|---|---|
| "user unknown", "mailbox does not exist", `5.1.1`, `550 5.1.1` | Invalid recipient | Is it one address or many? One points to a typo or a churned address. Many point to a list-quality problem | Suppress the address (a hard bounce means permanent suppression). If many: audit the acquisition source and see [list hygiene](https://emailmarketing.net/learn/operations/list-hygiene-and-sunset-policies) |
| "quota exceeded", "mailbox full", "out of storage", `5.2.2` | The recipient's mailbox is full | A single recipient, and temporary | Treat it as a soft, temporary failure: retry, then suppress after repeated failures. It does not reflect on your reputation |
| Names a **blocklist** (Spamhaus, Barracuda, SpamCop, SURBL) or says "listed in DNSBL" | The IP address or domain is blocklisted | A DNSBL lookup on every sending IP address and domain | Find the root cause first, then request delisting. See [blocklists](https://emailmarketing.net/learn/reference/blocklists-and-spamhaus) and the [delisting workflow](https://emailmarketing.net/learn/operations/reputation-monitoring#blocklist-delisting-workflow). Do not request delisting before you fix the behavior |
| "banned sending IP", "access denied", reputation language, `5.7.x` | The provider has blocked you for reputation | Is it one provider or all of them? One provider with a red dashboard points to reputation at that provider | Follow the provider branch below, and escalate through the [provider's channel](https://emailmarketing.net/learn/providers/escalation-and-mitigation-channels) |
| Mentions content, links or attachments, "message content rejected", or "spam" in a 5xx | A content filter blocked the message | Run a seed test or a spam check on the exact message, and remove elements one at a time | Fix the content ([content and design](https://emailmarketing.net/learn/operations/content-and-design-for-deliverability)): remove URL shorteners and fix the HTML |
| Authentication language: SPF, DKIM or DMARC failure, `5.7.1`, `5.7.26`, "unauthenticated" | Authentication failure | Inspect `Authentication-Results` and check the DMARC policy | Fix alignment ([DMARC](https://emailmarketing.net/learn/authentication/dmarc)). Authentication is mandatory for bulk senders at Gmail and Yahoo |
| HELO or EHLO error, `501 5.5.4`, "invalid HELO", nonroutable IP address | Connection identity or reverse DNS (rDNS) | Verify that a PTR record exists and matches, and that HELO gives a fully qualified domain name (FQDN), not a private IP address | Fix rDNS and HELO. Receivers, including Microsoft, reject mail that advertises `10.x`, `172.16–31.x` or `192.168.x` |
| "too many messages", or rate or connection language (`421`, `4.7.x`, which is technically a deferral) | Rate limiting | See Playbook B | Slow down. See [MTA delivery tuning](https://emailmarketing.net/learn/operations/mta-delivery-tuning) |

**Provider-specific 5xx branches** (for the reputation and content rejections in the table above):
- **Gmail:** [Gmail SMTP Troubleshooting](https://emailmarketing.net/learn/providers/gmail-troubleshooting) lists the full catalog of `421` and `550-5.7.x` codes with a fix for each. Gmail's own guidance on non-delivery also lists sending more than 500 messages a day or one message to more than 500 recipients (the limits for personal Gmail accounts), a recipient that does not exist, a recipient whose storage is full, and a malformed HELO or EHLO.
- **Microsoft:** for `550 5.7.606-649 Access denied, banned sending IP [x.x.x.x]`, use the **delist portal** at `sender.office.com` ([Microsoft escalation channels](https://emailmarketing.net/learn/providers/microsoft-escalation-channels)). For diagnosis from headers, the spam confidence level (SCL) and the bulk complaint level (BCL), see [Microsoft filtering internals](https://emailmarketing.net/learn/providers/microsoft-filtering-internals). Microsoft's full list of NDR codes is in its guide "Email non-delivery reports in Exchange Online."
- **Yahoo:** the code catalog is in [Yahoo SMTP Error Codes](https://emailmarketing.net/learn/providers/yahoo-smtp-error-codes).
- **B2B and corporate gateways** (Proofpoint, Mimecast, Barracuda, M365 tenants): these use entirely different reputation systems and delisting portals. See [B2B gateway deliverability](https://emailmarketing.net/learn/providers/b2b-gateway-deliverability).

---

## Playbook B: message delayed or deferred (4xx, "Delayed", stuck in the queue)

**Symptom:** the message is not delivered yet but has not failed permanently. The sender's queue shows `4xx` or `421`, or Postmark shows `Delayed`: the remote server asked to wait, and Postmark retries most domains every ~10 min for up to 12 hours before it bounces the message. The receiver is saying "not now", and the diagnosis is about why and for how long.

Deferrals have four common causes. They look identical at first, and each needs a different response:

| Cause | Signature | Test that tells causes apart | Response |
|---|---|---|---|
| **Greylisting** | The first message from a new combination of IP address and sender is deferred, and it clears when retried from the same IP address | Does it deliver on the next attempt with no change? Is the deferral tied to the combination of IP address, sender and recipient? | Do nothing except retry from the same IP address. This is why keeping a sender on the same pool or IP address matters. See [greylisting](https://emailmarketing.net/learn/rfc/rfc6647-greylisting) |
| **Throttling or rate limiting** | Deferrals rise with volume and concentrate at one provider: `421`, "try again later", `4.7.28` | Do deferrals grow with your sending rate? Is it one provider? | Reduce concurrency and rate to that destination, and back off. See [MTA delivery tuning](https://emailmarketing.net/learn/operations/mta-delivery-tuning) and [per-provider baselines](https://emailmarketing.net/learn/operations/per-provider-tuning-baselines) |
| **Reputation deferral (before a block)** | Sustained 4xx responses that do not clear, a provider dashboard that is getting worse, often before a hard block | Is your reputation in Google Postmaster Tools (GPT) or Smart Network Data Services (SNDS) trending down? Does the deferral text mention reputation? | Treat it as an early incident: run Playbook C and see [incident recovery](https://emailmarketing.net/learn/operations/reputation-incident-recovery). Do **not** simply retry harder |
| **Recipient server down, or network trouble** | Deferrals to one destination domain whatever your rate, and connection timeouts | Is it one destination domain, temporary, and unrelated to your volume? | Wait and keep the normal retry schedule. Microsoft's own guidance names "the intended destination isn't responsive" as the most likely cause of a delay |

**The critical mistake to avoid** is responding to a reputation deferral by retrying more aggressively. Retrying hard against a provider that is deferring you for reputation turns a soft block into a hard block. To tell throttling from a coming block, slow down. A throttle clears when you slow down. A reputation problem persists, and the dashboard gets worse.

**Microsoft:** `host xxxx.outlook.com [x.x.x.x]: 451 4.7.550 Access denied, please try again later` means that Microsoft has temporarily restricted the IP address because it detected suspicious activity and is evaluating it. The restriction lifts automatically once the traffic is judged acceptable. Reduce volume, let the evaluation run, and do not escalate immediately.

**Deferrals of one-time passwords (OTP) and other transactional mail** need special handling. For the user, a deferred one-time password has failed, even though SMTP still considers it in transit. If transactional mail shares a stream or IP address with marketing mail, and the marketing volume triggers throttling, the OTP is deferred too. This is the argument for [stream separation](https://emailmarketing.net/learn/operations/sending-infrastructure-practices), with transactional mail on its own subdomain and pool. To diagnose it, compare the timestamps of OTP deferrals with the times of marketing send bursts.

---

## Playbook C: accepted but placed in spam or junk

**Symptom:** the logs show `Delivered` or `250`, but the message is in the spam or junk folder, or in a Gmail tab that the sender does not count as the inbox. This is the placement problem, and it is the most common ticket a deliverability consultant receives. There is no SMTP signal: the receiver accepted the message and then decided where to route it. The tests that tell causes apart are dashboards, headers and seed tests, not response codes.

### C-1. Scope the failure first

The most valuable early test is whether the problem affects **one provider or all providers**. The answer splits the possible causes in two:

- **All providers point to a cause on the sender's side.** Every filter sees an authentication, content, list or reputation problem. Start with authentication and content.
- **One provider points to that provider's reputation or filter.** Go to the provider branch (C-3). A message that reaches the inbox at Yahoo but goes to spam at Gmail does not have a content problem. It has a Gmail reputation problem or a Gmail personalization problem.

Establish the scope with a **seed or inbox-placement test** across providers (Litmus, Validity/Everest, GlockApps, Mailgun), and keep its limits in mind. Seed addresses have no engagement history with you, so they miss the personalization for each user and tend to be conservative (see [the limits of placement measurement](https://emailmarketing.net/learn/operations/reputation-monitoring#4-seed--inbox-placement-testing) and [tracking distortion](https://emailmarketing.net/learn/operations/tracking-and-measurement-distortion)). Compare seed results with Postmaster Tools and with live engagement at each provider.

### C-2. Tests on the sender's side (when mail goes to spam at every provider)

Run these in order, and stop when a test reveals the cause:

1. **Authentication.** Inspect the headers of a message that was delivered to junk. `Authentication-Results:` must show `spf=pass dkim=pass` **and** DMARC alignment (the `From` domain matches the DKIM `d=` domain or the Return-Path domain). Every major provider flags unauthenticated mail as high risk, and the bulk-sender rules at Gmail and Yahoo disqualify it. Verify that SPF stays within the [10-lookup limit](https://emailmarketing.net/learn/authentication/spf), that DKIM verifies, and that a custom Return-Path is in place for alignment. See [DMARC](https://emailmarketing.net/learn/authentication/dmarc).
2. **Complaint rate.** This is the most damaging signal. Postmark's working rule is that a complaint rate above **0.1%** (1 per 1,000) predicts a drop in deliverability, and Google enforces a hard ceiling of **0.3%** (see [Gmail requirements](https://emailmarketing.net/learn/providers/gmail-sender-requirements)). Check complaint data for each provider in [GPT](https://emailmarketing.net/learn/postmaster-tools/google-postmaster-tools) and in [SNDS and JMRP](https://emailmarketing.net/learn/postmaster-tools/microsoft-snds-jmrp).
3. **Bounce rate.** A high rate of invalid addresses looks like a spammer's list practices. Postmark's working ceiling is a hard-bounce rate below 5%, and never above 10%. Klaviyo's stricter target is a total bounce rate below 1%, and Postmark's healthy rate during warm-up is below 2%. The full range, with each figure attributed, is in the [canonical threshold table](https://emailmarketing.net/learn/operations/metrics-and-benchmarks#canonical-threshold-table). High bounces point to a list-quality problem that is damaging reputation.
4. **Content.** Run the exact message through a check based on SpamAssassin (Postmark Spam Check's target is a score below 5, and negative is better) and through mail-tester. Common triggers are URL shorteners (bit.ly) instead of branded links, messages made only of images or with oversized images, broken or incomplete HTML, link and image domains that do not match the `From` domain, and a missing or broken unsubscribe link. If a **template change came just before the drop**, revert it step by step, removing one element at a time, to isolate the trigger. See [content and design](https://emailmarketing.net/learn/operations/content-and-design-for-deliverability).
5. **Reputation.** Check domain and IP reputation in the provider dashboards and with DNSBL lookups. A poor rating here means the cause is accumulated history, not this one message. See [incident recovery](https://emailmarketing.net/learn/operations/reputation-incident-recovery).

### C-3. Placement branches for each provider (when mail goes to spam at one provider)

| Provider | Test that tells causes apart | What it shows | Route |
|---|---|---|---|
| **Gmail** | [Google Postmaster Tools](https://emailmarketing.net/learn/postmaster-tools/google-postmaster-tools): domain and IP reputation (Bad, Low, Medium, High), the spam-rate dashboard, authentication pass rates | A drop in domain reputation from High to Medium predicts placement in the junk folder. Gmail personalizes for each user based on their contact history, so one Gmail user can receive a campaign in the inbox while another receives the same campaign in spam. Seed results that disagree with real placement are therefore expected | Send only to engaged Gmail users and encourage positive engagement. GPT shows no data below its volume thresholds, so diagnose through engagement instead |
| **Microsoft** (Outlook.com and M365) | Inspect the headers: **SCL** and **BCL** in `X-Forefront-Antispam-Report`, and `compauth` | A high SCL means a spam verdict based on content or reputation. A high BCL means a penalty for bulk mail. The header tells you which filter fired. [Microsoft filtering internals](https://emailmarketing.net/learn/providers/microsoft-filtering-internals) decodes it in full | For a false positive, the recipient submits the message to Microsoft for analysis. Check the filter color in [SNDS](https://emailmarketing.net/learn/postmaster-tools/microsoft-snds-jmrp) (green, yellow or red) and any trap hits, and escalate through [Microsoft's channels](https://emailmarketing.net/learn/providers/microsoft-escalation-channels) |
| **Yahoo and AOL** | [Yahoo performance feeds](https://emailmarketing.net/learn/providers/yahoo-performance-feeds) and the complaint feedback loop (FBL) | Placement is driven by complaints, and Yahoo gives engagement a lot of weight | Suppress complainers and send only to engaged recipients. See [Yahoo requirements](https://emailmarketing.net/learn/providers/yahoo-sender-requirements) |
| **Apple iCloud** | There is no sender dashboard, so infer placement from seed tests and engagement | Mail Privacy Protection (MPP) inflates opens, so treat opens as unreliable. Placement depends on authentication and reputation | [Apple iCloud](https://emailmarketing.net/learn/providers/apple-icloud-mail) |
| **B2B gateway** | The gateway's own IP reputation checker (ipcheck.proofpoint.com, barracudacentral.org) | Placement depends on the tenant policy set by the administrator and on the gateway's reputation data, not on consumer-style filtering | [B2B gateway deliverability](https://emailmarketing.net/learn/providers/b2b-gateway-deliverability) |

### C-4. Microsoft: the workflow for mail placed in Junk

Microsoft documents this path for a false positive:

1. Confirm that the message was delivered (message trace STATUS = Delivered, not blocked).
2. Have the recipient **report the message to Microsoft** as a false positive for analysis.
3. Verify that the sender is not advertising a nonroutable IP address and is not failing reverse DNS.
4. Confirm that the From name and subject are transparent and that redirect domains are consistent: all links go to one domain, not to a scattered set such as `unsubscribe.bulkmailer.com`, `profile.excite.com` and `options.yahoo.com`.
5. For a systemic reputation problem, work with SNDS and sender support.

---

## Playbook D: message "missing" (accepted, not in the inbox, not in spam)

**Symptom:** the logs show `Delivered`, but the recipient cannot find the message anywhere, neither in the inbox nor in spam. This is the hardest case to diagnose, because the receiver reported success. The possible causes, from most to least likely:

1. **The message is in spam or junk and the recipient did not look there.** This is the most common explanation. Have the recipient search every folder, including the Gmail tabs (Promotions, Updates, Social), Outlook's Focused and Other views, and Junk. Then run Playbook C.
2. **The message was filtered out or dropped after acceptance.** The provider accepted it and then discarded it through aggressive reputation filtering. The provider dashboard and, at Microsoft, a message trace reveal a filter verdict made after acceptance. This is a reputation problem: see Playbook C-3 and [incident recovery](https://emailmarketing.net/learn/operations/reputation-incident-recovery).
3. **A rule or a forward on the recipient's side.** An inbox rule moved or deleted the message, or a broken forward lost it. Microsoft's first triage step is to have the user check **Outlook on the web**. If the message is there but not in the desktop or mobile app, the problem is the app or a local rule, not delivery. For Outlook issues that affect a single user, run Microsoft's **Support and Recovery Assistant**.
4. **Delivery to the wrong address.** An alias or a typo happened to match a valid mailbox. Confirm the exact recipient address in your logs.
5. **A service incident.** Before a deep investigation, check the provider's service health (Microsoft 365 admin center, then Service health, or the provider's status page). A degraded receiving service delays or misroutes mail across the whole organization, and no fix on the sender's side is needed.

**One user or many** is the key question in Playbook D. If one recipient is missing a message, the cause is the mail app, a rule or the address (use the tools above). If many recipients at one provider are missing messages, the cause is reputation or filtering (Playbook C). If many recipients across all providers are missing messages, the cause is authentication or an incident on the sending side.

---

## Scenario library (worked examples)

Concrete tickets and the branch each one takes:

| Ticket | Playbook | Test, finding and fix |
|---|---|---|
| "Delivered but spam at Gmail only" | C, one provider | A seed test confirms that only Gmail is affected. GPT shows domain reputation at Medium. Content is not the cause, because Yahoo delivers to the inbox. Send only to engaged Gmail users, encourage engagement, and expect recovery over weeks |
| "Sudden Microsoft junk-foldering after years of inboxing" | C-3 Microsoft | The header shows a jump in SCL or BCL. SNDS turned yellow or red, or shows trap hits. A recent change in list or volume is the trigger. Suppress the bad segment, submit the false positive, and use [Microsoft's escalation channels](https://emailmarketing.net/learn/providers/microsoft-escalation-channels) |
| "Transactional OTP deferred at Yahoo" | B, throttling | Deferrals coincide with a marketing burst on the shared stream. Move transactional mail to its own stream and pool, and the deferral clears |
| "Open rates collapsed at one provider" | C, or a measurement artifact | First rule out [distortion from MPP and bot clicks](https://emailmarketing.net/learn/operations/tracking-and-measurement-distortion), since opens are unreliable after MPP. If clicks and conversions also fell, placement really dropped: run Playbook C |
| "New IP: mail suddenly rejected / deferred" | A or B | Read the text. `5.7.1` citing the IPv6 guidelines means the authentication and PTR requirements in [IPv6 sending](https://emailmarketing.net/learn/operations/ipv6-sending). `451 4.7.550` from Microsoft means a throttle on a new IP address: let it ramp up, which takes weeks. Greylisting means retrying from the same IP address |
| "Bounces spiked overnight, one provider" | A, reputation | Run DNSBL lookups and check the dashboard. If it is a blocklisting or a provider reputation block, fix the root cause and then follow the [delisting workflow](https://emailmarketing.net/learn/operations/reputation-monitoring#blocklist-delisting-workflow). If volume also spiked, suspect a [compromised account](https://emailmarketing.net/learn/esp-operations/compromised-accounts) |
| "Recipient says never arrived, log says Delivered" | D | Search all folders first. Then ask whether one user or many are affected. For a single user, test Outlook on the web |

---

## Escalating to the provider (when self-service is exhausted)

Before you open a provider channel, run the playbooks until you have a specific hypothesis backed by evidence. Provider support closes tickets that arrive without a diagnosis. Bring the sending IP addresses and domain, the exact SMTP rejection or NDR text, sample headers (`Authentication-Results`, `X-Forefront-Antispam-Report`), screenshots of the GPT or SNDS dashboards, the date the problem started, and what you changed around that date.

[Escalation and Mitigation Channels](https://emailmarketing.net/learn/providers/escalation-and-mitigation-channels) and [Microsoft Escalation Channels](https://emailmarketing.net/learn/providers/microsoft-escalation-channels) map the channels: Google's bulk-sender form and its eligibility condition (0.3% over 7 days), Microsoft's delist portal (`sender.office.com`) as distinct from sender support, Yahoo sender support, and Apple's `icloudadmin@` address. Each channel fixes only some problems. Delist portals clear IP blocks. They do not clear content or complaint problems, which correct themselves only after the sender's behavior changes.

## Related articles

- [Reputation Monitoring and Remediation](https://emailmarketing.net/learn/operations/reputation-monitoring), including the delisting workflow
- [Reputation Incident Recovery](https://emailmarketing.net/learn/operations/reputation-incident-recovery)
- [Sending Infrastructure Practices](https://emailmarketing.net/learn/operations/sending-infrastructure-practices), on Postmark's 5-area framework: authentication, content, engagement, reputation and infrastructure
- [MTA Delivery Tuning](https://emailmarketing.net/learn/operations/mta-delivery-tuning)
- [Per-Provider Tuning Baselines](https://emailmarketing.net/learn/operations/per-provider-tuning-baselines)
- [Gmail SMTP Troubleshooting](https://emailmarketing.net/learn/providers/gmail-troubleshooting)
- [Microsoft Filtering Internals](https://emailmarketing.net/learn/providers/microsoft-filtering-internals)
- [Yahoo SMTP Error Codes](https://emailmarketing.net/learn/providers/yahoo-smtp-error-codes)
- [Escalation and Mitigation Channels](https://emailmarketing.net/learn/providers/escalation-and-mitigation-channels)
- [Enhanced Status Codes](https://emailmarketing.net/learn/bounce-handling/smtp-enhanced-status-codes)
- [Delivery Status Notifications](https://emailmarketing.net/learn/bounce-handling/delivery-status-notifications)