Skip to content

Email Delivery Failures Playbook

Symptom: Email not delivered or bouncing.

Hypotheses

Hypothesis Likely Cause Evidence Tag
Domain not verified Domain is in Pending or Failed status in Azure Portal [Observed]
SPF/DKIM failure Email rejected by recipient because it failed authentication checks [Measured]
Recipient invalid The destination email address does not exist or has a full mailbox [Observed]
Content filtered Email was blocked due to suspicious content or attachments [Inferred]
Rate limiting Sending more emails than allowed by the current sender tier [Correlated] 
flowchart TD
    S["Email not delivered"] --> H1{"Sender domain verified?"}
    H1 -- no --> R1["Complete domain verification in ACS"]
    H1 -- yes --> H2{"SPF or DKIM failing?"}
    H2 -- yes --> R2["Fix DNS auth records"]
    H2 -- no --> H3{"Recipient invalid or content filtered?"}
    H3 -- yes --> R3["Suppress invalid recipients and revise content"]
    H3 -- no --> H4{"Hitting rate limits?"}
    H4 -- yes --> R4["Throttle sending within limits"]
    H4 -- no --> EV["Collect evidence: delivery reports, metrics, SMTP status"]
    EV --> M["Apply mitigation and confirm next send"]

Evidence Collection

1. Delivery Reports

Query the ACSEmailStatusUpdateOperational table in Log Analytics. Filter for recipient-level rows (isnotempty(RecipientId)) and inspect DeliveryStatus, SmtpStatusCode, and EnhancedSmtpStatusCode. See the ACS Email Logs schema for the full column list.

2. Monitor Metrics

Review the Email Service API Requests and Email Service Delivery Status Updates metrics on the ACS resource. See Monitoring → Email metrics for the canonical metric names and how to chart them.

3. SMTP Status Codes

Look for bounce messages containing standard SMTP status codes (e.g., 550, 554).

Validation

[Observed] Check Domain Verification

Confirm the domain status is Verified in the ACS resource. If it's Pending, messages cannot be sent.

[Measured] Test SPF/DKIM

Use a third-party tool (e.g., Mail-Tester) to send a test email and verify that authentication headers are correct and pass verification.

[Inferred] Review Spam Logs

Filter ACSEmailStatusUpdateOperational for DeliveryStatus in ("FilteredSpam", "Quarantined") on recipient-level rows. Inspect EnhancedSmtpStatusCode for the carrier's reason code.

Mitigation

  1. Complete Verification: Ensure all required DNS records (SPF, DKIM) are correctly added to your DNS provider.
  2. Correct Sender Address: Use only verified sender addresses that match your domain.
  3. Cleanse Recipient Lists: Implement an email verification step to remove invalid or inactive addresses.
  4. Follow Best Practices: Avoid suspicious keywords in the subject line and ensure a valid Unsubscribe link is present.
  5. Request Tier Increase: If consistently hitting rate limits, request a higher sending tier from Azure support.

See Also

Sources

  • Azure Communication Services Email Status Codes
  • Gmail/Outlook Sending Guidelines