django / django/new-features

Support sending to Unicode emails in the SMTP EmailBackend (EAI, SMTPUTF8)

Open
#206 2 comments 5 reactions 0 assignees View on GitHub
Django Core Email Internationalization
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.