Console EmailBackend option to show developer-readable email messages

[medmunds]

Code of Conduct

• I agree to follow Django's Code of Conduct

Feature Description

Add an option to Django's console and file EmailBackends to display non-ASCII characters as Unicode (utf-8), rather than the various 7-bit encodings used for SMTP transmission.

Problem

Django's console and filebased EmailBackends output email messages exactly as they would be passed to an SMTP server. That's helpful for debugging SMTP, but not so helpful if you just want to see the content being emailed. And it can be confusing if you aren't familiar with the variety of different encodings needed to represent non-ASCII characters for 7-bit SMTP transmission.

For example, the console EmailBackend might show this for a password reset email. Notice the subject header and message body:

Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: base64
MIME-Version: 1.0
Subject: =?utf-8?b?0KHQutC40LTQsNC90L3RjyDQv9Cw0YDQvtC70Y8g0L3QsCDQn9GA0LjQutC70?=
 =?utf-8?b?LDQtCDRgdCw0LnRgtGD?=
From: webmaster@django.example.com
To: user@example.com
Date: Sat, 30 May 2026 20:21:35 +0000
Message-ID: 178017249531.136945.18351584476362565960@django.example.com

0JLQuCDQvtGC0YDQuNC80LDQu9C4INGG0LXQuSDQu9C40YHRgiDRh9C10YDQtdC3INGC0LUsINGJ
0L4g0LfRgNC+0LHQuNC70Lgg0LfQsNC/0LjRgiDQvdCwINC/0LXRgNC10LLRgdGC0LDQvdC+0LLQ
u9C10L3QvdGPINC/0LDRgNC+0LvRjyDQtNC70Y8g0L7QsdC70ZbQutC+0LLQvtCz0L4g0LfQsNC/
0LjRgdGDINC60L7RgNC40YHRgtGD0LLQsNGH0LAg0L3QsCDQn9GA0LjQutC70LDQtCDRgdCw0LnR
gtGDLgoK0JHRg9C00Ywg0LvQsNGB0LrQsCwg0L/QtdGA0LXQudC00ZbRgtGMINC90LAg0YbRjiDR
gdGC0L7RgNGW0L3QutGDLCDRgtCwINC+0LHQtdGA0ZbRgtGMINC90L7QstC40Lkg0L/QsNGA0L7Q
u9GMOgpodHRwOi8vZGphbmdvLmV4YW1wbGUuY29tL3Bhc3N3b3JkLXJlc2V0L01nL2Q5ZjB4ei03
YWI0Yjg4ZjQ2MTEzMWJlZjdiMTBiMzI4YzQ3OGM1ZS8K

In many cases, it would be more useful to show the original, unencoded Unicode text:

Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Subject: Скидання пароля на Приклад сайту
From: webmaster@django.example.com
To: user@example.com
Date: Sat, 30 May 2026 20:21:35 +0000
Message-ID: 178017249531.136945.18351584476362565960@django.example.com

Ви отримали цей лист через те, що зробили запит на перевстановлення пароля для облікового запису користувача на Приклад сайту.

Будь ласка, перейдіть на цю сторінку, та оберіть новий пароль:
http://django.example.com/password-reset/Mg/d9f0xz-7ab4b88f461131bef7b10b328c478c5e/

Request or proposal

proposal

Additional Details

See (e.g.,) this forum topic. The developer assumed (reasonably, imho) that the base64-encoded message body echoed to the console was a bug.

With the console backend becoming the default for new projects in the 6.1 settings template, we're likely to start seeing similar reports more often.

Implementation Suggestions

[Edit: see updated proposal in a later comment.]

We could add a decode boolean option to the console and filebased backends:

MAILERS = {
    "default": {
        "BACKEND": "django.core.mail.backends.console.EmailBackend",
        "OPTIONS": {"decode": True},
    },
}

When decode is True, we'd change the message serialization in write_message() so the original, unencoded text content would be written to the console or file (as Unicode text). I think it would also be good to update the new-project settings template to include the decode option as shown above.

Some experimentation would be needed for getting the email message "as Unicode text." A few options are:

• Serializing with policy=email.policy.default.clone(utf8=True, max_line_length=0, cte_type="8bit"). This avoids most 7-bit encoding (though would still use rfc2231 for attachment filenames). But it would result in very long (unwrapped) lines in message bodies. (Setting policy.max_line_length to anything other than 0 would use base64 or quoted-printable when wrapping non-ASCII text parts, which defeats the purpose.)
• Not serializing the message with as_bytes(), but instead walking the Python EmailMessage and writing each part as Unicode text. This would guarantee no 7-bit encodings anywhere, and is probably the most flexible (if a bit more work).

In either case, we might want some sort of wrapping for the console. That could be something like textwrap.wrap() or just a hard wrap at 79 chars. Maybe also a separate wrap or max_line_length option to control this.

(Incidentally, I'd originally wanted to handle this as a new policy option, allowing any email.policy.Policy object for serialization. Unfortunately, that alone isn't sufficient for the console backend, if we want to wrap text bodies in the output.)

[github-actions]

Thank you medmunds for sharing your idea! We have a lot of them so please be patient. You can see the current queue here.

Community instructions

For commenters, please use the emoji reactions on the issue to express support, and/or concern easily. Please use the comments to ask questions or contribute knowledge about the idea. It is unhelpful to post comments of "I'd love this" or "What's the state of this?"

Reaction Guide

• 👍 This is something I would use
• 👎 This is something that would cause problems for me or Django
• 😕 I’m indifferent to this
• 🎉 This is an easy win

[codingjoe]

While I agree with the use case, this may break emark's console backend. It implements a similar behavior, where it will generate a console-friendly text version and omit HTML bodies from the console.

I believe we mainly implemented it to quickly get OTPs for development.

[medmunds]

While I agree with the use case, this may break emark's console backend.

Could you explain more? The new behavior would be opt-in via "OPTIONS": {"decode": True} in the configuration. Without that, Django's console backend would behave exactly as it does today.

It implements a similar behavior, where it will generate a console-friendly text version and omit HTML bodies from the console.

While mocking this up yesterday, I realized encoded binary attachment data isn't very console-friendly, so elided that with [Binary image/png data: 1_029_763 bytes]. An option to also elide HTML parts (or anything other than text/plain) might also be helpful.

Also, I'm open to suggestions on the option name. "decode" doesn't seem exactly right. (It's more like "skip encoding," but even that isn't precise.) Maybe "friendly": True?

[medmunds]

I cleaned up my prototype from yesterday and stuck it in a draft PR. There's also a longer example showing a multipart message with attachments.

[tim-mccurrach]

I definitely think we should do something here. It's a good example of django being anglo-(or at least western)-centric that we should fix. Given we have translations for our built-in emails (such as auth related ones) out of the box, I think it's reasonable to expect our debugging-tools (such as the console email backend) to also work well with the translations out of the box.

As such, I think we should really (via a suitable deprecation path) aim to have, (at least part of) what is described be the default behaviour.

My worry about the proposal above is how you decide what should be included in "friendly" mode. I imagine that over time there will be other things that folks would want to be included. It's also not clear to me that we necessarily want to couple better decoding with simplified presentation of binary attachments. I think my preference here would be for an option such as "serialize" that points to a serialization function, and to provide a sensible default. That way we avoid lots of options, can provide an alternative function for those who want to maintain current behaviour, and if folks want to further customise it they can. (Having said that, it is already relatively easy to sub-class the console backend if you wanted to do customisation).

Sorry for the slightly stream-of-consciousness-y reply. I hope it's helpful.

[codingjoe]

While I agree with the use case, this may break emark's console backend.

Could you explain more? The new behavior would be opt-in via "OPTIONS": {"decode": True} in the configuration. Without that, Django's console backend would behave exactly as it does today.

We override write_message as along as the API doens't change, I believe we would be fine. See also: https://github.com/voiio/emark/blob/main/emark/backends.py#L85-L106

It implements a similar behavior, where it will generate a console-friendly text version and omit HTML bodies from the console.

While mocking this up yesterday, I realized encoded binary attachment data isn't very console-friendly, so elided that with [Binary image/png data: 1_029_763 bytes]. An option to also elide HTML parts (or anything other than text/plain) might also be helpful.

Also, I'm open to suggestions on the option name. "decode" doesn't seem exactly right. (It's more like "skip encoding," but even that isn't precise.) Maybe "friendly": True?

I like the idea, but I'd invert it. Default is pretty-printing and you can set raw=True.
Considering that we are going for a useful change, post people will prefer the userful output.
Only people who are debugging SMTP issues may need the actual raw SMTP transmission and they can enable it if they care to.

You may also consider just adding two backends. A pretty console backend and a raw console backend :)

[medmunds]

OK, here's an updated proposal with raw, defaulting to pretty-printing in the console backend (with standard deprecation)…

The goal is for the console EmailBackend to present a readable, useful representation of sent emails for developers. And for it to (eventually) do this by default.

• Add a raw boolean option to Django's console and filebased email backends. (Note the file backend is a subclass of console.)
• When raw=True, the message is formatted exactly as it would be for SMTP transition (as those backends do today)
• When raw=False, the message is pretty-printed to maximize readability and utility for developers:
  • Headers and text bodies are shown in the original Unicode characters (not encoded to 7-bit for SMTP), and are not wrapped. (The user's own terminal or editor should wrap long lines at the user's preferred width.)
  • Long text bodies are clipped at max_text_length characters with a [... N more characters] annotation. (Default is 1024, but configurable; can be disabled with max_text_length=None.)
  • Binary attachments are shown as the content type and byte length (not encoded data).
  • Bcc recipients are identified (see ticket-28598)
  • Multipart message boundaries are shown as deterministic, sequential separators for easier reading (not random strings)
• For the file backend, the default is raw=True. (The assumption is the file backend is often used for things like snapshot tests, and should default to capturing the complete message in a machine-parsable form.)
• For the console backend, the default is raw=False after a standard deprecation period. During deprecation, the default is raw=True to preserve the current behavior, but a deprecation warning is issued if the value isn't explicitly specified.
• Update the new-project settings.py template to specify raw=False for its console default MAILERS config. (This only affects newly-created projects, so doesn't require deprecation.)

I've updated the draft PR to match. (Still no tests or documentation.)