Add RFC 3834 Auto-Submitted header to emails by default

[Tobias Bengfort]

RFC 3824 (​https://www.rfc-editor.org/rfc/rfc3834) defines the Auto-Submitted header for emails to avoid mail loops. The vast majority of mails sent by Django should use Auto-Submitted: auto-generated. The only exceptions I can think of are:

• Django is used in a bigger system that also receives emails. In that case it may also be appropriate to use Auto-Submitted: auto-replied in some cases.
• Django is used to implement an email client. In that case Auto-Submitted should not be used.

Since these are rare exceptions, I think Django should use Auto-Submitted: auto-generated by default. Users who need more control should have to explicitly disable this behavior.

I did not do a larger survey, but just from the mails I currently have in my inbox I noticed that gitlab and unattended-upgrades both use Auto-Submitted.

[Sarah Boyce]

Hi Tobias, thank you for this!
Accepting as this sounds like the right thing to do to me. Added a couple of people in cc in case they have any concerns and can update the ticket accordingly.

[Adam Johnson]

I found very few search results about the header (​DuckDuckGo, ​Google). Notably, I don’t see any “Email best practices” articles discussing this header.

But on GitHub code search there are ​11.4k results for "auto-submitted" "auto-generated", among which I found these tools:

• Wagtail since 2018: ​https://github.com/wagtail/wagtail/blob/1ec62a6c2d99365886e41c517d386d8d36fa5d50/docs/releases/2.3.rst?plain=1#L39)
• Mastodon sets this header: ​https://github.com/mastodon/mastodon/blob/1ad119941ff672b93f2b04dc29f82443349bb69c/app/mailers/application_mailer.rb#L21
• Bugzilla: ​https://github.com/mozilla-bteam/bmo/blob/8192fe39ea8b93a7f3bd16fec4807e5d349ce223/Bugzilla/Mailer.pm#L100

It seems reasonable that Django would set it. But there’s some risk since some search results are people trying to *remove* the header (​1, ​2). I think we should at least document a way to opt-out, possibly by subclassing EmailMessage and overriding message() to delete the header.

[cgracin]

Hello everyone! I'm a new contributor here and just submitted a PR for this feature. I went ahead and added the default behavior to the EmailMessage class to attach the "Auto-Submitted : auto-generated" header. I took the advice of Adam and.created a subclass of EmailMessage named NoAutoSubmittedHeaderEmailMessage that removes the "Auto-Submitted : auto-generated" header to allow a user to opt-out of this default behavior.

[Tobias Bengfort]

Thanks for the patch! I am not sure if NoAutoSubmittedHeaderEmailMessage is the best option though. The way I understood Adam we should document how to create such a class, not provide it in Django itself. Either way, having to use a different Message class is a bit awkward because you can no longer use send_mail(). My proposal would be to add a setting DEFAULT_EMAIL_HEADERS which would be more flexible. I cannot think of any other headers for which this could be useful right now, but who knows. I am not sure whether we want another setting though.

[Sarah Boyce]

I am also not a fan of NoAutoSubmittedHeaderEmailMessage as a user would need to make many updates to their code (including overwriting the EmailMultiAlternatives, mail_admins etc).
I can see the appeal of having something like a DEFAULT_EMAIL_HEADERS setting, however we try to avoid adding new setting to Django when we can. We'd need very strong agreement that this is the best way forward here.
I would recommend creating a discussion on the ​forum to try and get input from a wider audience as to what would be the best approach.

[Tobias Bengfort]

The documentation already contains this line:

Not all features of the EmailMessage class are available through the send_mail() and related wrapper functions. If you wish to use advanced features, such as BCC’ed recipients, file attachments, or multi-part email, you’ll need to create EmailMessage instances directly.
​https://docs.djangoproject.com/en/5.0/topics/email/#the-emailmessage-class

For consistency I think we should also add the Auto-Submitted header in the wrapper functions.

The special thing here would be that dropping down to EmailMessage allows you to remove a header rather than add one. I am not sure how best to explain that in the docs. I see that most parameters are only documented once for send_mail() and not repeated for the other wrapper functions. So maybe it would be sufficient to add a note only to send_mail(). The note could be something like this:

send_mail() uses the Auto-Submitted mail header to indicate that the mail was created by software rather than a human.

[cgracin]

Thank you guys for the comments, I'll work on implementing these requests and submit an updated PR.

[David Smith]

Does the header need to be removed entirely? Could we advise folk to set the header to "no" to disable it?
​https://www.iana.org/assignments/auto-submitted-keywords/auto-submitted-keywords.xhtml

The current patch has this to add the header:

if "Auto-Submitted" not in self.extra_headers: 
     # Default to adding the Auto-Submitted: auto-generated header 
     self.extra_headers["Auto-Submitted"] = "auto-generated"

So could we documentat this by something like...

By default EmailMessage sets the Auto-Submitted header to auto-generated to indicate that the mail was created by software rather than a human. The value of the Auto-Submitted header can be customised by the headers option. To disable the header the value of Auto-Submitted can be set to "no".