API SMTP Logs: How to Diagnose Email Delivery Failures

API SMTP logs are the fastest way to answer the question every email developer eventually faces: what happened to this message? Used well, they connect an application event to an API request or SMTP session, then to a provider queue, recipient-server response, retries, bounce handling, and—in some cases—final delivery signals.

Email is not a single synchronous transaction. A successful call to an email API or a 250 response from an SMTP relay can mean the message was accepted for processing, not necessarily placed in the recipient's inbox. Good logs let you identify exactly where the chain stopped, whether the fault is temporary or permanent, and which team can fix it.

What API SMTP logs are—and what they are not

API SMTP logs are structured records of email-submission activity. They usually cover two related but distinct paths:

• API logs: Records generated when your application sends an HTTP request to an email provider's REST API.
• SMTP logs: Records generated when your application, server, or mail client submits email through an SMTP relay.

A useful record typically captures a timestamp, request or session identifier, sender domain, recipient domain or a privacy-safe recipient reference, response code, and diagnostic text. It may also include the sending IP address, API key identifier, user agent, SMTP command stage, message identifier, template or campaign reference, and the event timeline after acceptance.

The word log can be misleading because different systems log different points in the mail flow. An application log might prove that your code called sendEmail(). An API access log might prove that the provider returned HTTP 202 Accepted. An SMTP transcript might prove that the relay replied 250 2.0.0. A delivery event may later show that a receiving server deferred or rejected the message. These are complementary pieces of evidence, not interchangeable definitions of delivery.

A reliable investigation starts by naming the stage being observed:

1. Application creation: Your software assembled the message and initiated a send.
2. Submission: Your app received an HTTP response or SMTP reply from the sending service.
3. Provider processing: The service validated the request, applied policy, and placed the message in a queue.
4. Recipient-server handoff: The service attempted SMTP delivery to the destination mail exchanger.
5. Recipient disposition: The recipient server accepted, deferred, rejected, quarantined, or filtered the message.
6. Mailbox placement and engagement: The message reached an inbox, spam folder, tab, or was opened. These are not equivalent and are not all observable.

For a REST API plus SMTP relay platform, the practical objective is the same whichever submission method you choose: preserve enough evidence to correlate the original request with the eventual delivery result. If you are building that integration, keep your provider's API and SMTP setup reference alongside your own application logging and alerting standards.

The delivery path your logs need to reconstruct

A transactional email can travel through several systems in seconds or remain queued for hours when a recipient server is temporarily unavailable. The more accurately you model the path, the less likely you are to misread a successful submission as a successful delivery.

REST API submission

With an API, your application normally makes an HTTPS request containing recipients, sender data, subject, content, headers, attachments, and optional metadata. A typical sequence is:

Application -> HTTPS email API -> validation/policy -> provider queue -> recipient MX -> recipient mailbox

At the first boundary, inspect the HTTP status and response body. Common patterns include:

• 200 OK or 201 Created: The request was processed according to the endpoint's contract.
• 202 Accepted: The provider accepted the request for asynchronous processing. It is not proof of recipient delivery.
• 400 Bad Request: The payload was malformed or failed validation, such as invalid JSON, an invalid address structure, or missing required fields.
• 401 Unauthorized or 403 Forbidden: Credentials are invalid, missing, expired, restricted, or lack permission for the sending domain.
• 413 Payload Too Large: Attachments or the total request body exceed a limit.
• 422 Unprocessable Content: The JSON is valid but contains semantically invalid data, depending on the API's design.
• 429 Too Many Requests: Your application exceeded a rate limit and should obey retry guidance.
• 500, 502, 503, or 504: A service-side or gateway failure; retry only when your idempotency design makes doing so safe.

Do not treat the numeric code alone as the complete diagnosis. Store the response body, request ID, and any provider-specific error code in a secure log. If a provider returns a message identifier, persist it next to your own order ID, user ID, password-reset ID, or notification ID. That relationship becomes essential when a customer says they did not receive a message hours later.

SMTP relay submission

SMTP submission is a stateful text protocol. A simplified authenticated session might look like this:

S: 220 smtp.example.net ESMTP ready
C: EHLO app.example.com
S: 250-smtp.example.net
S: 250-STARTTLS
S: 250 AUTH PLAIN LOGIN
C: STARTTLS
S: 220 Ready to start TLS
C: EHLO app.example.com
S: 250 AUTH PLAIN LOGIN
C: AUTH PLAIN <credentials omitted>
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 as abc123
C: QUIT
S: 221 2.0.0 Bye

The relay can reject at several points. 535 5.7.8 commonly indicates authentication failure. A rejection after MAIL FROM may point to an unverified sender, sender policy, or relay authorization issue. A failure at RCPT TO can identify a bad address, a suppression-list match, an account rule, or a destination-level condition. A response after DATA often means the message was accepted into the relay queue, but it still does not guarantee the final recipient accepted it.

For security, never retain raw SMTP credentials, complete AUTH command values, full message bodies, or access tokens in routinely accessible logs. Redact secrets before log export and restrict access to the source records.

The fields every useful log record should contain

A log is useful only when it can answer a specific operational question. Rather than collecting every possible field indiscriminately, collect the fields needed to correlate, classify, and reproduce an event without exposing unnecessary personal data.

A strong event model includes the following categories.

Identity and correlation fields

Use identifiers that join events across your systems:

• Your application event ID: For example, password_reset:usr_8421:evt_01J....
• Provider message ID: The identifier returned after the provider accepts the message.
• RFC message identifier: The outbound Message-ID header, if available.
• Request ID or SMTP queue ID: An identifier for the API call, SMTP session, or queued message.
• Idempotency key: A value that helps avoid duplicate sends after a timeout or retry.
• Template/version ID: Essential when only one release produces malformed content or unexpected headers.

Do not rely on the recipient address as your primary correlation key. People can receive more than one email, addresses can be shared, and retaining full addresses in broad-access logs creates privacy and security risk. Consider storing a normalized, salted hash for operational correlation and keeping cleartext only in the systems that genuinely need it.

Delivery context

Capture the information necessary to explain routing and authentication:

• Envelope sender, also called MAIL FROM or Return-Path identity.
• Header From domain and reply-to domain.
• Recipient domain, and recipient address only where justified.
• IP address or relay identity used for delivery, if provided.
• Sending domain and DKIM signing domain.
• API key label or credential principal, not the secret itself.
• SMTP host, port, TLS mode, and negotiated TLS result.
• Submission route: API, SMTP, background worker, or manually triggered resend.

This context matters because mail authentication evaluates different identities. The visible From: header is what recipients see. SPF generally evaluates the envelope sender domain against the IP or authorized infrastructure. DKIM evaluates the domain in the d= signing tag. DMARC evaluates whether the visible From: domain aligns with a passing SPF or DKIM identity.

Outcome and diagnostic fields

The results should be recorded as both machine-readable values and the original diagnostic evidence:

• HTTP status and API error code.
• SMTP three-digit response code.
• Enhanced status code, such as 5.1.1 or 4.7.0, when present.
• Full remote-server diagnostic text, with personal data redacted when appropriate.
• Event state: accepted, queued, delivered, deferred, bounced, rejected, suppressed, complained, opened, or clicked.
• Attempt number, next retry time, and final attempt time.
• Recipient MX hostname or receiving system, if available.

The enhanced status code is especially valuable because it separates the general SMTP outcome from a more specific condition. The three-part format is class.subject.detail. For example, 5.1.1 denotes a permanent failure associated with the destination mailbox or address, while 4.7.0 is commonly used for a temporary security or policy-related condition. Receiver wording varies, so preserve both the numeric codes and the text.

How to read SMTP response codes correctly

SMTP reply codes are the common language of mail transport, but they require context. The first digit is the most important indicator of whether an error is broadly successful, transient, or permanent.

Important 2xx and 3xx replies

250 2.0.0 generally means the server accepted the command or message. When returned by your submission relay after DATA, it usually means the relay queued the message. When returned by the recipient's MX after a delivery attempt, it means that receiving server accepted responsibility for the message. In neither case does it prove the email appeared in the inbox rather than a spam folder or another destination folder.

235 2.7.0 commonly indicates successful SMTP authentication. 354 means the server is ready for the message body and expects the client to finish data with a line containing only a period. A 220 response is normally a service greeting or confirmation that TLS negotiation can begin.

Common temporary failures

A 421 response can mean a service is unavailable, closing the connection, overloaded, or applying a connection policy. 450, 451, and 452 generally represent temporary mailbox, processing, storage, or policy conditions. The enhanced code and text determine the appropriate response.

Examples include:

421 4.7.0 Temporary system problem. Try again later.
451 4.3.0 Temporary lookup failure.
452 4.2.2 Mailbox full.

A temporary reply is not an instruction to have every layer retry immediately. If your email provider queues and retries recipient delivery, your application should not resubmit the same message simply because it sees an asynchronous deferred event. That creates duplicates. Instead, let one layer own delivery retries and use a distinct retry strategy for failed submission requests.

Common permanent failures

550, 551, 552, 553, and 554 are commonly used for permanent failures, but their exact meaning depends on the enhanced code and recipient-server text.

550 5.1.1 User unknown
550 5.7.1 Message rejected due to policy
552 5.2.2 Mailbox full
553 5.1.3 Invalid recipient address
554 5.7.1 Transaction failed

A 550 5.1.1 is usually a strong signal to stop sending to that address and place it on a bounce or suppression list. A 550 5.7.1 is not necessarily a bad address; it can indicate a domain-authentication, reputation, content, IP, or recipient policy issue. Treating every 5xx response as an address problem will damage your data quality and hide deliverability problems.

Also be cautious with the term soft bounce. In operational usage, it usually means temporary failure, but a mailbox-full condition can be conveyed with a permanent code by some systems. Your classification should use the actual reply, enhanced code, receiver text, and your provider's documented event semantics—not a simplistic label alone.

Debugging API failures before email reaches SMTP

When an API call fails, there may never have been an SMTP transaction. This is good news: the failure is often deterministic and reproducible from your application.

Start by comparing the exact request your application intended to send with the request your provider received. Use a secure request capture or structured application log, not browser-console output or pasted production credentials.

A practical API investigation sequence

1. Find the application event. Record the user action, job ID, deployment version, timestamp, and idempotency key.
2. Find the API request ID. Pair your event with the provider's request ID and HTTP status.
3. Read the response body. A human-readable message may reveal an invalid sender domain, a malformed header, a missing recipient, or an exceeded quota.
4. Validate payload construction. Check JSON encoding, recipient objects, Unicode handling, attachment encoding, header line breaks, and required fields.
5. Check authorization scope. Confirm the credential is active and allowed to send for the chosen domain or environment.
6. Decide whether retry is safe. Retry temporary transport failures only with an idempotency key or deduplication design.
7. Trace asynchronous events. Once the provider accepts the request, use the returned message ID to follow queue, delivery, bounce, and complaint events.

A timeout requires special care. If your application times out after submitting a request, the provider may still have accepted and queued the message. Retrying blindly can send two password-reset links, receipts, or account alerts. Use an idempotency key if the provider supports one, or record a durable outbound event before submission and reconcile its final state by message ID.

For webhook-driven status updates, verify signatures according to your provider's documentation, store the raw event safely, and make webhook processing idempotent. Delivery webhooks can arrive more than once or out of order. Your state machine should handle queued -> delivered, queued -> deferred -> delivered, and queued -> bounced without allowing an older event to overwrite a newer terminal state.

Diagnosing SMTP authentication, TLS, and relay problems

SMTP logs are most valuable when they include the command stage where a session failed. Authentication issues look different from TLS negotiation errors, sender authorization failures, and recipient rejections.

Authentication failures

Typical evidence includes 535, 534, or enhanced 5.7.x responses. Check the credential type expected by the provider: many services use SMTP-specific usernames and generated credentials rather than an account password. Verify that your environment variables have no accidental whitespace, quote characters, or stale secrets.

Avoid logging the AUTH payload. Instead, log that authentication was attempted, the credential label or non-secret identifier, the SMTP host and port, the result code, and the timestamp. If a compromised credential is suspected, rotate it immediately and then correlate activity by credential label, IP address, and time window.

TLS and connection failures

Connection failures can happen before SMTP authentication begins. Common symptoms include certificate validation errors, handshake failures, connection timeouts, or a network policy blocking outbound SMTP ports.

Use the transport settings your provider documents. In general, port 587 is commonly used for message submission with STARTTLS, while port 465 is commonly used for implicit TLS. Do not assume a provider supports every port or every authentication mechanism. A log should show the configured endpoint, port, TLS mode, connection error, and, where appropriate, the certificate-validation failure.

If a service advertises STARTTLS, the client should negotiate TLS before supplying credentials. A transcript that shows authentication before TLS is a security problem unless the connection is already protected by implicit TLS. Do not disable certificate validation to make a production integration work; fix the host, system trust store, clock, or network interception issue instead.

Sender and relay authorization failures

A relay may accept authentication but reject MAIL FROM because the envelope sender uses a domain that has not been verified or is not permitted for that credential. You may see a 553 or 550 5.7.1 response with wording about sender verification, relay access, or policy.

Check all three sender identities: the envelope sender, visible From address, and DKIM signing domain. A message can be syntactically valid while using a combination of identities that cannot pass DMARC alignment or violates a provider's domain policy.

DNS authentication issues revealed by delivery logs

A large share of recipient-side rejections and spam-folder complaints originate in authentication or identity misalignment. API SMTP logs will not always state the full DNS problem, but they can reveal patterns: failures cluster by recipient domain, diagnostics mention SPF, DKIM, DMARC, unauthenticated mail, or policy, and messages using one sender domain perform worse than those using another.

SPF: authorize the infrastructure that sends mail

SPF is published as a DNS TXT record at the domain used for the envelope sender. A simplified example is:

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

Replace the include: domain and IP address with values supplied by the actual sending services you authorize. Never copy the example literally. Publish one SPF policy record for a domain, then combine all legitimate sending mechanisms into that single record.

The final qualifier matters. -all is a hard fail for sources not listed; ~all is a soft fail; ?all is neutral. Your policy choice should follow a complete sender inventory, not guesswork. SPF also has a DNS-lookup limit, so a long chain of nested include, a, mx, and redirect mechanisms can produce a permerror rather than a pass.

DKIM: publish the public key for the signing selector

DKIM adds a cryptographic signature to a message. The sending system signs with a private key and receiving systems retrieve the public key from DNS using the selector in the message's DKIM-Signature header.

A DNS record format looks like this:

selector1._domainkey.example.com. IN TXT "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A..."

The selector is not universal. It must match the s= value in the message's DKIM signature, and the signing domain must match the d= value. Providers often generate the selector and key material for you. Publish their exact record, preserve long TXT values correctly, and do not insert unintended spaces or quotation marks in DNS management interfaces.

A DKIM failure in logs can stem from a missing DNS record, a selector mismatch, a key rotation performed in the wrong order, an unsupported algorithm, or content modified after signing by an intermediate system. Inspect the original message headers from a test mailbox to see dkim=pass or dkim=fail, the d= domain, and the s= selector.

DMARC: require alignment with the visible From domain

DMARC builds on SPF and DKIM. It evaluates whether SPF or DKIM passes and aligns with the domain in the visible From: header. A baseline monitoring record looks like this:

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

p=none requests monitoring rather than enforcement. After you have inventoried every legitimate sender and corrected failures, you may progress deliberately to p=quarantine or p=reject. Do not move to enforcement just because a single test message passes; review aggregate reports over time and account for every service that sends mail using your domain.

DMARC policy is not an inbox-placement guarantee. It is an authentication and handling framework. Recipient systems still make independent decisions using message content, reputation, user behavior, complaint signals, and local policy.

A repeatable workflow for investigating a missing email

When a user says, “I did not get the email,” avoid beginning with assumptions about spam folders or provider outages. Follow a consistent evidence chain.

Step 1: Define the exact message

Identify the recipient, intended sender, approximate send time with timezone, message type, application event ID, and environment. A password reset generated in staging is different from the same template sent in production. If possible, capture the visible subject and the business action that triggered it.

Step 2: Prove whether the application attempted a send

Search your application logs for the durable event and outbound job. Confirm whether the worker picked up the job, whether template rendering succeeded, and whether the email library made an API request or SMTP connection. Template errors, serialization problems, background-worker crashes, and database rollbacks can prevent submission entirely.

Step 3: Inspect the API or SMTP submission outcome

For API sends, locate the HTTP status, response body, request ID, and returned message ID. For SMTP, locate the final response after DATA, not merely the connection or login result. A successful TCP connection and 235 authentication reply do not mean the message was accepted.

Step 4: Follow the message through queue and delivery events

Find the provider message ID and inspect events chronologically. Look for accepted, queued, delivered, deferred, bounced, suppressed, or rejected states. If delivery was deferred, inspect the response and the planned retry. If it was bounced, preserve the full SMTP code and diagnostic text.

Step 5: Classify the failure domain

Use the evidence to choose the owner:

• Application team: Invalid payload, duplicate logic, template rendering, wrong configuration, bad credentials, or poor retry behavior.
• Domain/DNS team: SPF, DKIM, DMARC, tracking-domain, or sender-domain configuration.
• Email operations team: Reputation, suppression handling, sending patterns, segmentation, complaint rate, and recipient-domain trends.
• Recipient or user: Full mailbox, typo, forwarding issue, local filter, or mailbox rule.
• Provider or network: API outage, relay incident, connection failure, or an ongoing recipient-MX issue.

Step 6: Test without contaminating production data

Use a dedicated test recipient under a domain you control, plus seed accounts at major mailbox providers when appropriate. Send a unique test token in the subject or custom header so it can be found in logs. Review the raw headers in the received message and compare authentication results across destinations.

Tools such as mail-tester.com can provide a practical message-content and authentication check for a test send. MXToolbox can help inspect public DNS records and mail-exchanger configuration. For Gmail-specific aggregate diagnostics, Google Postmaster Tools can surface domain-level signals such as authentication, spam rate, reputation, and delivery errors when you meet its eligibility requirements. These tools complement logs; they do not replace a message-level correlation ID.

Turn logs into operational signals, not an archive

A dashboard full of individual events is useful for support tickets, but production email reliability depends on trends. Aggregate API SMTP logs by time, sender domain, credential label, template, recipient domain, response family, and release version.

Monitor metrics such as:

• API request error rate by endpoint and status code.
• SMTP authentication failures by credential and source IP.
• Submission acceptance rate versus eventual delivery rate.
• Deferred volume and age of the oldest deferred messages.
• Hard-bounce rate by sender domain, template, acquisition source, and recipient domain.
• 5.7.x policy or authentication failures by destination domain.
• Suppression events and attempted sends to suppressed recipients.
• Delivery latency from acceptance to recipient-server handoff.
• Duplicate-send rate, measured through idempotency or business event IDs.

Alert on changes, not only absolute counts. Ten 550 5.1.1 bounces may be normal at a large volume. A tenfold increase after a new signup flow, import, sender-domain change, or release deserves attention. Similarly, a rise in 4.7.0 responses from one major recipient domain can indicate throttling, policy enforcement, or reputation trouble before it becomes a broad delivery incident.

Retention and access controls matter as much as observability. Email logs can contain addresses, IPs, subjects, headers, and business metadata. Set a retention period that supports debugging and compliance requirements, redact message content by default, encrypt exports, limit access by role, and document who can retrieve raw delivery evidence.

Common mistakes that make API SMTP logs less useful

The most expensive email incidents are often made worse by incomplete instrumentation or by reading the available evidence incorrectly.

Mistaking acceptance for delivery

An HTTP 202 or relay 250 is a successful handoff to the next system. It is not a statement about inbox placement. Keep separate metrics for API acceptance, relay queueing, recipient-server delivery, and engagement.

Retrying the wrong layer

If your provider already retries recipient-server 4xx responses, resubmitting the original request from your application risks duplicates. Conversely, if an API request never reached the provider due to a network timeout, a carefully idempotent retry may be necessary. Design the ownership boundary explicitly.

Discarding diagnostic text

A single field called bounce_reason is not enough. Keep the SMTP code, enhanced code, receiving hostname, and sanitized response text. A generic “rejected” label cannot distinguish a nonexistent mailbox from DMARC failure or a reputation block.

Logging secrets or full email content

SMTP passwords, API tokens, reset links, invoice details, and HTML bodies should not appear in general-purpose logs. Redaction is not optional. It is part of operating email infrastructure safely.

Treating every bounce as a list-quality problem

5.1.1 often suggests an invalid mailbox. 5.7.1 can point to policy, authentication, content, IP, or reputation. Segment bounce reporting by enhanced code and destination domain before suppressing addresses or changing acquisition practices.

Changing DNS without validating alignment

Adding an SPF record or enabling DKIM does not automatically make DMARC pass. Verify the visible From domain, envelope sender domain, and DKIM d= domain as they actually appear on received test messages. Then validate public DNS lookup results after propagation.

Conclusion: make each send traceable from code to recipient server

The purpose of API SMTP logs is not simply to collect error messages. It is to create a defensible chain of evidence from the business event that triggered an email through submission, queueing, retries, recipient-server responses, and final classification.

For day-to-day debugging, start with a stable application event ID and connect it to an API request ID, SMTP queue ID, provider message ID, and any eventual bounce or delivery event. For long-term reliability, aggregate those records into trends by sender, recipient domain, template, and response type. That combination helps you distinguish an invalid address from an authentication failure, an API problem from a recipient deferral, and a one-off support request from a systemic deliverability issue.

FAQ

What is the difference between API logs and SMTP logs?

API logs show HTTP-based submission requests and responses, such as 202, 400, or 429. SMTP logs show the stateful mail-submission conversation and SMTP replies such as 250, 451, or 550. Both can lead to the same delivery pipeline, but they diagnose failures at different boundaries.

Does 250 2.0.0 mean an email reached the inbox?

No. It means the server that returned the response accepted the relevant SMTP command or message. If your sending relay returned it, the message may only be queued. If the recipient MX returned it, the recipient server accepted responsibility, but the message can still be filtered to spam or another folder.

Should I retry a 4xx SMTP error?

Usually, yes—but only one layer should own delivery retries. Most transactional email providers retry recipient-server temporary failures automatically. Your application should generally retry failed API submission only when it can do so safely with idempotency protection.

Which DNS records should I check when logs show authentication failures?

Check the SPF TXT record for the envelope sender domain, the DKIM selector record at selector._domainkey.example.com, and the DMARC TXT record at _dmarc.example.com. Then confirm that either SPF or DKIM passes with alignment to the visible From: domain.

What information should never appear in email logs?

Do not log API keys, SMTP passwords, authentication payloads, password-reset URLs, raw attachment contents, or complete message bodies in broadly accessible systems. Prefer message IDs, hashes, redacted headers, and structured diagnostic fields.