Common SMTP connection errors can look deceptively similar in application logs: a timeout, a refused socket, a TLS failure, or a terse 535 response. The fastest fix is to identify which stage failed—network connection, TLS negotiation, SMTP authentication, message submission, or downstream delivery—then test that stage directly.

SMTP is a conversation, not a single request. Your application first opens a TCP connection to a mail server, optionally negotiates TLS, identifies itself with EHLO, authenticates with AUTH when required, supplies an envelope sender and recipients, and transfers message data. A failure anywhere in that sequence may be reported as an “SMTP error,” even when the root cause is a firewall rule, an expired credential, a DNS record, or an invalid recipient address.

This guide focuses on application-to-provider SMTP submission, but the same method is useful when running your own relay or diagnosing server-to-server delivery. If your provider also offers an HTTP sending endpoint, it can be useful to compare the SMTP failure with a controlled API request; the provider’s email API reference and setup guides should document the expected credentials, endpoints, and supported authentication methods.

Start by locating the failed SMTP stage

Do not begin with a generic retry or a credentials reset. First capture the complete error string, the numeric status code if one exists, the hostname and port your application used, and the timestamp in UTC. A message such as connect ETIMEDOUT, ECONNREFUSED, wrong version number, and 535 5.7.8 Authentication credentials invalid points to four very different layers.

A typical authenticated SMTP submission session resembles this:

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

The final 250 means the submission server accepted the message for processing. It does not prove that the recipient inbox accepted it, that it avoided spam filtering, or that the recipient read it. Keep submission failures separate from later bounces, suppressions, and deliverability problems.

A simple error-classification checklist

Before changing configuration, classify the error into one of these groups:

Network connection failure: the TCP session never opens. Typical errors include ETIMEDOUT, ECONNREFUSED, EHOSTUNREACH, ENOTFOUND, and getaddrinfo failures.
TLS negotiation failure: the socket opened, but encryption could not be established. Examples include certificate-name mismatches, unsupported protocol versions, wrong version number, or 454 after STARTTLS.
SMTP protocol or authentication failure: the server responded, but rejected EHLO, AUTH, MAIL FROM, or RCPT TO. Common responses include 530, 535, 550, and 554.
Provider policy, quota, or rate limiting: the provider knows who you are but temporarily declines requests, often with a 4xx reply.
Recipient-side delivery rejection: the submission provider accepted the message, then a recipient server later rejected it. The useful evidence is usually in a bounce, event webhook, or message activity log—not the initial SMTP call.

The first digit of an SMTP reply is a useful triage signal. 2xx indicates success, 4xx indicates a transient negative result that may be retried according to policy, and 5xx indicates a permanent negative result for that command or message. The human-readable text and enhanced status code, such as 5.7.8, often provide the decisive detail. SMTP reply-code categories and commonly used responses are defined in the SMTP standard. (datatracker.ietf.org)

Connection refused, timeout, and DNS lookup errors

These are the most literal connection errors: your application never reaches a working SMTP listener. No username, password, sender domain, or email content can fix a connection that does not exist.

`ECONNREFUSED` or “connection refused”

ECONNREFUSED means the destination IP responded to the TCP connection attempt with a refusal. Usually, one of the following is true:

The hostname resolves, but nothing is listening on the selected port.
You selected the wrong port for the encryption mode.
A local firewall, container network policy, proxy, or egress gateway actively rejects the connection.
The provider accepts SMTP only on a different hostname or from approved source IP addresses.
You are connecting to a web/API hostname rather than the provider’s SMTP hostname.

Test from the same environment where the application runs—not only from your laptop:

nc -vz smtp.example-provider.com 587

For a successful TCP connection, nc typically reports that the port succeeded. If it is refused, verify the configured hostname and port against your provider’s current documentation. Then test a second supported submission port only if the provider documents it; guessing ports can conceal a TLS-mode mismatch.

`ETIMEDOUT`, `ESOCKETTIMEDOUT`, or “connection timed out”

A timeout means no usable response arrived before your client gave up. It often points to an egress block or network path problem rather than an SMTP server issue. Some cloud platforms and corporate networks restrict outbound SMTP traffic, particularly port 25, to reduce abuse.

Check these possibilities in order:

Outbound traffic is blocked by a cloud-provider policy, security group, firewall, network ACL, or hosting control panel.
A Kubernetes NetworkPolicy, service mesh, NAT gateway, or corporate proxy prevents the connection.
The SMTP hostname resolves to an unreachable IPv6 address while your runtime has incomplete IPv6 connectivity.
The provider has an incident or is blocking your source IP.
Your timeout setting is unrealistically short during cold starts or congested network conditions.

Run a verbose TLS test from the application host or a temporary diagnostic container:

openssl s_client -starttls smtp \
  -connect smtp.example-provider.com:587 \
  -servername smtp.example-provider.com \
  -crlf

If openssl itself hangs before showing a certificate or SMTP banner, focus on routing and firewall rules. If it connects but your application times out, compare the application’s DNS behavior, proxy configuration, IP family preference, and timeout settings with the shell environment.

`ENOTFOUND`, `getaddrinfo ENOTFOUND`, or “host not found”

These indicate a DNS resolution problem for the SMTP server hostname. This is distinct from MX, SPF, DKIM, and DMARC records for your sending domain. If your code cannot resolve smtp.example-provider.com, it cannot begin an SMTP session regardless of whether your own domain’s email authentication records are perfect.

Use these commands:

dig +short smtp.example-provider.com
nslookup smtp.example-provider.com

Common causes include a misspelled hostname, an environment variable with whitespace or a copied URL scheme such as https://smtp.example-provider.com, a private DNS resolver that cannot resolve public records, and a stale deployment secret. SMTP host settings should contain a hostname only—not smtp://, https://, a path, or a port appended to the name unless your library explicitly expects a URL.

Why port 25 behaves differently

Port 25 is traditionally used for SMTP relay between mail servers. Authenticated client submission is commonly configured on a separate submission service and port, often using STARTTLS or implicit TLS as documented by the service operator. RFC 6409 defines message submission and registers port 587 for that purpose; its guidance distinguishes message submission from relay. (datatracker.ietf.org)

That distinction has practical consequences. A production app that works from a home network may time out after deployment because the host restricts outbound port 25. Do not work around that by disabling encryption or using an arbitrary open relay. Use the authenticated submission hostname, port, and TLS mode your provider specifies.

TLS and STARTTLS configuration errors

SMTP supports two common encrypted connection patterns. With STARTTLS, the client opens a plain SMTP connection, sends EHLO, sees STARTTLS in the server capabilities, requests the upgrade, and then performs a TLS handshake. With implicit TLS, TLS begins immediately when the TCP socket opens; sending unencrypted SMTP commands first will fail.

The configuration must match both the port and the server’s expected mode. A common failure is selecting “SSL/TLS” in a library while connecting to a STARTTLS submission port, or configuring STARTTLS while connecting to an implicit-TLS port.

“wrong version number” and “SSL routines” errors

Errors such as wrong version number, ssl3_get_record:wrong version number, or unexpected plaintext responses commonly mean your client tried to start a TLS handshake against a server that expected plaintext SMTP commands first.

For example, this is incorrect for a typical STARTTLS endpoint:

Open TLS socket immediately -> connect to STARTTLS port

Instead, configure the client to connect normally and request STARTTLS after EHLO. Conversely, an implicit-TLS service expects a TLS handshake immediately, so a client configured for plain SMTP plus STARTTLS will see confusing protocol errors or a dropped connection.

Do not infer the mode solely from the port number. Providers can make different choices, and application libraries use inconsistent setting names such as secure, ssl, tls, starttls, requireTLS, or useTls. Read the library documentation and the provider’s documented SMTP settings together.

`STARTTLS` is missing or rejected

If the server capability response after EHLO does not list STARTTLS, your application cannot safely require a STARTTLS upgrade on that connection. A server may also answer the command with 454 TLS not available due to temporary reason. RFC 3207 specifies the STARTTLS extension and notes that a 454 response leaves the client to decide whether to continue based on local policy. For authenticated submission, treating a TLS failure as fatal is generally the prudent policy because credentials should not fall back to plaintext. (datatracker.ietf.org)

Use a direct test to inspect the server’s capabilities:

openssl s_client -starttls smtp \
  -connect smtp.example-provider.com:587 \
  -servername smtp.example-provider.com \
  -crlf -quiet

After the handshake, type:

EHLO diagnostic.example.com

Inspect the response for supported authentication methods and other capabilities. Do not paste live credentials into a shared terminal transcript or support ticket.

Certificate verification failures

A certificate failure is not something to bypass with rejectUnauthorized: false, verify=False, or an equivalent “trust all certificates” switch. Disabling verification exposes SMTP credentials and message content to interception, and it can hide an incorrect hostname that will later break again.

Common certificate errors include:

hostname mismatch or ERR_TLS_CERT_ALTNAME_INVALID: the hostname in your configuration is not covered by the server certificate.
unable to verify the first certificate: the runtime lacks an appropriate CA bundle, an intermediate certificate is missing, or traffic is being intercepted by a corporate TLS inspection device.
certificate has expired: either the server certificate is expired or the system clock is inaccurate.
unsupported protocol or handshake failure: the client and server cannot agree on a TLS version, cipher suite, or signature algorithm.

Check the certificate name, chain, dates, and negotiated TLS details:

openssl s_client -starttls smtp \
  -connect smtp.example-provider.com:587 \
  -servername smtp.example-provider.com \
  -showcerts

The -servername option matters because it sends Server Name Indication (SNI). Without it, a multi-tenant SMTP endpoint may present a default certificate that does not match the intended hostname.

TLS errors after a runtime upgrade

If SMTP suddenly fails after a Node.js, Java, Python, OpenSSL, base-image, or operating-system upgrade, compare the TLS stack before and after deployment. New runtimes may reject obsolete protocol versions or weak cipher suites that an older runtime tolerated. That is usually a security improvement, but it requires either a provider-side update, a supported client configuration change, or a current CA bundle.

Also verify the server clock. A clock that is far ahead or behind can make a currently valid certificate appear expired or not yet valid. Time drift is especially easy to miss in custom VM images, isolated networks, and container hosts with broken time synchronization.

SMTP authentication failures: `530`, `534`, and `535`

Authentication occurs after the connection and, in a secure configuration, after TLS. An authentication error proves that the SMTP server was reached and responded. It does not prove that the application sent the credentials you think it sent.

`535 5.7.8 Authentication credentials invalid`

535 5.7.8 is the classic SMTP authentication failure. RFC 4954 defines it as a reply indicating invalid or insufficient authentication credentials. (datatracker.ietf.org)

The obvious cause is an incorrect username or password, but the more common production causes are subtler:

The deployment environment contains an old secret after a credential rotation.
The app reads a different variable name than the one set in the hosting platform.
A password contains a newline, quote, trailing space, or shell-escaped character introduced during secret entry.
The provider requires an API key or generated SMTP credential rather than a normal dashboard login password.
The username is a required literal value, account identifier, or full email address rather than the address developers assumed.
The account, project, IP, or credential was disabled, revoked, restricted, or not authorized for SMTP.
The library selected an unsupported SASL mechanism.

Never log passwords, tokens, or the base64 payload of AUTH PLAIN or AUTH LOGIN. Log only safe diagnostics: host, port, TLS mode, configured username length, credential fingerprint or secret version, server code, enhanced code, and provider request/message identifier where available.

`530 5.7.0 Must issue a STARTTLS command first`

A 530 response often means the server refuses authentication or message submission until the connection is encrypted. Enable STARTTLS on the documented submission endpoint and ensure the client sends EHLO before attempting STARTTLS or AUTH.

Do not solve this by turning off encryption requirements. The correct sequence is:

Connect -> EHLO -> STARTTLS -> TLS handshake -> EHLO again -> AUTH

The second EHLO is important. RFC 3207 requires the client to discard knowledge obtained from the pre-TLS server capabilities and issue EHLO again after TLS is established. (datatracker.ietf.org)

`504`, `534`, and unsupported authentication mechanisms

504 can indicate that the requested authentication mechanism is unsupported or that a required encryption layer is absent. 534 is often used by providers for an additional authentication requirement or policy condition, but its precise text is provider-specific.

Inspect the EHLO response. A server may advertise something like:

250-AUTH PLAIN LOGIN

Your client must choose a mechanism the server advertises and that your provider supports for the credential type. If the provider supports token-based SMTP credentials over AUTH PLAIN but your library attempts a legacy or custom method, the exchange will fail even with the correct secret.

Treat an SMTP password as an application secret with a lifecycle: create it narrowly, store it in a secret manager, deploy it without transformation, rotate it deliberately, and revoke it when a service or employee no longer needs it. Avoid sharing one credential across unrelated environments; separate development, staging, and production credentials make incident containment and auditing much easier.

Relay denied and sender authorization errors

A successful authentication step does not automatically authorize every sender address or recipient. SMTP has an envelope sender—the address in MAIL FROM—and one or more visible headers, including From, To, and Reply-To. Providers and receiving systems can enforce rules on either layer.

“Relay access denied” or `554 5.7.1`

A relay denial means the server will not accept the requested delivery on your behalf. It can occur because you did not authenticate, authenticated unsuccessfully, used the wrong SMTP hostname, connected to an inbound server rather than a submission server, or attempted a recipient/sender combination that the server policy forbids.

Check the exact command that failed:

Rejection immediately after RCPT TO commonly indicates the server will not relay to that recipient under the current session or authorization.
Rejection after MAIL FROM can indicate an unauthorized envelope sender.
Rejection after DATA may indicate message policy, rate limits, content checks, or a sender-domain restriction.

A provider’s relay is not an open relay. It generally expects authenticated, authorized submission. Do not attempt to “fix” a relay denial by pointing your app at a random mail exchanger found in a recipient domain’s MX records. MX records identify inbound mail servers for a domain; they are not authenticated SMTP submission endpoints for your application.

“Sender address not verified” and `550 5.7.1`

Many email services require you to verify a domain or, in some cases, an individual sender before using it in From or envelope-sender fields. If a message is rejected because the sender is unauthorized, verify all of these independently:

The exact domain in the visible From address is authorized.
The envelope sender is permitted by the account or sending identity.
Required domain-authentication records are published and verified.
The configured sender did not accidentally use a typo, a subdomain, or a development domain.
The sending account or project has access to that domain.

alerts@example.com and alerts@notify.example.com are different domains for configuration purposes. A root-domain verification does not always cover every subdomain, and a subdomain configuration may require its own DNS records.

DNS issues that affect SMTP sending and delivery

DNS normally does not prevent your app from opening a session to an external SMTP provider unless the provider hostname itself cannot be resolved. However, DNS is essential to sender authorization, identity, reputation, and recipient acceptance. A message may submit successfully and still fail downstream because SPF, DKIM, DMARC, reverse DNS, or tracking-domain records are missing or malformed.

SPF: authorize the sending infrastructure

SPF is published as a TXT record at the sending domain. A simplified example is:

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

The exact include: domain must come from your email provider’s documentation. Do not substitute a fictional hostname, copy another provider’s include, or publish multiple independent SPF TXT records. SPF evaluation expects one SPF policy record; multiple competing records can produce a PermError.

If your application sends through more than one authorized system, combine the authorized mechanisms into one record, for example:

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

Use -all only when you are confident every legitimate sending source has been included. The principle is simple: SPF checks the envelope-sender domain, not necessarily the friendly address a recipient sees in the From header.

DKIM: publish the exact selector record

DKIM signs a message using a selector and a domain. The provider gives you a selector-specific DNS hostname and public-key value. A generic shape looks like this:

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

The selector, record type, and value must exactly match the provider’s instructions. Frequent errors include publishing the record at _domainkey.example.com without the selector, adding the domain twice in a DNS control panel that appends the zone automatically, changing a required CNAME record to TXT, or splitting/quoting the key incorrectly.

DNS UIs differ: some expect the relative host selector1._domainkey, while others expect the full hostname selector1._domainkey.example.com. Verify the resulting public record with dig, not only the value displayed in the dashboard:

dig +short TXT selector1._domainkey.example.com

DMARC: connect authentication to the visible From domain

DMARC is published at _dmarc for the domain and establishes a policy based on aligned SPF and/or DKIM authentication. A conservative monitoring record can look like this:

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

A stricter production policy might later be:

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

Do not jump to p=reject merely because a record parses. First confirm every legitimate sender—including support tools, CRM systems, invoice platforms, and transactional providers—can pass aligned authentication. DMARC evaluates alignment with the domain visible in the From header, which is why a technically valid SPF result alone may not satisfy DMARC. The current DMARC standard is specified in RFC 7489’s successor documents, while the record form remains recognizable as a _dmarc TXT policy beginning with v=DMARC1. (dmarctrust.com)

MX and reverse DNS are not submission settings

An MX record tells other mail servers where to deliver mail to your domain. A typical MX record might look like:

example.com. IN MX 10 mail.example.com.

It does not tell your application where to send outbound mail. Your application should use the SMTP submission hostname supplied by its provider.

Reverse DNS (PTR) maps an outbound sending IP address back to a hostname. If you use a managed transactional provider, the provider generally controls the sending IP and its PTR record. If you operate your own relay or dedicated IP, a missing or incoherent PTR can contribute to recipient distrust and delivery failures. The forward hostname and reverse mapping should be intentionally configured and consistent where your mail architecture requires it.

Test DNS from outside your DNS dashboard

Use more than one resolver when troubleshooting propagation or malformed records:

dig +short TXT example.com @1.1.1.1
dig +short TXT _dmarc.example.com @8.8.8.8
dig +short MX example.com

MXToolbox can provide a convenient cross-check for MX, SPF, DKIM, DMARC, and blacklist-related diagnostics. Use it as a diagnostic aid, but trust the authoritative DNS result and the exact record requirements from the service that will consume the record.

Remember that DNS TTLs are caching instructions, not a guaranteed universal update timer. A record can be correct in your authoritative zone yet remain absent from a resolver that still has an earlier answer cached.

Recipient, message, and policy rejections

Not every SMTP 5xx response is a connection problem. Once your provider accepts a message, recipient systems may reject it for reasons unrelated to your network configuration.

`550 5.1.1` and invalid recipients

550 5.1.1 commonly means the recipient mailbox does not exist, though the exact text and enhanced status code matter. This is generally a permanent failure: retrying the exact same address will not create a mailbox.

Handle it as a data-quality event. Stop repeated sends to the address, record the bounce reason, and let the user correct the address if your product supports it. For signup, invite, or checkout flows, validate obvious formatting problems before sending, but do not rely on regex validation alone to establish that a mailbox can receive mail.

For pre-send checks, an email address verification tool can help identify malformed, risky, or non-deliverable addresses. Verification results should inform your workflow rather than replace bounce processing, consent controls, and suppression handling.

`552`, `552 5.2.2`, and mailbox limits

552 and enhanced 5.2.x responses can indicate that a mailbox is full, a message exceeds a size limit, or another storage-related condition applies. Treat the server text as authoritative because implementations vary.

If your messages include attachments, calculate the encoded size—not only the raw file size. Base64 encoding expands binary content, and MIME boundaries, headers, inline images, and HTML all add overhead. For large assets, use a secure download link rather than attaching the file when possible.

`554`, `5.7.1`, and content or reputation policy blocks

554 and 5.7.1 are broad policy-related rejections. They may result from spam-like content, an unauthenticated sender, a new or poor IP/domain reputation, malformed message headers, a blocked URL, suspicious attachment types, or a recipient organization’s local policy.

The right response is evidence-driven:

Preserve the full server response and any message identifier.
Confirm SPF, DKIM, and DMARC alignment.
Check that From, Reply-To, Return-Path, and visible links are coherent with your domain.
Remove deceptive subject lines, broken HTML, malformed MIME boundaries, and unnecessary URL shorteners.
Check unsubscribe handling and consent practices for marketing mail.
Compare a failing message with a known-good message, including headers and content structure.

For a controlled inbox-placement and content diagnostic, send a representative test to mail-tester.com and review its report. Do not send sensitive production data there; use a redacted test message with the same sender setup, authentication, template structure, and links where practical.

Rate limits, quotas, and temporary `4xx` errors

A 4xx SMTP reply means the command was not accepted at that moment, but the condition may be temporary. This does not mean “retry immediately in a tight loop.” Aggressive retries can extend a throttle, overload your queue, create duplicate messages, and make an incident harder to diagnose.

Common temporary replies

The following responses are frequently seen, though providers may use different wording:

421: service not available, sometimes accompanied by a connection closure or rate-limit message.
450: mailbox or recipient unavailable temporarily.
451: local processing error or temporary server condition.
452: insufficient system storage, quota, or a temporary sending limit.
454: temporary authentication, security, TLS, or policy issue depending on context.

SMTP standards describe 4yz replies as transient negative completion responses: the command failed, but retrying later may succeed. (datatracker.ietf.org)

Build a retry policy that does not amplify failure

A safe retry strategy should be queue-based, bounded, and idempotent. For transactional messages, preserve a stable internal message ID so a retry can be recognized and duplicate sends can be investigated.

A practical baseline is:

Retry only errors you have classified as transient, such as selected network failures and SMTP 4xx responses.
Use exponential backoff with jitter—for example, a randomized delay around 1 minute, 5 minutes, 20 minutes, 1 hour, then longer intervals.
Cap the number of attempts and total retry window according to the message’s business value and expiry.
Respect any provider-specific Retry-After, rate-limit, or quota guidance when available.
Do not retry permanent authentication failures, invalid recipients, unauthorized senders, or clear policy rejections until configuration or content changes.
Alert on sustained failure rates by error class, provider hostname, environment, and sender domain.

A transient status can still reveal a permanent operational issue. For example, repeated 421 replies may mean your account has reached a rate threshold, your IP is blocked, or all workers are reconnecting at once after a deployment. Backoff buys time; it does not replace diagnosis.

A repeatable diagnostic workflow

When email is business-critical, troubleshooting should be reproducible rather than dependent on a single developer’s laptop. The following workflow narrows the problem quickly while minimizing risk to credentials and customers.

1. Capture a safe, complete error record

Record the UTC timestamp, application release/version, region, hostname, port, TLS mode, DNS result, socket error or SMTP response, enhanced status code, and a correlation ID. Redact recipients if needed and never include SMTP passwords, raw authorization strings, or complete message bodies in general logs.

2. Test basic DNS and TCP connectivity from production

Run dig and nc or equivalent from the same network path as the service. A test from a developer workstation cannot prove that a serverless runtime, container cluster, VPN-connected VM, or private subnet has outbound access.

3. Inspect the TLS handshake

Use openssl s_client with the correct mode and SNI hostname. Confirm that the certificate is trusted, the hostname matches, the protocol is current, and the server presents expected SMTP capabilities after the handshake.

4. Verify credentials without exposing them

Confirm the secret version, source, and deployment timing. Rotate or recreate a credential only after checking whether the app is actually loading the intended secret; otherwise, you may create more confusion while the stale configuration remains deployed.

5. Send a minimal controlled message

Use one verified sender and a mailbox you control. Keep the subject, HTML, links, and attachments minimal. This isolates transport and authorization from template rendering, attachment size, personalization, and recipient-specific policy.

6. Add complexity one variable at a time

Test the production sender domain, then the real template, then attachments, then representative recipients. When a failure appears, the last changed variable is a valuable clue.

7. Separate acceptance from delivery

If the SMTP server returned 250 after DATA, inspect provider events, bounce notifications, recipient headers, and DMARC reports for the next stage. A successful submission is a handoff, not an inbox guarantee.

Application configuration mistakes that resemble server failures

Many “SMTP outages” are configuration parsing bugs. These deserve explicit checks because they can survive code review and only fail in a specific deployment environment.

Boolean and port parsing errors

Environment variables are strings. In some languages, the non-empty string "false" evaluates as truthy, accidentally enabling implicit TLS. Parse values intentionally:

SMTP_PORT=587
SMTP_SECURE=false

Your code should convert SMTP_PORT to a number and compare SMTP_SECURE explicitly, rather than relying on generic truthiness. Log the final effective configuration excluding secrets.

Invisible whitespace and copied credentials

A credential copied from a dashboard or password manager can acquire a newline. A hostname can acquire https://, a trailing slash, or a non-breaking space. Print safe representations during diagnosis, such as the hostname in brackets, port, credential length, and a hash prefix of the secret—not the secret itself.

Mixing sandbox and production settings

A sandbox account may accept only authorized recipients, use different credentials, or restrict sending until verification is complete. Production and staging often have different sender identities, domains, quotas, and IP allowlists. Make the environment explicit in configuration and monitoring so a staging credential cannot silently be used in production.

Reusing one SMTP client across incompatible workloads

Connection pooling can improve throughput, but a pool that is too large can exhaust provider limits or create a burst of simultaneous authentication attempts. A pool that is too small can make queued messages look like timeouts. Monitor connection creation, authentication failures, queue depth, send latency, and retry volume—not only total email count.

When to use SMTP and when to compare the HTTP API

SMTP remains useful because it is widely supported by application frameworks, legacy software, devices, and mail libraries. It is also a conversational protocol, which makes direct debugging with standard tools straightforward.

An HTTP email API can be easier to observe in modern services because it typically uses structured JSON responses, explicit request IDs, and first-class support for templates, attachments, tags, idempotency, and webhooks. That does not make SMTP obsolete; it changes the troubleshooting surface from TLS/SASL/socket configuration to HTTP authentication, request validation, and API rate limits.

If your provider supports both, use the same verified sending domain and a controlled recipient to compare paths during an incident. If an API request succeeds while SMTP fails, investigate SMTP hostname, port, TLS mode, and SMTP credentials. If both fail with sender-domain or account-policy errors, the issue is likely authorization, account state, DNS verification, or sending policy rather than the transport protocol.

Prevent common SMTP connection errors before deployment

The best SMTP incident is the one caught in a pre-production test. Build a lightweight mail health check that validates only what is safe and necessary: DNS resolution, TCP reachability, certificate validity, and a controlled send to a monitored mailbox.

Use this operational checklist:

Store SMTP credentials in a managed secret store and rotate them with a documented process.
Use a provider-documented submission hostname, port, and encryption mode.
Require certificate verification in production.
Configure SPF, DKIM, and DMARC before scaling sends from a new domain.
Keep a verified test recipient and test sender for synthetic checks.
Alert on connection failures, 535 spikes, 4xx retry growth, and bounce-rate changes.
Preserve complete server responses and correlation IDs while redacting secrets.
Use backoff and bounded retries for transient failures.
Suppress known hard bounces and invalid recipients.
Test after DNS, secret, runtime, firewall, or infrastructure changes.

Email systems fail at boundaries: between an app and a network, a socket and TLS, credentials and account policy, a sender domain and DNS, or a provider and recipient mailbox. Instrumenting those boundaries makes errors far less mysterious.

FAQ

What is the most common SMTP connection error?

The most common category depends on where the app runs. In cloud deployments, timeouts and blocked outbound SMTP ports are frequent. In otherwise connected applications, 535 5.7.8 authentication failures and TLS-mode mismatches are especially common. Capture the full error and determine whether TCP, TLS, AUTH, or message submission failed before changing settings.

Does `250 OK` mean an email reached the inbox?

No. A 250 response after message data generally means the SMTP server accepted the message for processing. It may still be deferred, bounced, quarantined, filtered, or delivered to spam by a downstream recipient system. Check delivery events, bounces, and recipient-side headers for the final outcome.

Should I retry SMTP error `535`?

Not automatically. 535 5.7.8 means authentication credentials were rejected, so repeating the same request with the same configuration is unlikely to help and can trigger additional security controls. Verify the credential type, username format, secret deployment, TLS requirement, account status, and supported AUTH mechanisms first.

Why does SMTP work locally but time out in production?

Your production environment may have different DNS, IPv6, firewalls, egress rules, security groups, proxies, NAT gateways, or cloud-provider port restrictions. Run dig, nc, and openssl s_client from the production network path to test the real route.

Can SPF, DKIM, or DMARC cause an SMTP connection timeout?

Usually no. Those DNS records affect sender authentication and downstream delivery, not the initial TCP connection from your app to an SMTP provider. They can, however, cause recipient-side rejections or poor inbox placement after the provider accepts the message.

Common SMTP Connection Errors: Causes, Tests, and Fixes