Free trial The cheapest email marketing platform: try Moosend free for 30 days, no credit card. Don't miss your seat. The cheapest email marketing platform Start free trial →

RFC 2231: MIME Parameter Value and Encoded Word Extensions

RFC 2231 lets MIME parameters such as attachment filenames carry non-ASCII text and long values. The three syntax forms, real library output, and why filenames arrive garbled.

Alaa Touil
Email infrastructure specialist, 8+ years in SMTP and deliverability
4 min read Updated Nov 9, 2026 301 views
RFC 2231 MIME Parameter Value and Encoded Word Extensions - SMTPedia reference
RFC 2231
MIME Parameter Value and Encoded Word Extensions

Current standard

Domain
MIME
Published
November 1997
Obsoletes
RFC 2184
SMTP relevance
Medium

↗ Read on rfc-editor.org

What this RFC defines

RFC 2231 extends MIME parameter handling to support non-ASCII characters and long values in Content-Type and Content-Disposition parameter fields. It defines a character set and language tagging syntax for parameter values, solving the problem of how to include accented or non-Latin characters in an attachment filename header.

Where you see it in practice

When you receive an email attachment with a filename containing non-ASCII characters (like accented letters or CJK characters) and your email client displays it correctly, RFC 2231 encoding is what made that possible. A correctly encoded Content-Disposition header for a French filename looks like: Content-Disposition: attachment; filename*=UTF-8''R%C3%A9sum%C3%A9.pdf (two single quotes: the empty slot between them is the optional language tag). Email clients that do not implement RFC 2231 may display garbled filenames for international attachments.

How it connects to other RFCs

RFC 2231 obsoletes RFC 2184 and extends RFC 2045 (MIME framework) and RFC 2183 (Content-Disposition). It complements RFC 2047, which handles non-ASCII in message headers but does not cover parameter values. Together they provide complete non-ASCII support for MIME messages.

Current status

RFC 2231 is a current standard, published November 1997. Its encoding for non-ASCII filenames is supported by most modern email clients, though interoperability issues still occur with older implementations that do not recognise the filename* parameter syntax.

Parameter continuation and encoding

RFC 2231 addressed two limitations of the original MIME headers. First, MIME parameters (like Content-Type filename or Content-Disposition filename) could not exceed line length limits, which made long filenames impossible. RFC 2231 introduced parameter continuation using an asterisk-numbered syntax: filename*0=”part1″; filename*1=”part2″. Second, parameter values were limited to ASCII, which prevented filenames in non-English languages. RFC 2231 added a charset-language-value syntax: filename*=UTF-8”Caf%C3%A9.pdf, where the value is percent-encoded UTF-8.

Common interoperability issues

RFC 2231 is famously inconsistently implemented. Outlook historically preferred an older encoding style (RFC 2047 encoded-words in Content-Disposition, which is technically incorrect but widespread). Some servers strip continuation numbers, breaking long filenames. Some clients only support the continuation OR the charset syntax but not both. If you have ever received an attachment with a garbled filename (mojibake, question marks, or the raw =?UTF-8?B?…?= string visible), RFC 2231 non-conformance is the likely cause.

Testing and best practice

Best practice for outbound mail is to generate both RFC 2231 continuation-and-charset syntax AND an RFC 2047 encoded-word for maximum client compatibility. Libraries differ here: some emit only RFC 2231, others add the encoded-word form as well, so check what yours produces (see the Python test below). Testing across Outlook, Gmail, Apple Mail, and Thunderbird is the standard conformance check; if any of these renders the filename incorrectly, adjust the encoding strategy. For CLI utilities and legacy code, the RFC 2231 handling is often where filename bugs originate.

The three RFC 2231 tricks, decoded

FeatureSyntaxWhat it solves
Charset and languagefilename*=UTF-8'fr'R%C3%A9sum%C3%A9.pdfNon-ASCII values: charset, optional language tag, then percent-encoded bytes
Continuationfilename*0="a-very-long"; filename*1="-name.pdf"Values longer than a header line, split into numbered pieces
Both togetherfilename*0*=UTF-8''R%C3%A9...; filename*1*=%C3%A8s...Long non-ASCII values: only the first piece carries the charset, every encoded piece ends with *

What a real library produces

We attached a file named “Résumé de l’équipe 2026 très long nom de fichier pour tester.pdf” with Python’s standard email package in November 2026. It used the combined form, on its own:

Python email.message.EmailMessage, add_attachment()
Content-Disposition: attachment;
filename*0*=utf-8”R%C3%A9sum%C3%A9%20de%20l%E2%80%99%C3%A9quipe%202026%20tr;
filename*1*=%C3%A8s%20long%20nom%20de%20fichier%20pour%20tester.pdf

This is valid RFC 2231. A client that does not understand continuations and charsets together will show a garbled or missing name. If your recipients include older desktop clients or document management systems, test with them, and consider shorter ASCII filenames for files that must open everywhere.

The same syntax on the web. HTTP reuses the RFC 2231 charset syntax for downloads: Content-Disposition: attachment; filename*=UTF-8''... is defined for HTTP by RFC 6266 and RFC 8187. If a file downloads with the right name from your website but arrives garbled by email, the difference is usually the continuation pieces, which HTTP does not use.

Did this guide save you time?

SMTPedia is free and independent. A coffee helps keep every guide accurate.

Buy SMTPedia a coffee

See SMTPedia first on Google

Add us as a preferred source in Top Stories.

Add as preferred source

About the Author

Alaa - SMTPedia author

Alaa · LinkedIn

Email infrastructure specialist with 8+ years of hands-on experience in SMTP, deliverability, and email verification. I’ve configured and troubleshot mail systems across Postfix, Exchange, and cloud relays, managed IP reputation and warmup campaigns, and built verification pipelines processing millions of addresses. My work spans DNS authentication (SPF, DKIM, DMARC, BIMI), bounce handling, blocklist monitoring, and compliance frameworks including CAN-SPAM and GDPR. I write every article on SMTPedia to give email professionals, developers, and marketers the accurate, RFC-grounded reference they need.


About SMTPedia

SMTPedia is an independent email industry reference covering SMTP, IMAP, POP3, email deliverability, marketing platforms, DNS authentication, and email verification. Every article is researched from official provider documentation, IETF RFCs, and industry best practices. Settings and configurations are verified quarterly.

We are cited as a source by ChatGPT, Microsoft Copilot, and thousands of email professionals worldwide. Learn more about our editorial process.