email-deliverability-troubleshooting

name	email-deliverability-troubleshooting
enabled	true
description	Use when performing email deliverability troubleshooting — email delivery issues investigation workflow covering bounce analysis, spam filter diagnosis, SPF/DKIM/DMARC validation, mail flow tracing, and mailbox quota management. Guides helpdesk agents through systematic diagnosis of email delivery failures for both sending and receiving issues.
required_connections	[{"prefix":"itsm","label":"ITSM Tool (ServiceNow, Freshservice, etc.)"}]
config_fields	[{"key":"user_name","label":"Affected User Name","required":true,"placeholder":"e.g., Jane Smith"},{"key":"email_direction","label":"Issue Direction (sending/receiving/both)","required":true,"placeholder":"e.g., sending, receiving, both"},{"key":"recipient_or_sender","label":"Other Party Email Address","required":false,"placeholder":"e.g., [e-mail]"},{"key":"email_platform","label":"Email Platform","required":false,"placeholder":"e.g., Microsoft 365, Google Workspace, Exchange On-Prem"}]
features	["HELPDESK"]

Email Deliverability Troubleshooting

Investigating email issue for {{ user_name }} Direction: {{ email_direction }} | Platform: {{ email_platform }} Other party: {{ recipient_or_sender }}

Decision Tree

START: What is the email issue?
│
├─ Emails Not Being SENT
│  ├─ Bounce-back / NDR received?
│  │  ├─ Yes → Analyze NDR error code (see below)
│  │  └─ No → Check outbox, stuck in queue?
│  ├─ Sending to all recipients or specific ones?
│  │  ├─ All → Account or server issue
│  │  └─ Specific → Recipient-side issue
│  └─ Attachment issues?
│     └─ Check size limits (typically 25-35MB)
│
├─ Emails Not Being RECEIVED
│  ├─ From all senders or specific?
│  │  ├─ All → Mailbox or routing issue
│  │  └─ Specific → Spam filter or sender issue
│  ├─ Check spam/junk folder
│  ├─ Mailbox full?
│  └─ Mail flow rules blocking?
│
└─ Emails Delayed
   ├─ Internal or external?
   ├─ Check mail queue on server
   └─ DNS/MX record issues?

Diagnostic Steps

Step 1 — Basic Checks

• Verify {{ user_name }}'s mailbox is active and not over quota
• Check mailbox size: current usage vs limit
• Verify {{ user_name }} can log into webmail (rules out client-only issues)
• Check for any active mail flow rules / inbox rules that might redirect or delete emails

Step 2 — Bounce / NDR Analysis

Common NDR codes and meanings:

Code	Meaning	Action
550 5.1.1	Recipient does not exist	Verify recipient address spelling
550 5.7.1	Relay denied / not authorized	Check authentication, connector config
552 5.2.2	Mailbox full	Recipient needs to clear space
554 5.7.1	Message rejected (spam)	Check SPF/DKIM/DMARC, content filters
421 4.7.0	Temporary failure, try later	Server greylisting, retry automatically
550 5.4.1	Recipient domain not found	Verify domain exists, check MX records

Step 3 — DNS & Authentication Records

• Verify MX records point to correct mail servers
• Validate SPF record: nslookup -type=txt domain.com — look for v=spf1
• Validate DKIM: check selector records in DNS
• Validate DMARC: nslookup -type=txt _dmarc.domain.com
• If records are missing or incorrect, escalate to DNS administrator

Step 4 — Message Trace

• Run message trace in {{ email_platform }} admin console
• Search by sender, recipient, date range, and message ID
• Check trace results for:
  • Delivery status (delivered, failed, pending, filtered)
  • Transport rules applied
  • Spam filter verdict and confidence level
  • Connector routing path

Step 5 — Spam Filter Investigation

• Check if message was quarantined
• Review spam filter logs for the specific message
• If legitimate email was blocked:
  • Whitelist sender domain or address
  • Adjust spam filter sensitivity if false positives are frequent
  • Release message from quarantine
• If company emails are being marked as spam by recipients:
  • Verify SPF/DKIM/DMARC alignment
  • Check if company domain/IP is on any blacklists
  • Review email content for spam trigger words

Escalation Criteria

Escalate to email/messaging team if:

• Mail server queue is backed up
• DNS record changes are needed
• Domain is blacklisted
• Transport rules need modification
• Multiple users affected simultaneously

Counter-Rationalizations

Shortcut	Counter	Why
"We can skip some steps for this case"	Adapt the workflow steps, don't skip them	Skipped steps are where incidents and oversights originate
"The user seems to already know what to do"	Complete all workflow phases with the user	The workflow catches blind spots that experience alone misses
"This is a minor case, full process is overkill"	Scale the process down, don't turn it off	Minor cases become major when unstructured; the process scales, not disappears
"I'll fill in the details later"	Complete each section before moving on	Deferred details are forgotten; real-time capture is more accurate
"The template output isn't necessary"	Always produce the structured output format	Structured output enables comparison, audit trails, and handoff to other teams

Output Format

Generate a diagnostic report with:

1. Issue summary (user, direction, platform)
2. Diagnostic findings from each step
3. Root cause identified
4. Resolution applied or escalation with details