id	summary	reporter	owner	description	type	status	component	version	severity	resolution	keywords	cc	stage	has_patch	needs_docs	needs_tests	needs_better_patch	easy	ui_ux
36907	Docs for email `fail_silently` are incorrect and inconsistent	Mike Edmunds	Ahmed Asar	"Several django.core.mail APIs support a `fail_silently` boolean argument. This is documented three places in the email topic (quoting from https://docs.djangoproject.com/en/6.0/topics/email/):

1. [https://docs.djangoproject.com/en/6.0/topics/email/#send-mail:~:text=fail_silently%3A%20A%20boolean.%20When%20it%E2%80%99s%20False%2C%20send_mail()%20will%20raise%20an%20smtplib.SMTPException%20if%20an%20error%20occurs.%20See%20the%20smtplib%20docs%20for%20a%20list%20of%20possible%20exceptions%2C%20all%20of%20which%20are%20subclasses%20of%20SMTPException. send_mail()]: ""`fail_silently`: A boolean. When it’s `False`, `send_mail()` will raise an `smtplib.SMTPException` if an error occurs. See the `smtplib` docs for a list of possible exceptions, all of which are subclasses of `SMTPException`.""
2. [https://docs.djangoproject.com/en/6.0/topics/email/#django.core.mail.EmailMessage.send:~:text=If%20the%20keyword%20argument%20fail_silently%20is%20True%2C%20exceptions%20raised%20while%20sending%20the%20message%20will%20be%20quashed. EmailMessage.send()]: ""If the keyword argument `fail_silently` is True, exceptions raised while sending the message will be quashed.""
3. [https://docs.djangoproject.com/en/6.0/topics/email/#django.core.mail.get_connection:~:text=The%20keyword%2Donly%20fail_silently%20argument%20controls%20how%20the%20backend%20should%20handle%20errors.%20If%20fail_silently%20is%20True%2C%20exceptions%20during%20the%20email%20sending%20process%20will%20be%20silently%20ignored. get_connection()]: ""If `fail_silently` is True, exceptions during the email sending process will be silently ignored.""

The claims about `SMTPException` are accurate only when using an smtplib-based EmailBackend. And even then not 100% true: Django's default SMTP backend can also raise various `ssl.SSLError` and `OSError` exceptions. Third-party backends might raise just about anything—e.g., a requests `HTTPError` or boto3 `ClientError`. (The `SMTPException` language is likely left over from before Django supported pluggable email backends and secure SMTP connections.)

The other two sentences are mostly accurate, but should probably clarify that only ""some"" errors are silently ignored. Callers must not assume they can avoid all error handling with `fail_silently=True`.

The intent of `fail_silently` seems to be suppressing ""expected errors"" that are common when sending mail, such as transient network problems. One use case is for sending email as an error reporting mechanism, like in Django's AdminEmailHandler.

Each EmailBackend implementation has its own logic for which errors should fail silently and which remain loud. For example, Django's SMTP EmailBackend will raise `ImproperlyConfigured` for settings problems or `ValueError` for message serialization problems, even with `fail_silently=True`.

Suggest updating all three places to use some context-appropriate version of: ""If `fail_silently` is True, some exceptions during the email sending process will be silently ignored."" And remove references to specific errors in !#1. (And perhaps include a longer explanation of ""some exceptions"" in !#2?)

If we want to document what specific exceptions might be raised during sending, that should be moved to documentation for each individual email backend. (I don't think it's necessary.)"	Cleanup/optimization	closed	Documentation	6.0	Normal	wontfix	email docs fail_silently	Ahmed Asar	Someday/Maybe	0	0	0	0	0	0