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