emailmarketing.net

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.

Operationalesp-operatorsender

The other operations articles are reference checklists — ordered lists of things that are true about reputation, content, or infrastructure. This article is the decision-procedure layer: given a symptom a customer or dashboard reports, which discriminating test do you run next, and where does each branch lead. It exists because the daily job of a deliverability analyst is not "run down a checklist" but "narrow the hypothesis space one test at a time." Each playbook is written so an agent can walk it top-down and stop at the first branch that matches.

For the raw material these playbooks route into, see: error-code catalogs (Gmail, Yahoo, enhanced status codes); the reputation monitoring stack; Microsoft filtering internals; the escalation channel map; and reputation incident recovery for what to do after diagnosis when the cause is systemic.

Step 0 — The one question that forks everything: was it accepted?

Every delivery problem is one of two fundamentally different classes, and the first job is always to establish which. Do not run a spam-placement playbook on a message that never got a 250, and do not run a bounce playbook on a message that was accepted and then junk-foldered.

Not accepted (transfer failed) Accepted (transfer succeeded)
SMTP evidence 4xx (deferred, will retry) or 5xx (bounced, gave up) 250 ... OK recorded in your logs / MTA
Recipient sees Nothing — or the sender gets an NDR/bounce Message is somewhere on the recipient 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:

  • On your own MTA / ESP logs: read the last SMTP response for that recipient. A 250 means the receiver took responsibility for the message; anything else means it did not.
  • API senders (Postmark model): a Delivered event = remote server returned 250 2.0.0 OK. Delivered is acceptance, not inbox placement — the message can still be spam-foldered or dropped downstream. Processed = handed to the sending MTA, awaiting the remote server's verdict. Queued = accepted by the platform but not yet sent (check whether the account/stream is paused for high bounce/complaint rates, or the platform's status page).
  • Microsoft 365 recipient side: run a message trace (Exchange admin center → mail flow → message trace). Delivered in the STATUS column = accepted; the Details view carries a "How to fix it" explanation for anything else. Trace data appears 10 min–1 hr after send; traces >7 days old are CSV-only and can take up to an hour to generate.

If you cannot find the message in your logs at all, the problem is upstream of delivery: the send never happened (paused stream, API error, suppression-list hit, a filter/rule on the sending side). Check the sending platform's own response code before blaming the receiver.

Playbook A — Message not delivered (bounced / rejected, 5xx)

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

The discriminating signal is the rejection text, not the numeric code alone — read the full SMTP response and the enhanced status code (RFC 3463 class: 5.1.x addressing, 5.7.x policy/security). Route by what the text says:

Rejection says… Hypothesis Discriminating test Fix
"user unknown", "mailbox does not exist", 5.1.1, 550 5.1.1 Invalid recipient Is it one address or many? One = typo/churned address. Many = list-quality problem Suppress the address (hard bounce → permanent suppression). Many → audit acquisition source; see list hygiene
"quota exceeded", "mailbox full", "out of storage", 5.2.2 Recipient-side full mailbox Single recipient, transient Treat as soft/temporary; retry, then suppress after repeated failures. Not your reputation
Names a blocklist (Spamhaus, Barracuda, SpamCop, SURBL) or "listed in DNSBL" IP/domain blocklisted DNSBL lookup on every sending IP + domain Find root cause first, then delist — see blocklists and the delisting workflow. Do not request delisting before fixing behavior
"banned sending IP", "access denied", reputation language, 5.7.x Reputation block by the provider Is it one provider or all? One provider + provider dashboard shows red = provider-specific reputation Provider-specific branch below; escalate via provider channel
References content, links, attachments, "message content rejected", "spam" in a 5xx Content filter block Seed test / spam-check the exact message; A/B remove elements Fix content — content & design; remove URL shorteners, fix HTML
Auth language: SPF/DKIM/DMARC fail, 5.7.1, 5.7.26, "unauthenticated" Authentication failure Inspect Authentication-Results; check DMARC policy Fix alignment — DMARC; Gmail/Yahoo bulk-sender auth is mandatory
HELO/EHLO error, 501 5.5.4, "invalid HELO", nonroutable IP Connection identity / rDNS Verify PTR exists and matches; HELO is an FQDN, not a private IP Fix rDNS/HELO — receivers (incl. Microsoft) reject mail advertising 10.x, 172.16–31.x, 192.168.x
"too many messages", rate/connection language (421, 4.7.x — technically deferral) Rate limiting See Playbook B Slow down; see MTA delivery tuning

Provider-specific 5xx branches (the reputation/content rejections that route out of the table above):

  • Gmail — the full 421/550-5.7.x code catalog with per-code fixes lives in Gmail SMTP Troubleshooting. Gmail's own non-delivery guidance also flags: sending >500 messages/day or one message to >500 recipients (personal-Gmail limits), non-existent recipient, storage-full recipient, HELO/EHLO malformation.
  • Microsoft — 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). For the header/SCL/BCL diagnostic layer see Microsoft filtering internals; full NDR code list is Microsoft's "Email non-delivery reports in Exchange Online."
  • Yahoo — code catalog in Yahoo SMTP Error Codes.
  • B2B / corporate gateways (Proofpoint, Mimecast, Barracuda, M365 tenants) — different reputation systems and delisting portals entirely; see B2B gateway deliverability.

Playbook B — Message delayed / deferred (4xx, "Delayed", stuck in queue)

Symptom: message not yet delivered but not permanently failed — sender's queue shows 4xx/421, or Postmark shows Delayed (remote server asked to wait; Postmark retries most domains every ~10 min for up to 12 hours before bouncing). This is the receiver saying "not now," and the whole diagnostic is why and for how long.

Deferrals have four common causes that look identical at first and require different responses:

Cause Signature Discriminating test Response
Greylisting First message from a new IP/sender tuple deferred, clears on retry from the same IP Does it deliver on the next attempt with no change? Is deferral tuple-scoped (IP+sender+recipient)? Nothing — retry from the same IP. Confirms why pool/IP affinity matters; see greylisting
Throttling / rate limit Deferrals rise with volume, concentrate at one provider, 421, "try again later", 4.7.28 Do deferrals scale with your send rate? One provider? Reduce concurrency/rate to that destination; back off — MTA delivery tuning, per-provider baselines
Reputation deferral (pre-block) Sustained 4xx that does not clear, provider dashboard degrading, often precedes a hard block GPT/SNDS reputation trending down? Deferral text references reputation? Treat as an early incident — Playbook C + incident recovery; do not just hammer retries
Recipient server down / network Deferrals to one destination domain regardless of your rate; connection timeouts Is it one destination domain, transient, unrelated to your volume? Wait; normal retry schedule. Microsoft's own guidance: "the intended destination isn't responsive" is the most likely delay cause

The critical anti-pattern: responding to a reputation deferral by increasing retry aggressiveness. Hammering a provider that is deferring you for reputation escalates a soft block into a hard block. The test that separates throttle from pre-block is whether the deferral clears when you slow down (throttle) or persists and the dashboard degrades (reputation).

Microsoft-specific: host xxxx.outlook.com [x.x.x.x]: 451 4.7.550 Access denied, please try again later = Microsoft has temporarily restricted the IP because it detected suspicious activity and is evaluating it. The restriction lifts automatically once traffic is judged OK — reduce volume and let it evaluate; do not escalate immediately.

OTP / transactional deferral deserves special handling: a deferred one-time-password is a failed OTP from the user's perspective even though SMTP considers it in-flight. If transactional mail shares a stream/IP with marketing and marketing volume is triggering throttling, the OTP inherits the deferral — this is the argument for stream separation (transactional on its own subdomain/pool), diagnosed by correlating OTP deferral timestamps against marketing send bursts.

Playbook C — Accepted but landed in spam / junk

Symptom: logs show Delivered / 250, but the message is in the spam or junk folder (or a Gmail tab the sender considers "not the inbox"). This is the placement problem, and it is the single most common consultant ticket. There is no SMTP signal here — the receiver accepted the message and made a post-acceptance routing decision — so the discriminating tests are dashboards, headers, and seed tests, not response codes.

C-1. Scope the failure first

The most valuable early test is is it one provider or all providers? — it splits the entire hypothesis space:

  • All providers → sender-side cause. Authentication, content, or list/reputation problem that every filter sees. Start with authentication and content.
  • One provider → that provider's reputation or filter. Route to the provider branch (C-3). A message that inboxes at Yahoo but spams at Gmail is not a content problem; it is a Gmail-reputation or Gmail-personalization problem.

Establish scope with a seed/inbox-placement test across providers (Litmus, Validity/Everest, GlockApps, Mailgun) — but read it with its limits: seeds have no engagement history with you, so they miss per-user personalization and skew conservative (see placement-measurement honesty and tracking distortion). Triangulate seed results against Postmaster Tools and live per-provider engagement.

C-2. Sender-side test ladder (run when it's spam at all providers)

In order — stop when a test reveals the cause:

  1. Authentication — inspect a delivered-to-junk message's headers. Authentication-Results: must show spf=pass dkim=pass and DMARC alignment (the From domain matching the DKIM d= / Return-Path domain). Unauthenticated mail is flagged high-risk by every major provider and is disqualifying under Gmail/Yahoo bulk-sender rules. Verify SPF is within the 10-lookup limit, DKIM verifies, and a custom Return-Path is in place for alignment. See DMARC.
  2. Complaint rate — the most damaging signal. Postmark's operating line: complaint rate above 0.1% (1 per 1,000) predicts a deliverability drop; Google enforces a 0.3% hard ceiling (see Gmail requirements). Check per-provider complaint data in GPT / SNDS-JMRP.
  3. Bounce rate — high invalid-address rates signal spammer-like list practices. Postmark's operating ceiling is <5% hard-bounce (never exceed 10%); Klaviyo's stricter aspirational line is <1% total bounce and Postmark's warm-up-healthy line is <2% — the full attributed spread is in the canonical threshold table. High bounces → list-quality problem feeding reputation.
  4. Content — run the exact message through a SpamAssassin-based check (Postmark Spam Check target: score <5, negative better) and mail-tester. Common triggers: URL shorteners (bit.ly) instead of branded links; image-only messages / oversized images; broken or incomplete HTML; link and image domains that don't match the From domain; missing/broken unsubscribe. If a template change preceded the drop, revert incrementally (remove one element at a time) to isolate the trigger. See content & design.
  5. Reputation — check domain and IP reputation in the provider dashboards and DNSBL lookups. A degraded rating here means the cause is accumulated history, not this one message → incident recovery.

C-3. Provider-specific placement branches (run when it's spam at one provider)

Provider Discriminating test Reads / means Route
Gmail Google Postmaster Tools: domain & IP reputation (Bad/Low/Medium/High), spam-rate dashboard, auth pass rates Domain reputation drop High→Medium predicts junk-foldering; per-user personalization means one Gmail user inboxes while another spams the same campaign (contact history) — so seed disagreement with real placement is expected Shrink to engaged Gmail users, drive positive engagement; GPT shows no data below volume thresholds — diagnose via engagement instead
Microsoft (Outlook.com / M365) Header inspection: X-Forefront-Antispam-Report SCL (spam confidence) and BCL (bulk complaint level); compauth High SCL = content/reputation spam verdict; high BCL = bulk-mail penalty; the header tells you which filter fired. Full decode in Microsoft filtering internals False positive → recipient submits the message to Microsoft for analysis; check SNDS filter color (green/yellow/red) & trap hits; escalate via Microsoft channels
Yahoo / AOL Yahoo performance feeds + complaint FBL Complaint-driven; Yahoo weights engagement heavily Suppress complainers, tighten to engaged; Yahoo requirements
Apple iCloud No sender dashboard — infer from seed + engagement MPP inflates opens (treat opens as unreliable); placement driven by auth + reputation Apple iCloud
B2B gateway Gateway's own IP-reputation checker (ipcheck.proofpoint.com, barracudacentral.org) Admin-configured tenant policy + gateway reputation, not consumer-style filtering B2B gateway deliverability

C-4. Microsoft "landed in Junk" — the specific workflow

Microsoft's documented path for a false positive: (1) confirm it 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 the sender isn't advertising a nonroutable IP or failing reverse-DNS; (4) confirm From-name/subject transparency and consistent redirect domains (all links to one domain, not scattered across unsubscribe.bulkmailer.com / profile.excite.com / options.yahoo.com); (5) for systemic reputation, work SNDS and sender support.

Playbook D — Message "missing" (accepted, not in inbox, not in spam)

Symptom: logs show Delivered, but the recipient finds it nowhere — not inbox, not spam. This is the hardest to diagnose because the receiver reported success. Hypotheses in order of likelihood:

  1. It's in spam/junk and the recipient didn't look — the most common "missing" resolution. Have the recipient search all folders (including Gmail tabs Promotions/Updates/Social, Outlook Focused vs Other, Junk). Then run Playbook C.
  2. Silently filtered / dropped after acceptance — the provider accepted then discarded (aggressive reputation filtering). Provider dashboard + a message trace (Microsoft) reveals a post-acceptance filter verdict. This is a reputation problem → Playbook C-3 / incident recovery.
  3. Client-side rule / forwarding — a user inbox rule moved or deleted it, or a broken forward lost it. Microsoft's first triage step: have the user check Outlook on the web — if the message is there but not in their desktop/mobile client, the problem is the client/app or a local rule, not delivery. Run Microsoft's Support and Recovery Assistant for single-user Outlook issues.
  4. Delivered to the wrong address — alias/typo that happens to be a valid mailbox. Confirm the exact recipient address in your logs.
  5. Service incident — before deep investigation, check the provider's service health (Microsoft 365 admin center → Service health; provider status pages). A degraded receiving service delays or misroutes mail organization-wide and needs no sender-side fix.

Single-user vs. many-users is the key fork in Playbook D: one recipient missing = client/rule/address problem (tools above). Many recipients at one provider missing = reputation/filtering (Playbook C). Many across all providers = authentication or a sending-side incident.

Scenario library (composed playbook walks)

Concrete tickets and the branch each takes:

Ticket Fork Test → finding → fix
"Delivered but spam at Gmail only" C, one-provider Seed confirms Gmail-only → GPT shows domain reputation Medium → not content (Yahoo inboxes) → shrink to engaged Gmail users, drive engagement, recover over weeks
"Sudden Microsoft junk-foldering after years of inboxing" C-3 Microsoft Header shows SCL jump / BCL → SNDS turned yellow/red or trap hits → recent list/volume change is the trigger → suppress bad segment, submit false-positive, MS escalation
"Transactional OTP deferred at Yahoo" B, throttle Deferrals correlate with a marketing burst on the shared stream → separate transactional stream/pool → deferral clears
"Open rates collapsed at one provider" C or measurement artifact First rule out MPP/bot-click distortion (opens unreliable post-MPP); if clicks/conversions also fell → real placement drop → Playbook C
"New IP: mail suddenly rejected / deferred" A or B Read text: 5.7.1 IPv6 guideline → IPv6 sending auth+PTR mandate; 451 4.7.550 Microsoft → new-IP throttle, let it ramp (weeks); greylist → retry same IP
"Bounces spiked overnight, one provider" A, reputation DNSBL + dashboard: blocklisted or provider reputation block → delisting workflow after fixing root cause; suspect compromise if volume also spiked
"Recipient says never arrived, log says Delivered" D All-folders search first → then single-vs-many fork → Outlook-on-web test for single user

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

Run the playbooks to a specific, evidenced hypothesis before opening a provider channel — provider support closes tickets that arrive without diagnosis. Bring: sending IP(s) and domain, exact SMTP rejection/NDR text, sample headers (Authentication-Results, X-Forefront-Antispam-Report), dashboard screenshots (GPT/SNDS), the date the problem started, and what you changed around then. The channel map — Google bulk-sender form and its 0.3%/7-day eligibility gate, Microsoft delist portal (sender.office.com) vs. sender support, Yahoo sender support, Apple icloudadmin@ — is in Escalation & Mitigation Channels and Microsoft Escalation Channels. Each channel fixes only some problems: delist portals clear IP blocks, not content or complaint problems, which self-correct only after sender behavior changes.

Related

#troubleshooting#operations#diagnosis#gmail#microsoft#yahoo#deliverability#decision-tree#support

Sources