[Django] #35864: EmailMessage.connection option ignored when using send_messages()

[Django]

#35864: EmailMessage.connection option ignored when using send_messages()
------------------------------+-----------------------------------------
Reporter: Mike Edmunds | Type: Uncategorized
Status: new | Component: Core (Mail)
Version: 5.1 | Severity: Normal
Keywords: | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
------------------------------+-----------------------------------------
The EmailMessage [https://docs.djangoproject.com/en/5.1/topics/email
/#emailmessage-
objects:~:text=sending%20the%20email.-,connection,-%3A%20An%20email%20backend
connection] option is ignored when using send_messages() to
[https://docs.djangoproject.com/en/5.1/topics/email/#topics-sending-
multiple-emails send multiple messages] as suggested in the docs.

Here's some code that ''won't'' in fact use special handling for EU users
as the author expects:

{{{#!python
from django.core import mail

def get_notification_emails():
notification_emails = []
for user in get_users_needing_notification():
email = mail.EmailMultiAlternatives(to=[user.email], ...)
# Override the ESP for users in the EU; otherwise the default is
fine.
if user.profile.must_use_eu_data_processor():
email.connection = mail.get_connection(hostname="smtp-
eu.example.net")
notification_emails.append(email)
return notification_emails

def send_periodic_notification_emails():
messages = get_notification_emails()
# We replaced this loop with send_messages() to optimize sending.
# https://docs.djangoproject.com/en/5.1/topics/email/#sending-
multiple-emails
# for message in messages:
# message.send()
connection = mail.get_connection()
connection.send_messages(messages)
}}}

(You ''probably'' wouldn't make this mistake writing that code all at the
same time, but you might stumble into it if those functions were in
different files and the send_messages() optimization got added later.)

If we were designing the EmailMessage API from scratch, a clearer design
would probably handle `connection` as an EmailMessage.send() parameter,
rather than an EmailMessage property. I don't think it's worth the effort
to try to change that now. (But there's an opportunity to avoid similar
confusion when we introduce `provider` as the successor to `connection` in
#35514.)

Suggested fix: in the EmailMessage.connection docs, note that: "This
option is ignored when using `send_messages()`." And maybe in the
send_messages() section note that it "overrides any `connection` option on
individual messages."

We could also log a warning in smtp.EmailBackend.send_messages(), if any
of the messages has a connection that is not self. (But each EmailBackend
implements its own send_messages(), so this wouldn't help with third party
backends.)
--
Ticket URL: <https://code.djangoproject.com/ticket/35864>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.