Clarify email docs about what "successfully delivered messages" means

[ovalseven8]

Today, I read through the "Sending email" documentation and it raised a few question to me. So I am asking if perhaps you could clarify it in the docs. In case someone can help, I can then create the pull request if you want to.

My raised questions:

What does "successfully delivered messages" exactly mean?

In the docs you say the return value of send_mail() or send_mass_mail() is the number of "successfully delivered messages". But what does this mean exactly? Let's say a new user registers on my website and uses an actually not existing email address like gh37ddg3@457f3838f.com. Will send_mail() then always return 0? Or what is when the SMTP connection is successful, and the email server will just try to deliver the message several times? Will it then return 1 when the delivery to the SMTP server was successful or really only when the recipient's server got the mail? I hope you could clarify this.

Another question about fail_silently

Assuming fail_silently=False. Will then send_mail() only be able to return 1 and raise an Exception or could it also be that it returns 0?

Question to send_mass_mail()

Assuming I want to send 600 emails. Now, in the middle of the process, send_mass_mail() fails and returns that 20 emails have been delivered. How do I know which emails have been sent and which are still to be sent? In case fail_silently=False: Will the Exception also contain the number of "successfully delivered messages"?

[Carlton Gibson]

You'll want to look in ​https://github.com/django/django/tree/master/django/core/mail. Particularly in the ​SMTP backend.

More or less I think the quick answers to your questions are:

1. Success here means the SMTP server accepted the email. (It's up to the SMTP server to then try actually delivering it. This is out of scope for django.core.mail.)
2. Assuming fail_silently=False you'll either get a return from send_mail() or an exception being raised. Not both.
3. You can't know which messages were sent. You'd need to subclass the backend (or implement your own) to track that. Similar if an exception is raised: there's no mechanism to continue after an error (beyond fail_silently). If you need more complex behaviour you'll need your own backend.

In principle clarifications to the docs are always welcome. If you want look at the code, check these answers, and to roll-up them up into a PR that would be great.

Pending that I'm going to mark this as needsinfo as I'm not sure exactly what you have in mind here.

[Tim Graham]

A ​PR was provided, but I agree with the wontfix sentiment.