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
35864	Warn that EmailMessage.connection option is ignored when using send_messages()	Mike Edmunds	Mike Edmunds	"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(host=""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.)"	Cleanup/optimization	closed	Core (Mail)	5.1	Normal	fixed			Ready for checkin	1	0	0	0	0	0