Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Email delivery

Django send_mail fails or hangs with an SSL error

Errorsend_mail() hangs while connecting to the SMTP server

Short 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.

  • Applies to Django 4.2, Django 5.2, Python 3.12
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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)"
  2. 2Match what you see, then jump to its fix

    1. 1The connection hangs, or fails during the handshake, right after connecting.The TLS flag does not fit the portFix
    2. 2Your settings file, an .env file or a base settings module sets both.Both EMAIL_USE_TLS and EMAIL_USE_SSL are TrueFix
    3. 3The error mentions certificate verification, and the server is an internal relay.The server certificate comes from a private CA or is self-signedFix
    4. 4The request waits a long time and then fails.No timeout is set, so a blocked connection hangs the requestFix

What does the error look like?

  • send_mail() hangs while connecting to the SMTP server
  • smtplib.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.py

2Fix

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 = True

3Verify

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

Did this fix it?

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 = False

3Verify

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

Did this fix it?

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.py

2Fix

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.pem

3Verify

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

Did this fix it?

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.py

2Fix

Set a timeout in seconds so a bad host fails quickly and shows the real error.

EMAIL_TIMEOUT = 10

3Verify

A wrong host now fails in about ten seconds with an SMTP error instead of hanging.

grep -n "EMAIL_TIMEOUT" settings.py

Confirmed by docs.djangoproject.com

Did this fix it?

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:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.