Django send_mail fails or hangs with an SSL error
send_mail() hangs while connecting to the SMTP serverShort answer
Django has two secure modes that must not be mixed: EMAIL_USE_TLS for explicit TLS (STARTTLS, usually port 587) and EMAIL_USE_SSL for implicit TLS (usually port 465). Set only one to True and pair it with the right port. A private CA must go into the system CA bundle, not EMAIL_SSL_CERTFILE.
Fix it fast
1Find out which cause you have
Print the email settings the running project really uses, then compare the port with the TLS flag.
python manage.py shell -c "from django.conf import settings as s; print(s.EMAIL_HOST, s.EMAIL_PORT, s.EMAIL_USE_TLS, s.EMAIL_USE_SSL, s.EMAIL_TIMEOUT)"2Match what you see, then jump to its fix
- 1
The connection hangs, or fails during the handshake, right after connecting.The TLS flag does not fit the portFix - 2
Your settings file, an .env file or a base settings module sets both.Both EMAIL_USE_TLS and EMAIL_USE_SSL are TrueFix - 3
The error mentions certificate verification, and the server is an internal relay.The server certificate comes from a private CA or is self-signedFix - 4
The request waits a long time and then fails.No timeout is set, so a blocked connection hangs the requestFix
- 1
What does the error look like?
send_mail() hangs while connecting to the SMTP serversmtplib.SMTPException raised from send_mail()
Cause 1 of 4
The TLS flag does not fit the port
1Check
EMAIL_USE_TLS is for explicit TLS, generally on port 587. EMAIL_USE_SSL is for implicit TLS, generally on port 465. Django warns that connections can hang when the flag does not suit the server, and points to the other setting.
grep -n "EMAIL_" settings.py2Fix
Use the flag that matches the port your provider gave you.
# explicit TLS (STARTTLS)
EMAIL_PORT = 587
EMAIL_USE_TLS = True
EMAIL_USE_SSL = False
# or implicit TLS
# EMAIL_PORT = 465
# EMAIL_USE_TLS = False
# EMAIL_USE_SSL = True3Verify
Send one message from the shell.
python manage.py shell -c "from django.core.mail import send_mail; print(send_mail('test', 'body', None, ['you@example.com']))"Confirmed by docs.djangoproject.com
Cause 2 of 4
Both EMAIL_USE_TLS and EMAIL_USE_SSL are True
1Check
Django says the two settings are mutually exclusive, so only one may be True. Settings files that import from each other often leave both on.
grep -rn "EMAIL_USE_" --include=*.py --include=.env* .2Fix
Turn one off, as in the pair above. Search every settings module the project loads.
EMAIL_USE_TLS = True
EMAIL_USE_SSL = False3Verify
The settings print shows one True and one False.
python manage.py shell -c "from django.conf import settings as s; print(s.EMAIL_USE_TLS, s.EMAIL_USE_SSL)"Confirmed by docs.djangoproject.com
Cause 3 of 4
The server certificate comes from a private CA or is self-signed
1Check
Django documents that EMAIL_SSL_CERTFILE is for client authentication and must not be used for a self-signed server certificate or a private CA. Setting it does not turn on any certificate checking.
grep -n "EMAIL_SSL" settings.py2Fix
Install the server certificate or the private CA root into the system CA bundle, or point OpenSSL at a custom bundle with SSL_CERT_FILE or SSL_CERT_DIR in the environment Django runs in.
export SSL_CERT_FILE=/etc/ssl/private-ca-bundle.pem3Verify
Restart the app process and send a test mail.
python manage.py shell -c "from django.core.mail import send_mail; print(send_mail('test', 'body', None, ['you@example.com']))"Confirmed by docs.djangoproject.com
Cause 4 of 4
No timeout is set, so a blocked connection hangs the request
1Check
EMAIL_TIMEOUT defaults to None, and the connect attempt is a blocking operation. The SMTP backend then uses the socket default, which is no timeout.
grep -n "EMAIL_TIMEOUT" settings.py2Fix
Set a timeout in seconds so a bad host fails quickly and shows the real error.
EMAIL_TIMEOUT = 103Verify
A wrong host now fails in about ten seconds with an SMTP error instead of hanging.
grep -n "EMAIL_TIMEOUT" settings.pyConfirmed by docs.djangoproject.com
How do I stop it coming back?
- Keep the port, EMAIL_USE_TLS and EMAIL_USE_SSL together in one settings block.
- Set EMAIL_TIMEOUT in every environment.
- Test email with the console backend in development and with one real send before each release.
- Catch smtplib.SMTPException around sends and log it, instead of fail_silently=True.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
- stegnor.comMy company site: 804 pages from a Python and Jinja generator, with 15 free browser tools.
- MenuloA restaurant discovery platform in Germany, kept current by a Python ingestion pipeline.
- ShopGoAn e-commerce aggregator with a Python scraping engine behind its catalog, past 10K Google Play downloads.
Related fixes
Dovecot refuses to start: Can't load SSL certificate, no valid PEM certificate
doveconf: Error: ssl enabled, but ssl_cert not set
Dovecot reads the ssl_cert setting as the file's contents, not a path, so in 2.3 the value must start with a less-than sign.
3 causes, each with a fixGmail SMTP blocks you with 454 4.7.0 Too many login attempts
SMTP Error: 454 4.7.0 Too many login attempts
454 4.7.0 is a temporary block.
2 causes, each with a fixGmail rejects your mail with 530 5.5.1 Authentication Required
530 5.5.1 Authentication Required
Gmail refuses to accept a message from a connection that has not signed in.
3 causes, each with a fixGmail SMTP login fails with 535 or 534 5.7.14
534-5.7.14 Please log in via your web browser and then try again.
Gmail turned your sign-in down.
3 causes, each with a fixPython IMAP OAuth login to a shared mailbox in Microsoft 365 fails
imaplib.IMAP4.error: AUTHENTICATE failed.
Exchange Online accepts an OAuth token for IMAP only if the SASL user name is right and the token's identity has access to that mailbox.
4 causes, each with a fixJakarta Mail throws MessagingException: Could not convert socket to TLS
javax.mail.MessagingException: Could not convert socket to TLS
The server accepted STARTTLS, but the TLS handshake that followed failed on your side.
3 causes, each with a fix