SMTP: STARTTLS handshake failed

Quick fix

Read the commands before running them. Anything that restarts a service, deletes data or changes permissions should be tried on a non-production system first.

# Test STARTTLS manually
openssl s_client -starttls smtp -connect mail.example.com:587
# Check certificate
openssl s_client -starttls smtp -connect mail.example.com:587 | openssl x509 -noout -text
# Try implicit TLS on port 465
openssl s_client -connect mail.example.com:465

How to diagnose Email errors

SMTP errors follow a strict convention: a 4xx code is temporary and will be retried, a 5xx is permanent and will not. Beyond delivery mechanics, most modern email problems are authentication problems (SPF, DKIM and DMARC alignment) which cause silent filtering into spam rather than an explicit bounce, and therefore need to be checked proactively.

If the quick fix above does not resolve it, work through these steps. They apply to this whole class of error, not just to this one message, which is usually what saves the time.

1. Read the full bounce message. The enhanced status code (for example 5.7.1) is far more specific than the three-digit code and usually names the exact policy that rejected the message.
2. Test the SMTP conversation manually with swaks --to [email protected] --server smtp.example.com --tls. It shows each command and response.
3. Verify SPF, DKIM and DMARC records with dig TXT example.com, dig TXT selector._domainkey.example.com and dig TXT _dmarc.example.com.
4. Check DMARC alignment, not just presence: the domain in the From: header must align with the SPF or DKIM domain, or DMARC fails even when both pass individually.
5. Confirm the sending IP is not on a blocklist and has valid reverse DNS. Missing PTR records cause rejection by many large providers.

Tools worth reaching for

• swaks
• dig TXT
• openssl s_client -starttls smtp
• postfix mail logs
• DMARC aggregate reports

Authoritative references

Primary documentation for this error, worth reading before applying any fix in production.

📖 datatracker.ietf.org

Related Email errors

• DKIM: Signature verification failedThe DKIM signature on the email does not match. The DNS public key record may be wrong, or…
• SMTP: 421 Too many connectionsThe mail server is rate limiting connections. Too many simultaneous connections from the same…
• SMTP: 535 Authentication failedSMTP login credentials were rejected. The password may be wrong, or the account requires an…
• SMTP: 550 5.7.26 unauthenticated email from domain not acceptedGmail and Yahoo require bulk senders to authenticate with SPF and DKIM, publish a DMARC…
• SMTP: 550 Mailbox not foundThe recipient email address does not exist on the mail server. The mailbox may have been…
• SMTP: 554 Relay access deniedThe SMTP server refuses to relay mail for the sender. The server only accepts mail for its…
• SPF: Sender not authorizedThe sending mail server's IP is not listed in the domain's SPF record. The email may be…

See all 8 Email errors →

Browse other categories

• HTTP 494xx client errors, 5xx server errors, redirects, headers and protocol problems.
• JavaScript 42npm resolution, async pitfalls, hydration, memory limits and runtime type…
• Database 41Connections, deadlocks, constraints, replication and memory limits.
• AI 35Rate limits, context windows, GPU memory and model-serving failures.
• Network 35Refused connections, timeouts, resets, MTU problems and port exhaustion.
• Python 35Imports, virtual environments, encoding, concurrency and dependency conflicts.
• Kubernetes 34CrashLoopBackOff, ImagePullBackOff, OOMKilled, RBAC, scheduling and storage.
• Docker 27Daemon connectivity, disk space, image pulls, ports and architecture mismatches.
• System 26Disk space, systemd units, file descriptors, OOM killer and scheduled jobs.
• Cloud 25IAM permissions, quotas, service limits and credential failures.
• Security 25JWT validation, CSRF, OAuth grants, SELinux, SSH host keys and CSP.
• TLS 24Untrusted authorities, expiry, hostname mismatch, chains and cipher negotiation.

Something missing or wrong?

This entry is maintained by hand. If the fix is out of date, incomplete, or you have a better one, email a correction and it will be reviewed.