Docs for email `fail_silently` are incorrect and inconsistent

[Mike Edmunds]

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. ​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. ​EmailMessage.send(): "If the keyword argument fail_silently is True, exceptions raised while sending the message will be quashed."
3. ​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.)

[Ahmed Asar]

Hi Mike,
if the mentor approves this ticket, I’d like to work on it. Is that okay?

[Mike Edmunds]

Ahmed Asar yes. Please ​claim the ticket to indicate you plan to work on it. (You can do this even before the ticket has been approved. Just please don't assign yourself if a ticket already has someone listed in "Owned by".)

[Ahmed Asar]

Thanks Mike! I’ve claimed the ticket and will work on it.

[Natalia Bidart]

Thank you Mike! Flawless ticket report, as usual. Appreciated!

[Ahmed Asar]

PR: ​https://github.com/django/django/pull/20692

[Mike Edmunds]

I'm un-accepting this ticket temporarily. From some discussion elsewhere, we may want to fix fail_silently's behavior in the code rather than just the docs. (Once that discussion is resolved, I'll either return the ticket to "accepted" or close it "wontfix.")

[Mike Edmunds]

Forum discussion: ​https://forum.djangoproject.com/t/changing-how-django-core-mail-handles-fail-silently/44278

[Ahmed Asar]

Thanks Mike