Troubleshooting Email Delivery Issues: A Developer’s Guide

Troubleshooting email delivery issues is easier when you treat email as a chain of independent systems rather than a single send operation. A successful API response or SMTP handoff only proves that one link in that chain worked; it does not prove the recipient received, accepted, or saw the message in their inbox.

This guide provides a practical debugging process for transactional email sent through any provider, whether you use a REST API, an SMTP relay, or a self-managed mail transfer agent. It covers application errors, SMTP replies, domain authentication, DNS, message construction, suppression lists, recipient-server deferrals, spam placement, and the evidence you need before escalating a problem.

Start by defining what “not delivered” means

The phrase “email delivery issue” can describe several very different failures. If you do not identify the exact stage where the message stopped, it is easy to spend hours changing DNS records when the real issue is an invalid recipient address, a rejected API request, or an application job that never ran.

For each incident, classify the outcome before trying a fix:

1. The application did not submit a message. Your background job failed, a queue worker stopped, credentials are missing, or code never reached the email call.
2. The provider rejected the submission. An API returned a 4xx error, an SMTP relay rejected authentication, or the sender domain is not permitted.
3. The provider accepted the message but did not attempt delivery yet. The message may be queued, rate limited, scheduled, or awaiting a retry.
4. The recipient server temporarily deferred it. A receiving server responded with a transient 4xx SMTP status, so the sender should retry later.
5. The recipient server permanently rejected it. The recipient address, domain, authentication, reputation, or message policy caused a 5xx response.
6. The recipient server accepted it, but it landed in spam, promotions, quarantine, or another filtered location. This is a placement problem, not a transport failure.
7. The recipient accepted it, but the user cannot find or recognize it. Threading, mailbox rules, forwarding, a confusing subject line, or a mismatch between the expected and actual recipient can all look like non-delivery.

This distinction matters because an HTTP 202 Accepted, SMTP 250 OK, delivery event, and inbox placement are different checkpoints. A 202 usually means an API accepted your request for processing; it is not an end-to-end delivery receipt. Likewise, an SMTP 250 from your outbound relay means the relay accepted your message, while a 250 from the recipient’s mail exchanger means that remote system accepted responsibility for it.

Build an evidence trail before changing anything

The fastest troubleshooting teams preserve the original evidence. Do not begin by resending the same email repeatedly, changing multiple DNS records at once, or rotating credentials without recording what happened. Those actions can erase the signal that identifies the failure.

Create a small incident record containing:

• The application event or job ID that should have triggered the email.
• The provider message ID, if one was returned.
• The exact timestamp in UTC.
• The envelope sender, usually supplied in SMTP as MAIL FROM or called the return-path sender.
• The visible From: address, recipient address, reply-to address, and subject.
• The destination domain, such as gmail.com or a customer’s corporate domain.
• The API status code and response body, or the full SMTP transcript and enhanced status code.
• The event sequence: accepted, queued, delivered, deferred, bounced, complained, or suppressed.
• A copy of the raw message headers from a delivered test email.

Use a unique correlation value for every test. A custom header such as X-Message-Trace: order-confirmation-20260817-8f34 is useful, as is an opaque value in your application logs. Do not put customer secrets, passwords, access tokens, or personally sensitive data in headers because headers travel with the message and may be visible to recipients or support personnel.

For an API integration, log the request outcome and the message identifier returned by the sending service. For an SMTP integration, log the server hostname, port, TLS mode, SMTP command stage, and reply. The most useful minimum SMTP evidence looks like this:

MAIL FROM:<bounce@example.com>
250 2.1.0 OK
RCPT TO:<person@example.net>
250 2.1.5 OK
DATA
354 End data with <CR><LF>.<CR><LF>
...
250 2.0.0 queued as 8F3A12B4

If the failure occurs at RCPT TO, the remote server rejected the recipient or a policy associated with that recipient. If it occurs after DATA, the server accepted the recipient but rejected the content, size, authentication context, or message policy. SMTP reply classes and enhanced status codes are designed to help identify the failing stage; preserve the full response text rather than logging only “send failed.”

Check the application and API layer first

Before investigating deliverability, prove that your application actually created and submitted the intended message. Transactional email often originates from asynchronous jobs, webhooks, serverless functions, queue consumers, or scheduled tasks. A request can appear to work in local development while production has a missing environment variable, an unprocessed queue, an expired credential, or a conditional branch that skips sending.

Separate request acceptance from delivery

REST-based email APIs commonly return a successful 2xx response after validating and accepting the request. A 200 OK, 201 Created, or 202 Accepted does not mean the recipient mailbox has accepted the message. Store the returned message ID, then use provider events, webhooks, logs, or an activity feed to follow it through later states.

A failed API response should be handled according to its class:

• 400 Bad Request: The payload is malformed or contains invalid fields. Inspect JSON structure, required properties, address formatting, and attachment encoding.
• 401 Unauthorized: Credentials are absent, expired, malformed, or sent using the wrong authentication scheme.
• 403 Forbidden: Credentials may be valid but lack permission, the sender identity is unverified, or an account/domain restriction applies.
• 404 Not Found: Often indicates an incorrect endpoint, template identifier, or resource ID.
• 409 Conflict: May indicate an idempotency, resource-state, or configuration conflict, depending on the provider.
• 413 Content Too Large: Common with large attachments or base64-encoded payloads that exceed a request limit.
• 422 Unprocessable Content: The JSON is valid but an email-specific field is invalid, such as a disallowed sender or invalid recipient.
• 429 Too Many Requests: Slow down and retry using the service’s stated retry guidance or a bounded exponential backoff.
• 500, 502, 503, or 504: Treat as potentially transient. Retry safely only if your request is idempotent or protected with a stable idempotency key.

Do not blindly retry every 4xx response. Retrying a malformed payload, an unauthorized request, or an unverified sender only creates noise. Conversely, avoid treating a 5xx response as proof that no message was sent: network timeouts can leave the client uncertain whether the provider accepted the request. Idempotency keys or an application-level send record prevent duplicate receipts when you retry ambiguous failures.

Inspect common payload mistakes

Confirm the address fields are populated with RFC-style mailbox addresses, not display names placed in the wrong field. A valid formatted address is:

Jane Example <jane@example.com>

Avoid constructing headers by string concatenation with untrusted user input. Newline characters in recipient names, subjects, or custom headers can produce malformed messages and may create header-injection risks. Use your provider’s structured address and header fields whenever possible.

Also check whether your code is accidentally sending from a sandbox, test domain, preview environment, or a different region/account than the one whose DNS you configured. A surprisingly common production failure is authenticating mail.example.com while sending From: notices@example.org.

For integrations that need implementation details, consult your provider’s email API reference and setup guides rather than inferring endpoint behavior from a generic HTTP error code.

Diagnose SMTP relay failures by command and status code

SMTP is a conversation. Knowing which command failed provides much more diagnostic value than a generic “connection refused” or “email failed” error.

A typical authenticated submission session looks broadly like this:

S: 220 smtp.example-provider.net ESMTP ready
C: EHLO app.example.com
S: 250-STARTTLS
S: 250-AUTH PLAIN LOGIN
C: STARTTLS
S: 220 Ready to start TLS
C: EHLO app.example.com
C: AUTH PLAIN ...
S: 235 2.7.0 Authentication successful
C: MAIL FROM:<bounce@example.com>
S: 250 2.1.0 OK
C: RCPT TO:<recipient@example.net>
S: 250 2.1.5 OK
C: DATA
S: 354 End data with <CR><LF>.<CR><LF>
C: ...message content...
C: .
S: 250 2.0.0 Queued

Connection, TLS, and authentication problems

A timeout or connection refusal usually occurs before SMTP commands begin. Check the hostname, port, firewall egress rules, container network policy, cloud security group, and whether your provider expects implicit TLS or explicit STARTTLS.

Common submission ports include 587 for message submission with STARTTLS and 465 for implicit TLS. Port 25 is often blocked or restricted by hosting networks to reduce spam. Do not disable certificate validation in production merely to make a connection work. Instead, verify that the hostname matches the certificate and that your runtime trusts current certificate authorities.

SMTP authentication failures commonly return 535 or another 5.7.x reply. Check whether you are using an SMTP credential rather than an API token, whether the username is required to be a literal value or account identifier, and whether the password contains characters that were truncated or incorrectly escaped in an environment variable.

Temporary versus permanent SMTP failures

The first digit of an SMTP reply code is an essential triage clue:

• 2xx: The receiving system accepted the command.
• 3xx: The server expects more information, such as 354 before message data.
• 4xx: A temporary failure. Retry later with controlled backoff.
• 5xx: A permanent failure for that attempt. Correct the address, policy, content, or authentication issue before retrying.

Examples you may encounter include:

• 421 4.7.0: Service unavailable, closing connection, or a temporary policy/rate condition.
• 450 4.2.0: Mailbox temporarily unavailable or a temporary recipient-side condition.
• 451 4.7.1: A temporary local or policy issue; the text may indicate rate limiting, reputation review, or greylisting.
• 452 4.2.2: Insufficient system storage or recipient mailbox over quota, though exact interpretation varies.
• 550 5.1.1: Recipient mailbox does not exist, is disabled, or is unavailable.
• 550 5.7.1: Delivery blocked by policy, reputation, authentication, content, or sender restrictions.
• 552 5.2.2: Mailbox full or a size-related storage problem.
• 554 5.7.1: Transaction failed because of policy or content rules.

Enhanced status codes add useful context. For example, a 5.1.1 generally concerns an invalid recipient mailbox, while 5.7.x generally signals security or policy. Still, do not build automation around one provider’s human-readable text alone. The same numeric code can be used differently by different mailbox operators, so preserve both the enhanced code and the text.

For transient 4xx outcomes, retry gradually. A practical pattern is exponential backoff with jitter, such as retrying after roughly 5 minutes, 20 minutes, 1 hour, 4 hours, and then longer intervals up to a defined expiry window. Do not retry thousands of messages simultaneously after a deferral; that can turn a temporary throttle into a longer block.

Verify DNS and domain authentication

Authentication is foundational, but it is not a magic inbox-placement switch. Correct SPF, DKIM, and DMARC help recipients evaluate whether your domain authorized the message; they do not override poor sending reputation, irrelevant content, or bad recipient data. Major mailbox providers require authentication from senders, and higher-volume Gmail senders must use SPF, DKIM, and DMARC.

SPF: authorize the envelope sender

SPF is published as a DNS TXT record at the domain used in the SMTP envelope sender, also known as the return-path or MAIL FROM domain. A simplified example is:

example.com. IN TXT "v=spf1 include:spf.your-email-provider.example -all"

The include: domain must be the exact domain documented by your email provider. Do not copy the illustrative hostname above into production. If your organization uses more than one legitimate sending service, SPF mechanisms belong in one SPF record, for example:

example.com. IN TXT "v=spf1 include:spf.transactional.example include:_spf.workspace.example -all"

Publishing multiple separate TXT records beginning with v=spf1 can cause an SPF PermError. Also remember that SPF has a DNS lookup limit: complicated chains of includes, redirects, a, mx, and exists mechanisms can exceed the evaluation limit and fail authentication.

Use ~all only when you have a deliberate transitional reason. A final -all states that only the mechanisms listed are authorized. Before tightening policy, inventory every legitimate platform that sends using the same envelope domain, including customer support systems, invoicing tools, workspace mail, monitoring alerts, and marketing platforms.

DKIM: sign messages and publish the public key

DKIM adds a cryptographic signature to the message. A receiver reads the d= signing domain and s= selector from the DKIM-Signature header, then retrieves a TXT record at:

selector._domainkey.example.com

A simplified DNS record format is:

s1._domainkey.example.com. IN TXT "v=DKIM1; k=rsa; p=BASE64_ENCODED_PUBLIC_KEY"

The public key must be supplied by the signing system. Do not generate or edit the p= value manually unless you also control the corresponding private key and understand the signing configuration. DNS control panels sometimes split long TXT values into quoted chunks; that is normal when the resolver reconstructs them as one logical TXT record.

Check that the selector in the message header matches the DNS hostname exactly. A message signed with s=s1; d=example.com will look up s1._domainkey.example.com, not _domainkey.example.com alone. If you rotate selectors, keep the old key published until all messages signed with it have aged out of transit and mailbox processing.

DMARC: align the visible From domain

DMARC evaluates the visible RFC 5322 From: domain and requires alignment with either SPF or DKIM. In practical terms, the domain your recipients see in the From address should align with the domain authenticated by SPF or DKIM.

A basic monitoring record is:

_dmarc.example.com. IN TXT "v=DMARC1; p=none; rua=mailto:dmarc-reports@example.com; adkim=r; aspf=r; pct=100"

p=none asks receivers to monitor rather than request quarantine or rejection. It is useful while you discover legitimate senders, but it is not an enforcement policy. Once reporting shows that authorized mail aligns reliably, many organizations move gradually to p=quarantine and then p=reject.

Relaxed alignment (adkim=r and aspf=r) allows organizational-domain alignment in many common subdomain cases. Strict alignment (s) requires exact domain matches. Strict mode can be appropriate, but it may break mail if your visible From domain is example.com while your authenticated envelope sender or DKIM domain is a subdomain such as bounce.example.com or mail.example.com.

Test DNS from outside your DNS provider

DNS records can look correct in a control panel yet be unpublished, placed at the wrong hostname, duplicated, or blocked by stale delegation. Query public DNS directly:

dig +short TXT example.com
dig +short TXT s1._domainkey.example.com
dig +short TXT _dmarc.example.com
dig +short MX example.com

Tools such as MXToolbox can help spot malformed or conflicting DNS records, while dig gives you a direct view of what a resolver returns. Check from more than one resolver when you suspect propagation or split-horizon DNS. Do not assume DNS changes are instantaneous; the prior TTL and resolver caches affect when recipients observe a new record.

Confirm alignment using raw message headers

The recipient mailbox’s copy of the message is often the most useful artifact in an email incident. Send a controlled test to a mailbox you can inspect, then open the raw source or original message view.

Look for an Authentication-Results: header similar to:

Authentication-Results: mx.google.com;
       spf=pass smtp.mailfrom=bounce.example.com;
       dkim=pass header.d=example.com header.s=s1;
       dmarc=pass header.from=example.com

The exact formatting varies by recipient, but these values answer crucial questions:

• Did SPF pass, and for which envelope sender domain?
• Did DKIM pass, and which d= domain signed the message?
• Did DMARC pass, and which visible From domain was evaluated?
• Did the recipient report a soft failure, neutral result, temporary error, or permanent error?

Do not diagnose DMARC from DNS alone. A valid DMARC record can coexist with DMARC failure if the provider signs with an unrelated DKIM domain and your envelope sender does not align. Conversely, SPF can fail after forwarding while DKIM remains aligned and allows DMARC to pass.

Also inspect Return-Path, From, Reply-To, Message-ID, and the Received chain. The return path identifies the envelope sender used for bounces. The From: header identifies the user-visible author domain used by DMARC. A mismatch is not automatically wrong, but it must be intentional and authenticated.

Check recipient addresses, suppressions, and bounce handling

Many apparent provider problems are recipient-data problems. A hard bounce, a previous complaint, an unsubscribe, or a manually added suppression may stop a provider from attempting delivery at all. That is usually a protective behavior: repeatedly sending to known bad addresses damages reputation and wastes capacity.

Start with the exact recipient address, not just the person’s name in your database. Check for:

• Misspellings such as gmial.com, accidental spaces, or copied punctuation.
• An address that was valid when collected but has since been closed.
• A role mailbox such as support@, billing@, or info@ that has stricter filtering.
• A corporate address protected by a gateway that rejects unfamiliar senders.
• A recipient who previously marked mail as spam or opted out.
• An address suppressed after a permanent bounce.
• A test recipient routed through forwarding or a shared mailbox.

An address verifier can reduce obvious syntax, domain, and mailbox-risk issues before a campaign or import, though no verifier can guarantee that every recipient will accept future mail. For one-off checks during list cleanup, use an email address verification tool alongside your own bounce and complaint history.

Treat permanent bounces as data-quality events. Stop sending to addresses that return clear 5.1.1-style mailbox-not-found outcomes unless the recipient corrects the address. Treat temporary bounces differently: preserve the failure reason, retry according to policy, and avoid immediately suppressing a customer because of a short-lived quota or recipient-server outage.

Distinguish delivery from inbox placement

A recipient server can accept your message and still place it somewhere other than the primary inbox. This is a classification decision made after transport succeeds, often based on a combination of authentication, sender reputation, engagement, recipient behavior, message characteristics, and local filtering rules.

If the recipient server accepted the message, investigate these locations before declaring it missing:

• Spam or junk.
• Promotions, updates, or category tabs.
• Quarantine at a corporate security gateway.
• A mailbox rule, filter, label, or archive action.
• A threaded conversation where the new message is hidden under an existing subject.
• Another mailbox reached through aliasing or forwarding.

Test message quality without relying on a single score

Mail-tester.com is useful for a controlled test because it can highlight common authentication, MIME, header, link, and content issues. It is not a universal prediction of inbox placement; a score from one test mailbox cannot reproduce every recipient’s reputation history or filtering configuration.

Use it to catch concrete problems such as a missing plain-text part, malformed HTML, broken links, missing unsubscribe information where applicable, or obvious authentication errors. Then validate with real seed addresses across the mailbox providers your users actually use.

Message construction problems that affect filtering

Transactional email should look and behave like a legitimate, useful message. Common mistakes include:

• Sending HTML-only email with no meaningful plain-text alternative.
• Using a visible From address that differs from the brand or domain the recipient expects.
• Linking every button through an unrelated tracking domain with weak reputation.
• Including shortened URLs, misleading link text, or mixed HTTP and HTTPS content.
• Attaching unnecessary executable, archive, or password-protected files.
• Reusing a highly promotional subject line for security alerts, receipts, and account notices.
• Using a no-reply address while asking recipients to respond for support.
• Sending large bursts of password resets, receipts, or invitations to addresses that did not initiate the underlying action.

For transactional messages, relevance is a deliverability feature. A password reset should be triggered by an actual request, a receipt should follow a real purchase, and an account alert should clearly explain why the recipient got it. If recipients do not recognize why they received a message, they are more likely to ignore, filter, or report it.

Investigate sender reputation and traffic changes

Authentication proves domain authorization; it does not establish a positive sending reputation. Recipient systems also observe patterns such as bounce rates, complaint rates, sending consistency, domain and IP history, engagement, list quality, and the type of mail you send.

A delivery issue that begins after a traffic change deserves a traffic analysis. Compare the affected period with a known-good period:

1. Volume: Did daily or hourly volume spike sharply?
2. Audience: Did you begin sending to older, imported, purchased, or unengaged addresses?
3. Message type: Did a transactional stream begin carrying promotional content?
4. Domain: Did the visible From, DKIM signing domain, return-path domain, or link domain change?
5. Infrastructure: Did you move providers, rotate IPs, alter TLS settings, or add a new relay?
6. Failures: Did bounce, deferral, complaint, or unsubscribe rates rise at the same time?

Separate transactional and marketing streams whenever your platform permits it. They have different consent expectations, engagement patterns, volume profiles, and operational consequences. A product receipt should not inherit the reputation impact of a broad promotional campaign sent from the same identity without careful planning.

Ramp volume gradually when using a new sending domain or dedicated IP. Sudden high-volume traffic from a previously quiet identity can trigger scrutiny even when every individual message is technically valid. The right ramp depends on your recipient mix and engagement, but the principle is stable: grow in measured steps, watch bounces and complaints, and pause expansion when recipient systems begin to defer or reject mail.

Read provider events and webhook data carefully

A sending platform’s event stream is useful only when you understand what each event means. Names vary by provider, but the general lifecycle commonly includes accepted, processed, delivered, deferred, bounced, complained, unsubscribed, and dropped or suppressed.

A robust application stores provider events independently from the original send request. Do not overwrite a message’s status with the latest event without preserving history. A message can be accepted, deferred, retried, and then delivered; collapsing that timeline into one boolean loses the evidence needed for troubleshooting.

Make webhook processing reliable

Delivery webhooks are asynchronous and can arrive late, more than once, or out of order. Your webhook endpoint should:

• Verify the provider’s signature or authentication mechanism.
• Acknowledge valid events quickly, then process them asynchronously if needed.
• Deduplicate using the provider event ID or a stable composite key.
• Tolerate delivery-before-accepted ordering anomalies in your database model.
• Retain the SMTP response, enhanced status code, and recipient domain when provided.
• Keep a raw event archive with appropriate access controls and retention limits.

Do not use “delivered” as proof that a human read the email. It generally indicates acceptance by the recipient-side server. Use product events, such as a verified email link being clicked or a receipt page being viewed, to measure downstream customer outcomes instead.

Use a controlled test matrix

One test address cannot tell you whether a problem is global, provider-specific, domain-specific, or recipient-specific. Build a small test matrix that reflects your real audience and run it whenever you change sending infrastructure, DNS, templates, or mail libraries.

A useful matrix includes:

Use unique subjects and trace headers for each matrix entry. Inspect raw headers, record the provider event timeline, and note whether the message appeared in inbox, spam, a category tab, or quarantine. This converts deliverability from anecdotal testing into a repeatable release check.

Know when the issue is outside your control

Not every delayed or rejected message is a defect in your application or sending provider. Recipient servers can experience outages, temporary storage pressure, greylisting, local policy changes, or security-gateway problems. An individual recipient may have a full mailbox, a disabled account, an overaggressive rule, or an organization-wide block unrelated to your message.

When you see a transient 4xx response from a recipient domain, your best action is usually to allow the normal retry process to work. If a major destination domain has widespread deferrals, avoid changing authentication records or content prematurely. Gather timestamps, recipient domains, SMTP responses, and event counts, then look for a shared pattern.

For a persistent 5xx policy rejection at one organization, ask the recipient’s mail administrator for the full bounce message and message headers. Provide your sending domain, sending IP if relevant, timestamp in UTC, envelope sender, and recipient address. Do not ask them to “whitelist everything”; request the specific policy reason and correct the underlying issue where possible.

A practical escalation checklist

Escalate to your email provider after you have isolated the failure stage and gathered evidence. A concise, technically complete support request gets a better result than “emails are not arriving.”

Include the following:

• Provider message IDs for several affected messages.
• UTC timestamps and recipient domains.
• The exact SMTP response or API response body.
• Whether the problem affects all mail, one sender domain, one recipient domain, or one template.
• The envelope sender and visible From domain.
• Raw headers from a successful and unsuccessful test, if available.
• Current SPF, DKIM, and DMARC lookup results.
• Whether the issue began after a DNS, content, volume, account, or infrastructure change.
• A statement of whether messages are rejected, deferred, suppressed, delivered to spam, or accepted but not found.

Avoid sending full customer message bodies or unredacted personal data unless support explicitly needs them and you have an appropriate secure process. Often the provider can investigate using message IDs and metadata alone.

Conclusion: troubleshoot the handoff, not the hunch

The most reliable way to solve email problems is to locate the last confirmed handoff. First prove the application submitted a request. Then determine whether the sending service accepted it, whether the recipient server deferred or rejected it, whether SPF/DKIM/DMARC aligned, and whether the message was delivered but filtered.

That sequence prevents the most common troubleshooting mistake: treating all missing email as an inbox-placement problem. With message IDs, SMTP responses, raw headers, DNS lookups, and a controlled test matrix, most delivery incidents become measurable engineering work rather than guesswork.

FAQ

What does an API 202 Accepted response mean for email delivery?

It normally means the email API accepted your request for processing. It does not prove the email was delivered to, accepted by, or placed in the recipient’s inbox. Track the provider message ID through later delivery, bounce, deferral, and suppression events.

Why does SPF pass but DMARC fail?

DMARC requires domain alignment with the visible From: domain. SPF may pass for bounce.example.net, but DMARC can still fail if recipients see From: alerts@example.com and the domains do not align. A passing, aligned DKIM signature can also satisfy DMARC.

Should I retry SMTP 5xx errors?

Usually not without changing something. A 5xx reply indicates a permanent failure for that attempt, such as an invalid mailbox or policy rejection. Correct the recipient, authentication, content, or sender-policy issue first. Retry 4xx responses with bounded exponential backoff because they are generally temporary.

How can I tell whether an email went to spam?

Send a controlled test to a mailbox you can access, inspect the message folders and raw headers, and compare provider event data. A provider “delivered” event usually means the recipient server accepted the message, not that it reached the primary inbox.

Can correct SPF, DKIM, and DMARC guarantee inbox placement?

No. They establish and align sender identity, which is essential, but mailbox placement also depends on reputation, recipient engagement, complaint and bounce patterns, message content, links, sending volume, and recipient-specific filters.