Document how to properly escape `to` in email messages

[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).