Support sending to Unicode emails in the SMTP EmailBackend (EAI, SMTPUTF8)
- Dominant language
- No language data
- Stars
- 188
- Forks
- 7
- PR merge metrics
- No merged PRs in 30d
Description
### Code of Conduct
- [x] I agree to follow Django's Code of Conduct
### Feature Description
Update Django's SMTP EmailBackend to allow sending to (or from) email addresses that have Unicode usernames, like `jlópez@example.mx`, when using a compatible SMTP server that supports the SMTPUTF8 extension.
[Relocated and updated from [https://code.djangoproject.com/ticket/35714](https://code.djangoproject.com/ticket/35714).]
### Problem
Although Django's SMTP EmailBackend has long supported sending email to internationalized domain names (IDNs), it currently raises an error if you try to send to a Unicode mailbox. In Django 6.1:
* `julial@periódico.example.mx`: works
* `jlópez@noticias.example.mx`: ValueError "Invalid address …: local-part contains non-ASCII characters"
Supporting non-ASCII mailboxes is part of email address internationalization (EAI), which is part of the broader [Universal Acceptance](https://www.icann.org/ua) initiative for a multilingual, digitally inclusive Internet.
["Mailbox," "local-part," and "username" are used interchangeably to refer to the part of an email address before the `@`.]
### Request or proposal
proposal
### Additional Details
See [RFC 6530](https://datatracker.ietf.org/doc/html/rfc6530.html) *Overview and Framework for Internationalized Email* or Wikipedia's [International email](https://en.wikipedia.org/wiki/International_email) for additional background. The SMTPUTF8 extension is defined by [RFC 6531](https://datatracker.ietf.org/doc/html/rfc6531.html).
Much of the popular [SMTP server software already supports SMTPUTF8](https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol#SMTPUTF8). And larger email services like Gmail and Outlook have begun supporting EAI. The Universal Acceptance Steering Group (UASG)'s [2025 UA Readiness report](https://uasg.tech/wp-content/uploads/2025/06/UASG-10-Year-and-2025-UA-Readiness-Report.pdf) (PDF, section 3) includes a recent EAI assessment and adoption trends.
[The UASG also evaluates EAI compliance in programming languages and frameworks. It last looked at Django [in 2020](https://uasg.tech/download/uasg-018a-ua-compliance-of-some-programming-language-libraries-and-frameworks-en/?wpdmdl=3658&refresh=6a98a5a3cc8891788388771) (PDF, p. 11) with a "UA not ready" conclusion, based on lack of `EmailValidator` support. That's a separate issue: see ticket-27029 and some related discussion in ticket-26423. Enabling EAI in the validator and in the SMTP backend can and should be handled as independent (though related) Django features.]
### Implementation Suggestions
Add a new `smptutf8` option that can be configured in `MAILERS` options for an SMTP backend. Valid values would be:
* `True`: unconditionally use SMTPUTF8. Generate messages with 8-bit headers using email.policy.SMTPUTF8, and request the SMTPUTF8 extension in smtplib's `sendmail(..., mail_options)`—raising an error if the server doesn't support it.
* `False`: never use SMTPUTF8. Raise an error when attempting to send a message with non-ASCII local-parts in any email address.
* `None`: ("auto mode", the default) if an individual message includes any non-ASCII local-parts in any email address, try to use SMTPUTF8 for that message—and raise an error if the server doesn't support it. For all other messages, don't try to use SMTPUTF8. (This is similar to what Python's [`SMTP.send_message()`](https://docs.python.org/3/library/smtplib.html#smtplib.SMTP.sendmail) convenience method does.)
The `True` setting is intended for use with an SMTP host that is known to support SMTPUTF8. It offers a slight performance advantage over the `None` option. Also, it would be the only way to use SMTPUTF8 (rather than RFC 2047 encoded headers) for messages that have non-ASCII characters in headers like ''Subject,'' but only ASCII local-parts in addresses.
When the SMTP backend uses SMTPUTF8 for a message (either via `True` or auto mode), it will also pass any non-ASCII domains (IDNs) in email addresses directly to the SMTP server, rather than performing its own IDNA encoding.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start by reading Django's SMTP EmailBackend and Python's smtplib sendmail()/send_message() behavior, then trace how MAILERS options and message headers are handled. Done means supporting the proposed True, False, and None SMTPUTF8 modes, including Unicode local-parts and domains, with the specified server capability errors and message formatting.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- django, python
- Domain
- backend, internationalization
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100