Email API Status and Incidents: A Developer’s Guide

Email API status and incidents can be deceptively difficult to diagnose because a message may fail before submission, during provider processing, at the recipient server, or after acceptance in the recipient’s mailbox pipeline. The fastest response is not guessing whether “email is down,” but identifying exactly which stage is unhealthy and collecting evidence that separates a platform incident from an application, account, DNS, or deliverability problem.

What counts as an email incident?

An email incident is any unexpected condition that prevents email from being submitted, processed, delivered, tracked, or observed as expected. That definition is broader than a provider outage. A transactional email system has several independent layers, and a failure in one layer can look identical to a failure in another unless you inspect the available signals.

For example, an application may receive an HTTP 401 Unauthorized response because its API key is wrong. That is an integration issue, not an email infrastructure outage. A relay may return 421 4.7.0 because a recipient network is temporarily deferring messages due to rate limits or reputation controls. That can be a recipient-side delivery issue even while the sending provider is operating normally.

A useful incident model divides the sending path into these stages:

1. Application creation — your code renders content, selects recipients, and creates a sending request.
2. Authentication and submission — your service authenticates to a REST API or SMTP relay and submits a message.
3. Provider acceptance and processing — the email platform validates the request, queues the message, applies policy, signs it when configured, and attempts delivery.
4. Recipient-server delivery — the receiving mail exchanger accepts, defers, or rejects the SMTP transaction.
5. Mailbox placement and rendering — accepted mail is filtered into the inbox, a tab, spam, quarantine, or another folder.
6. Events and observability — webhooks, logs, message IDs, bounce events, and delivery records make the outcome visible to your systems.

The distinction matters because “accepted by the API” is not the same as “delivered to the recipient server,” and “delivered” is not the same as “seen in the inbox.” During an incident, use language that preserves those distinctions. It prevents a temporary recipient deferral from becoming an inaccurate claim that every message was lost.

Start with the provider status page, but do not stop there

A provider status page is the appropriate first stop when failures are widespread, sudden, and correlated in time. Good status pages report component-level health, active incidents, scheduled maintenance, incident updates, and historical events. Subscribe to email, RSS, webhook, or status-notification updates if your provider offers them, particularly for a production system with customer-facing transactional mail.

However, a green status page does not prove that your messages will be delivered. Status pages generally reflect the provider’s shared services: API endpoints, SMTP submission, queues, dashboards, webhooks, or specific regions. They cannot reliably represent every sender domain, every account policy, every recipient domain, or every destination mailbox provider.

Signals that point to a platform-wide incident

Treat a provider incident as plausible when several of the following are true at once:

• Errors begin abruptly at a specific timestamp without a deployment or configuration change on your side.
• Multiple unrelated applications, domains, or customers are affected.
• Both SMTP and REST submission fail, or API submission and event retrieval fail together.
• Error rates rise across multiple recipient domains rather than only Gmail, Microsoft 365, Yahoo, or one corporate destination.
• Provider dashboards, APIs, documentation, or status endpoints are also unavailable or slow.
• The provider’s status page identifies a degraded component, active incident, or maintenance window matching your symptoms.

A provider may operate both a REST API and an SMTP relay. If your REST API requests fail while SMTP submission continues normally, the incident scope may be limited to one interface. Conversely, successful submission through both interfaces does not guarantee downstream delivery if queues or recipient destinations are degraded.

Signals that point somewhere else

A status page is less likely to explain the issue if failures affect only one API key, one sending domain, one recipient segment, or messages with one particular template. Look first for account-level restrictions, a changed DNS record, an expired credential, a malformed request, a suppressed recipient, a new attachment, or a sending-rate spike.

It is also common for a provider to report normal operation while a large mailbox provider is deferring or rejecting a specific sender. In that case, the outbound email service may be functioning exactly as designed: it accepts your mail, attempts delivery, records recipient-server responses, and retries temporary failures.

Build an evidence timeline before changing anything

Incident response becomes much easier when every investigation begins with a time-bounded sample. Avoid making DNS, template, or retry changes before preserving evidence. Those changes can hide the original cause and make it difficult to determine whether a fix actually worked.

Start a timeline using UTC. Record when the first failure occurred, when it was detected, the last known successful send, and any deployments or operational changes in the preceding 24 hours. Include message identifiers from your application and the email provider whenever available.

Minimum evidence to capture

For each representative failure, preserve:

• The timestamp in UTC.
• Your internal request or job ID.
• The email provider’s message ID, submission ID, or queue ID.
• The API response status and response body, excluding secrets.
• The complete SMTP reply, including enhanced status code and diagnostic text.
• The sender address, envelope sender, and recipient domain. Redact the recipient local part where appropriate.
• The recipient domain category, such as Gmail, Microsoft 365, Yahoo, a corporate domain, or a test mailbox.
• The event sequence: submitted, accepted, queued, delivered, deferred, bounced, complained, or suppressed.
• A copy of relevant DNS lookups and their TTL values.
• The deployment, credential rotation, DNS edit, traffic change, or template change nearest to the incident start.

A single message is rarely enough. Compare a small but diverse sample: five to ten failures across different recipient domains, plus several known-successful messages. The goal is to find the common variable. If every failed message targets one corporate domain while Gmail succeeds, investigate the destination and its policy. If all recipient domains fail at the same moment with 5xx submission errors, focus on your integration or the provider’s submission layer.

Use correlation instead of anecdotes

A customer saying “I did not receive the password reset email” is valuable, but it is not a diagnosis. Check whether the message was created, whether your service attempted submission, whether the provider accepted it, whether a recipient MX accepted it, and whether a bounce or deferral followed.

The evidence may reveal a different product issue. For example, a password-reset endpoint could successfully request email delivery, but a background worker may be stuck before it calls the email API. In that situation, inspecting the provider status page alone will not help because no message ever reached the provider.

Interpret REST API errors correctly

A REST email API normally communicates submission failures with HTTP status codes. The status class tells you whether a request succeeded, needs correction, needs authentication, is rate-limited, or should be retried. Always inspect both the status code and the response body, because providers frequently add a machine-readable error code, parameter name, request ID, or retry guidance.

Common HTTP status codes in email sending

A 202 Accepted response is especially important in transactional email. It usually means the platform accepted the request for asynchronous work; it does not mean the receiving mail server has accepted the message. Your application should treat the submission response as one event in a longer lifecycle.

Safe retries and idempotency

Network timeouts are ambiguous. Your client may time out after the provider already accepted the message. Blindly retrying can send duplicate receipts, login links, invoices, or password-reset emails.

Use an idempotency key if the provider supports it. If it does not, create your own durable send record before submission. Associate that record with a stable business event ID, such as order_84721_receipt_v1, and record the provider message ID after acceptance. When a timeout occurs, query available message logs or events before retrying; if you cannot query, retry only under a carefully designed deduplication policy.

A practical retry schedule for transient submission errors is exponential backoff with jitter, such as 5 seconds, 20 seconds, 1 minute, 5 minutes, and 15 minutes. The exact schedule should reflect the urgency of the message and the provider’s documented limits. Do not retry 400, 401, 403, or most 422 responses unchanged, because those are normally deterministic errors rather than temporary conditions.

For implementation details such as authentication, request formats, and provider-specific error bodies, consult the relevant email API reference and setup guides rather than assuming all REST APIs use identical fields or retry semantics.

Read SMTP replies as operational evidence

SMTP responses are generated at different stages of an email transaction: connection, greeting, authentication, envelope sender, recipient, message data, or final queue acceptance. The first digit in the basic SMTP reply code is the fastest classification:

• 2xx means success or acceptance at that SMTP step.
• 4xx means a temporary failure; retrying later may succeed.
• 5xx means a permanent failure for that attempt; correct the underlying problem before retrying.

Modern diagnostics often pair the three-digit SMTP reply with an enhanced status code such as 4.2.0 or 5.1.1. The first enhanced digit similarly indicates success, persistent transient failure, or permanent failure. The remaining digits classify the broad subject and detail, but providers can include their own explanatory text and policies.

Common SMTP failures and what they usually mean

The human-readable response matters. 550 5.7.1 is not one universal diagnosis. A receiving server may use it for failed authentication, IP reputation, missing reverse DNS, policy blocks, spam-like content, or an unauthorized sender. Your incident record should preserve the original line rather than reducing it to “SMTP 550.”

Temporary does not mean harmless

A 4xx response is not a delivery failure yet, but it can become one if the retry window expires or the recipient keeps deferring mail. Large clusters of 421, 450, or 451 replies can delay password resets, confirmations, and alerts even when eventual delivery succeeds.

Measure deferrals separately from hard bounces. A rising deferral rate can indicate recipient throttling, a mailbox-provider outage, an overly aggressive sending burst, a reputation issue, or an internal queue backlog. It is an early-warning metric, not merely a background retry detail.

Separate provider outages from recipient delivery problems

The most useful operational question is often: “Where did the message stop?” Answer it with a decision tree rather than a general health check.

A practical triage flow

1. Did your application create the send job? If not, inspect application errors, queues, feature flags, templates, and background workers.
2. Did the application reach the REST API or SMTP relay? Check DNS resolution, TCP/TLS connection failures, HTTP client logs, SMTP connection logs, and credentials.
3. Did the provider accept the message? Look for an API acceptance response, SMTP 250 acceptance, or a provider message ID.
4. Did processing fail before outbound delivery? Check validation, sender identity, account policy, suppression, attachment, and rendering errors.
5. Did the recipient MX accept the message? Inspect delivered, deferred, bounced, and recipient-SMTP event details.
6. Was the message accepted but placed outside the inbox? Inspect recipient folders, authentication results, message headers, and content signals.

This model avoids a common mistake: treating every undelivered message as a provider outage. A provider can be healthy while your domain’s SPF record is malformed, your DKIM selector is missing, your From address does not align with DMARC, or a recipient domain rejects only your messages.

Test across recipients, not just addresses

Use controlled test recipients at more than one mailbox provider. A sensible baseline contains at least one Gmail mailbox, one Microsoft 365 or Outlook mailbox, one Yahoo mailbox, and a domain you control. If only one provider experiences deferrals or spam placement, you have a much narrower investigation.

Do not use production customers as your only monitoring surface. Seed addresses let you send known test content at a predictable cadence and detect delays before support tickets arrive. Record the submission time, delivery event time, actual inbox arrival time where possible, folder placement, and message authentication results.

DNS and authentication problems that resemble incidents

DNS changes and domain-authentication failures are among the most frequent causes of email disruption. They may begin after a provider migration, a registrar change, a DNS cleanup, a new subdomain, a security-policy rollout, or an accidental replacement of an existing TXT record.

DNS propagation is not instant. Resolvers may retain cached records until the published TTL expires, and different recursive resolvers may temporarily show different results. During an incident, record both the authoritative configuration and public lookup results rather than relying solely on what appears in your DNS control panel.

SPF: authorize every legitimate sender

SPF is published as a TXT record at the sending domain. A representative record might look like this:

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

This example authorizes the systems described by spf.email-provider.example and the IPv4 address 198.51.100.25. The -all mechanism expresses a hard fail for other sources. The exact include: hostname must come from the email provider’s verified setup instructions; never copy a placeholder or an include value intended for another service.

Publish one SPF policy record for a domain, not multiple separate v=spf1 TXT records. Multiple SPF records can create a permanent SPF error. Also watch the SPF DNS-lookup limit: nested include, a, mx, redirect, and exists mechanisms can push evaluation beyond the allowed lookup budget. A record that looks valid in a DNS console may fail at recipient evaluation time.

SPF authenticates the SMTP envelope sender domain, sometimes called the Return-Path or MAIL FROM domain. It does not automatically authenticate the visible From: header that users see. That difference is central to DMARC alignment.

DKIM: prove message integrity and domain control

DKIM uses a public key in DNS and a corresponding private key held by the sending system. The provider usually supplies a selector and a DNS hostname. A generic DKIM record resembles this:

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

The p= value is a long public key and must be copied exactly. Some DNS interfaces split long TXT values visually or require quoted chunks; that can be normal, but the published lookup must reconstruct the intended value. A missing selector, truncated key, wrong record name, stale CNAME target, or unsupported signing domain can lead to authentication failures that appear only after recipient delivery attempts.

When diagnosing DKIM, inspect the received message headers for DKIM-Signature and Authentication-Results. Look for the signing domain in d=, the selector in s=, and the verifier’s result, such as dkim=pass or dkim=fail.

DMARC: require alignment, not just a passing check

DMARC is published at _dmarc as a TXT record. A cautious monitoring record can look like this:

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

A stricter enforcement-oriented record might be:

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

DMARC passes when either SPF or DKIM passes and the authenticated domain aligns with the domain in the visible From: header. With relaxed alignment (aspf=r or adkim=r), related subdomains can align under the same organizational domain. Strict alignment (aspf=s or adkim=s) requires an exact match.

Do not switch straight to p=reject without reviewing reports and all legitimate sending sources. Transactional email, customer-support platforms, invoicing systems, marketing tools, and internal mail services may each sign or use envelope domains differently. A DMARC policy can prevent spoofing, but an incomplete deployment can also reject legitimate mail.

DNS tools to use during an incident

Use more than one lookup method because resolvers and interfaces can cache differently. Useful tools include:

• dig or nslookup for direct command-line TXT, MX, CNAME, and A/AAAA checks.
• MXToolbox for public MX, SPF, DKIM, DMARC, blacklist, and SMTP diagnostics.
• mail-tester.com for a controlled content, header, authentication, and spam-score test.
• A dedicated DMARC-reporting service for aggregate-report visibility across all authorized senders.
• Your provider’s domain-verification logs or API, where available, to compare its validation result with public DNS.

Example commands:

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

Do not paste API keys, SMTP passwords, full recipient lists, or sensitive message bodies into public diagnostic tools.

Monitor the full delivery path, not only uptime

A status page is useful for shared infrastructure, but your own monitoring should measure the experience your application needs. For most transactional systems, the key question is not “is the provider up?” It is “can a real customer receive a critical message within the expected time?”

Metrics worth alerting on

At minimum, track these metrics by provider interface, sending domain, message type, and recipient domain:

• Submission attempts and submission success rate.
• HTTP error rate by status code.
• SMTP authentication failures and connection failures.
• Accepted, queued, delivered, deferred, bounced, and suppressed counts.
• Time from application request to provider acceptance.
• Time from provider acceptance to recipient-server delivery.
• Deferral rate and retry age.
• Hard-bounce rate and policy-rejection rate.
• Webhook delivery failures and event-processing lag.
• Authentication failure rate for SPF, DKIM, and DMARC where event data or seed testing provides it.
• Inbox placement changes at monitored seed addresses.

Segmenting is essential. A 99.9% aggregate delivery figure can hide a serious issue affecting all password resets to one major mailbox provider. Likewise, a high bounce rate in a low-quality marketing import should not trigger the same incident response as a high deferral rate for receipts sent to existing customers.

Establish service objectives that reflect message urgency

Password resets, login verification, purchase receipts, account-security alerts, and legal notices do not have equal urgency. Define separate targets for each class. For example, a security code may require rapid acceptance and delivery monitoring, while a noncritical product notification may tolerate a longer queue delay.

Set alert thresholds around changes from your baseline rather than arbitrary absolute values alone. A jump from 0.2% to 5% 429 responses, or a tenfold increase in 421 deferrals to a major recipient domain, deserves investigation even if total volume remains modest.

Communicate incidents with precision

Technical accuracy is part of incident response. Vague statements such as “emails are delayed” can confuse users when only confirmation messages to one destination are affected. Overconfident statements such as “no emails were sent” can be equally damaging if messages were accepted and are simply delayed in retry queues.

A useful incident update format

Use a consistent structure for internal and customer-facing updates:

1. Impact: Identify the affected message type, sending interface, region, account group, or recipient destination.
2. Start time: Provide the earliest confirmed UTC time, not the time the incident was reported.
3. Observed behavior: State facts, such as elevated 503 submission responses or increased 421 deferrals to a recipient network.
4. Current scope: Explain what is known to work and what is not known yet.
5. Mitigation: Describe action in progress, such as reducing request concurrency, retrying queued messages, or correcting a DNS record.
6. Next update: Commit to a time, even if the next update is simply “still investigating.”

An example internal update:

Since 14:12 UTC, password-reset requests submitted through the REST email API have had elevated 503 responses. SMTP submissions and other message types are currently unaffected. We are preserving failed request IDs, applying idempotent retries with backoff, and monitoring the provider status channel. Next update by 14:45 UTC.

An example recipient-side update:

Since 09:30 UTC, messages to one recipient mail system have experienced increased temporary deferrals. Messages are being retried automatically, and we have not identified evidence of message loss. New sign-in codes may arrive later than usual for affected recipients.

The second example avoids blaming a third party without proof and correctly distinguishes temporary delay from loss.

Document the incident after recovery

A useful post-incident review answers more than “what broke?” It should identify why detection lagged, what signal was most valuable, which action reduced impact, and what change will prevent recurrence.

Include the timeline, customer impact, technical root cause, contributing factors, recovery actions, unresolved risks, and concrete follow-ups with owners and due dates. For email systems, also review whether retries created duplicate sends, whether webhooks were delayed or lost, whether monitoring covered all critical recipient domains, and whether support had enough message identifiers to investigate affected users.

Design for resilience before the next incident

Email is a distributed system. A resilient integration assumes that networks time out, DNS records change, recipient servers defer traffic, webhooks are delivered more than once, and provider interfaces can have temporary failures.

Application practices that reduce incident impact

• Persist an internal send record before calling the provider.
• Use idempotency keys or business-event deduplication for customer-visible messages.
• Retry only transient errors and apply exponential backoff with jitter.
• Put a maximum age on retries so stale notifications do not arrive after they are useful.
• Process webhooks idempotently because duplicate delivery is possible.
• Verify webhook signatures when your provider supports signed webhooks.
• Keep API keys and SMTP credentials in a managed secret store and test rotation procedures.
• Use a dedicated, authenticated sending subdomain where that fits your domain strategy.
• Keep DNS ownership, TTLs, and change history documented.
• Maintain seed mailboxes and send scheduled synthetic tests.
• Have a tested fallback policy for critical messages, such as in-product notification, SMS, or a secondary route where appropriate.

A secondary email provider can improve resilience, but it also increases complexity. It requires clear routing rules, consistent suppression handling, authentication for each sending path, observability across both systems, and protection against duplicate sends. Do not treat a second provider as an automatic failover without rehearsing the activation and rollback process.

Avoid unsafe workarounds

During an incident, teams sometimes disable DMARC enforcement, remove authentication records, turn off suppression protections, or dramatically increase sending rates. These changes can create a larger and longer-lived deliverability problem than the original incident.

Use reversible, scoped mitigations whenever possible. For example, reduce concurrency after a 429, pause a noncritical campaign to protect transactional traffic, or route a narrowly defined critical flow through a tested contingency. Record every change and its timestamp so recovery analysis remains possible.

When to escalate to your email provider

Escalate when your evidence indicates a submission, processing, queueing, event, or delivery problem the provider can investigate. A high-quality support request shortens time to diagnosis because it gives support engineers correlation points without requiring them to reconstruct your environment from scratch.

Provide the UTC timeframe, provider message IDs, request IDs, API endpoint or SMTP host used, response codes, full diagnostics, affected sending domain, recipient domains, approximate volume, and whether the problem reproduces with a minimal test. State whether the issue affects REST API submission, SMTP submission, delivery events, webhooks, or mailbox delivery.

Do not include production SMTP passwords, API tokens, full raw messages containing customer data, or large recipient exports unless the provider provides a secure method and specifically requests them. Redact where possible while retaining the information needed to correlate logs.

A concise escalation example:

Between 16:05 and 16:28 UTC, our application received 502 responses for 18 of 247 REST submissions. Requests used the same authenticated sending domain and succeeded before and after that interval. SMTP submission was not tested. Affected request IDs are listed in the attached secure file; no deployment or DNS change occurred during the window. Can you confirm whether the API gateway or message-submission component had elevated errors in that period?

Conclusion: diagnose the stage, then choose the response

The best way to handle email API status and incidents is to avoid treating email as one opaque service. Start with the provider status page when broad symptoms appear, but verify the path from application creation through API or SMTP submission, provider acceptance, recipient response, and final event processing.

Use HTTP status codes to distinguish malformed or unauthorized REST requests from transient service failures. Use SMTP reply codes and enhanced diagnostics to distinguish temporary recipient deferrals from permanent bounces. Validate SPF, DKIM, and DMARC with public DNS lookups, inspect message headers, and monitor delivery behavior by recipient domain and message type.

Most importantly, preserve evidence before changing configuration. A timestamped set of request IDs, SMTP replies, DNS results, and event data turns a vague report that “email is broken” into an actionable incident with a clear owner, a safe mitigation, and a faster recovery.

FAQ

Does a 202 Accepted email API response mean the email was delivered?

No. A 202 Accepted response generally means the provider accepted the request for asynchronous processing. Check subsequent events or logs to determine whether the message was queued, delivered, deferred, or bounced.

Should I retry SMTP 4xx errors?

Usually, yes. SMTP 4xx replies are temporary failures, so retry with exponential backoff and a maximum retry age. Preserve the full diagnostic text because repeated 4xx responses can indicate rate limits, recipient policy restrictions, or a sustained outage.

Should I retry SMTP 5xx errors?

Not unchanged. SMTP 5xx replies generally indicate a permanent failure for the current message or recipient. Correct the address, authentication, policy, content, or configuration problem before attempting another send.

How can I tell whether a DNS change is live?

Query public DNS directly with tools such as dig, nslookup, and MXToolbox. Compare the result with your DNS control panel and note the TTL. Different recursive resolvers may return cached values until the prior record’s TTL expires.

What should I send to provider support during an email incident?

Send UTC timestamps, request IDs or message IDs, HTTP or SMTP responses, affected sender and recipient domains, estimated volume, and recent relevant changes. Never include API keys, SMTP passwords, or unnecessary customer content in a normal support ticket.