Document how to safely construct email addresses

[Sylvain Fankhauser]

The documentation about sending email (​https://docs.djangoproject.com/en/dev/topics/email/) only provides examples with recipients being only e-mail addresses, without the recipient name. I believe adding the name of the recipient to the To header is a standard practice, and I think Django could provide some guidance on how to escape it properly since it can easily be misused.

For example, a naive way of doing it would be to use f"{first_name} {last_name} <{email}>" (which will fail if first_name, last_name or email contain special characters such as <, >, " or ,. I’m actually guilty of using this in the past, only to find out at my own expense that this wasn’t a good idea). Another way would be to pass the result of sanitize_address((f"{first_name} {last_name}", email), "utf-8") to the to argument, which would work until someone has a name that’s long enough for sanitize_address to add a \n character in the middle, resulting in an error when sanitize_address will be called a second time when actually sending the mail.

I’m still not entirely sure of the proper way to do it properly (and I’m actually surprised I couldn’t find anything about this online). I think the proper way to do it would be to pass the result of email.utils.formataddr((f"{first_name} {last_name}", email)) to the to argument. If you think that’s the correct way to do it and you think the docs could be improved by adding a note about this, I can take care of submitting a patch.

[Mariusz Felisiak]

Thanks for the ticket, however it's rather a support question. Django is not a mail server and we cannot document all related caveats, best practices, and how-to's.

Closing per TicketClosingReasons/UseSupportChannels.

[Claude Paroz]

I would not be so categorical, I think that this is a common use case and a note in the docs wouldn't hurt. Maybe the note would simply redirect to an external reference (Python docs or RFC).

[Jacob Walls]

Reopening and accepting per ​forum discussion, see Mike's implementation advice there.

[Mike Edmunds]

I would suggest reworking the entire existing "Preventing header injection" section as part of this change. Both the text and example can be improved.

A more useful example might be actually treating it as a typical contact form, with name, email, subject and message fields:

• from_email would be f'"{name} via contact form" <contact-form@example.com> (but formatted safely)
• to would be a constant (["contact@example.com"] or something like that)
• reply_to would be [f"{name} <{email}>"] (but formatted safely)
• subject & body would come from the form

This corrects another problem in the current example: trying to use an email from a web form as the from_email. (No email service lets you send messages from any random address. But people building contact forms often think that's how to do it.)

[Raghav Bodani]

I’m planning to work on updating the email documentation to cover safe construction of email addresses, incorporating the suggestions above.

[Raghav Bodani]

Quick update: the first draft of the documentation changes is ready. I will do a final review and open a PR once it’s ready.

[Raghav Bodani]

PR: ​https://github.com/django/django/pull/20431

[Mike Edmunds]

Copying in some of my notes (from a comment in the earlier PR):

I think we need to substantially rework the whole text in the section, so it emphasizes the part that's the *developer's* responsibility (preventing email address syntax injection). I'm not sure how best to word it, but here's what I'd want to convey and roughly the order:

• Email header injection is a security exploit in which an attacker manipulates email headers to change the intended sender, recipients, other headers, or even the entire message.
• Header injection can be caused by newlines in header values (CRLF injection) or by certain characters like commas and parentheses in address headers (address syntax injection). [There doesn't seem to be a standard term for the second type. We could instead say "header content injection" or "delimiter injection".]
• Django builds on Python's email library, which prevents CRLF injection. You'll get a ValueError if you try to send a message with newlines in header values.
• But Django can't protect you from address syntax injection. You are responsible for properly sanitizing email addresses constructed from user-supplied or variable data.
• The best way to construct email addresses is using a well-tested library function intended for the purpose, like Python's email.headerregistry.Address object or (if you don't need IDN support) the legacy email.utils.formataddr() function. (See example below.)
• Never try to use string formatting like f'"{name}" <{email}>' to compose an email address header. This is unsafe, just like building SQL or HTML with string formatting.
• If you're sending email that includes user-supplied content, you'll likely need to take steps to prevent spoofing, spear-phishing, spam cannons, and other malicious uses of email. (Details are beyond the scope of Django docs.)
• Here's an example contact form that demonstrates some of these concepts…

Also, I've been trying to find a replacement link for ​http://www.nyphp.org/phundamentals/8_Preventing-Email-Header-Injection.html, which is heavily PHP centric and a bit outdated. All the general descriptions I could find cover only CRLF injection, not address syntax injection. (And they all use similar PHP code examples.) But maybe one of these? Most are commercial sites; don't know if we have a policy about that:

• ​https://beaglesecurity.com/blog/vulnerability/email-header-injection.html
• ​https://www.invicti.com/learn/email-injection
• ​https://www.acunetix.com/blog/articles/email-header-injection/ (same content, related company, different formatting)
• ​https://en.wikipedia.org/wiki/Email_injection (stub article)

[Mike Edmunds]

​https://github.com/django/django/pull/21467

[Mike Edmunds]

I ended up removing the contact-form-like example entirely. It ended up not helpful. (And we have a better contact form example in the forms docs, though that has some of the issues in my earlier comment. See #37162.)