Delivery Troubleshooting
Test email not arriving? Find the evidence before resending
“I didn’t receive it” describes the result, not the failing layer. Start by validating the address, then trace the send job, provider response, inbox polling, and message rendering step by step.
Freeze the evidence first—don’t keep clicking Send
Repeated resends create multiple jobs and message IDs, making it unclear which message belongs to which action. First record the current recipient address, trigger time, test environment, template version, and job ID from the application logs.
A consistent time reference matters too. Your browser, queue, and provider dashboard may use different time zones, so convert everything to UTC while keeping the original timestamps.
Layer 1: Confirm the address is complete and still valid
Copy the address again from the inbox page instead of typing it from history. Check every character around the @, hidden spaces, and whether your test script still points to an address replaced in the previous run.
Temporary email addresses expire. If the address has expired or you switched inboxes, an old token cannot prove that a new message should appear on the current page. Create a fresh address and send a minimal email first.
Layer 2: Separate business triggers from email execution
A success message on the page does not mean the email job ran. Check that the application created the job correctly, the consumer is online, retries have not been exhausted, and the recipient variable was not overwritten before template rendering.
If the job is stuck in the queue, the receiving system cannot observe it. Fix the consumer or configuration instead of repeatedly refreshing the inbox page.
Layer 3: Read the provider or SMTP response
Find the message ID, acceptance response, rejection code, or bounce event. “Accepted” usually means only that the next hop accepted the request—not that the message reached the final inbox.
For a temporary 4xx error, wait according to your backoff policy. For a permanent 5xx error, correct the domain, recipient address, authentication, or content policy first. Keep the original response instead of recording only “send failed.”
Layer 4: Polling, lists, and message bodies are separate issues
Wait through one polling cycle, then refresh manually while watching the browser’s network requests. If the list shows a subject and sender, the message arrived; if the detail view is empty, inspect the message body data instead of checking DNS again.
Message details may provide html_body or text_body. An isolated HTML template, blocked remote images, or stripped scripts does not mean the email failed to arrive. Compare the plain-text fallback with the original fields.
Layer 5: Build a control with a minimal email
Create a new temporary address and send a fixed subject, a unique event ID, and one plain-text sentence—without images, attachments, or complex variables. If the minimal email arrives, add HTML, brand assets, and business data one at a time.
A control quickly separates basic delivery issues from content-policy issues. Change only one variable at a time; otherwise, even if delivery recovers, you will not know the real cause.
Turn the result into a reusable conclusion
Your conclusion should include the failing layer, direct evidence, corrective action, retest sample, and any limitations that remain unexplained. Don’t leave only “it worked after retrying”—that will not prevent the same issue from recurring.
If you are investigating an active incident, use the Delivery Troubleshooting Lab to generate prioritized checks from four facts.