Postfix SMTPUTF8 support


This document describes Postfix support for Email Address Internationalization (EAI) as defined in RFC 6531 (SMTPUTF8 extension), RFC 6532 (Internationalized email headers) and RFC 6533 (Internationalized delivery status notifications). Introduced with Postfix version 3.0, this fully supports UTF-8 email addresses and UTF-8 message header values.

Topics covered in this document:

Building Postfix with/without SMTPUTF8 support

Postfix will build with SMTPUTF8 support if the ICU version ≥ 46 library and header files are installed on the system. The package name varies with the OS distribution. The table shows package names for a number of platforms at the time this text was written.

OS Distribution Package
FreeBSD, NetBSD, etc. icu
Centos, Fedora, RHEL libicu-devel
Debian, Ubuntu libicu-dev

To force Postfix to build without SMTPUTF8, specify:

$ make makefiles CCARGS="-DNO_EAI ..."

See the INSTALL document for more "make makefiles" options.

Enabling Postfix SMTPUTF8 support

There is more to SMTPUTF8 than just Postfix itself. The rest of your email infrastructure also needs to be able to handle UTF-8 email addresses and message header values. This includes SMTPUTF8 protocol support in SMTP-based content filters (Amavisd), LMTP servers (Dovecot), and down-stream SMTP servers.

Postfix SMTPUTF8 support is enabled by default, but it may be disabled as part of a backwards-compatibility safety net (see the COMPATIBILITY_README file).

SMTPUTF8 support is enabled by setting the smtputf8_enable parameter in

# postconf "smtputf8_enable = yes"
# postfix reload

(With Postfix ≤ 3.1, you may also need to specify "option_group = client" in Postfix MySQL client files, to enable UTF8 support in MySQL queries. This setting is the default as of Postfix 3.2.)

With SMTPUTF8 support enabled, Postfix changes behavior with respect to earlier Postfix releases:

Postfix already permitted UTF-8 in message header values and in address localparts. This does not change.

Using Postfix SMTPUTF8 support

After Postfix SMTPUTF8 support is turned on, Postfix behavior will depend on 1) whether a remote SMTP client requests SMTPUTF8 support, 2) the presence of UTF-8 content in the message envelope and headers, and 3) whether a down-stream SMTP (or LMTP) server announces SMTPUTF8 support.

SMTPUTF8 autodetection

This section applies only to systems that have SMTPUTF8 support turned on (smtputf8_enable = yes).

For compatibility with pre-SMTPUTF8 environments, Postfix does not automatically set the "SMTPUTF8 requested" flag on messages from non-SMTPUTF8 clients that contain a UTF-8 header value or UTF-8 address localpart. This would make such messages undeliverable to non-SMTPUTF8 servers, and could be a barrier to SMTPUTF8 adoption.

By default, Postfix sets the "SMTPUTF8 requested" flag only on address verification probes and on Postfix sendmail submissions that contain UTF-8 in the sender address, UTF-8 in a recipient address, or UTF-8 in a message header value.

    smtputf8_autodetect_classes = sendmail, verify

However, if you have a non-ASCII myorigin or mydomain setting, or if you have a configuration that introduces UTF-8 addresses with virtual aliases, canonical mappings, or BCC mappings, then you may have to apply SMTPUTF8 autodetection to all email:

    smtputf8_autodetect_classes = all

This will, of course, also flag email that was received without SMTPUTF8 request, but that contains UTF-8 in a sender address localpart, receiver address localpart, or message header value. Such email was not standards-compliant, but Postfix would have delivered it if SMTPUTF8 support was disabled.

Limitations of the current implementation

The Postfix implementation is a work in progress; limitations are steadily being removed. The text below describes the situation at one point in time.

No automatic conversions between ASCII and UTF-8 domain names.

Some background: According to RFC 6530 and related documents, an internationalized domain name can appear in two forms: the UTF-8 form, and the ASCII (xn--mumble) form. An internationalized address localpart must be encoded in UTF-8; the RFCs do not define an ASCII alternative form.

Postfix currently does not convert internationalized domain names from UTF-8 into ASCII (or from ASCII into UTF-8) before using domain names in SMTP commands and responses, before looking up domain names in lists such as mydestination, relay_domains or in lookup tables such as access tables, etc., before using domain names in a policy daemon or Milter request, or before logging events.

Postfix does, however, casefold domain names and email addresses before matching them against a Postfix configuration parameter or lookup table.

In order to use Postfix SMTPUTF8 support:

Compatibility with pre-SMTPUTF8 environments

Mailing lists with UTF-8 and non-UTF-8 subscribers

With Postfix, there is no need to split mailing lists into UTF-8 and non-UTF-8 members. Postfix will try to deliver the non-UTF8 subscribers over "traditional" non-SMTPUTF8 sessions, as long as the message has an ASCII envelope sender address and all-ASCII header values. The mailing list manager may have to apply RFC 2047 encoding to satisfy that last condition.

Pre-existing non-ASCII email flows

With "smtputf8_enable = no", Postfix handles email with non-ASCII in address localparts (and in headers) as before. The vast majority of email software is perfectly capable of handling such email, even if pre-SMTPUTF8 standards do not support such practice.

Rejecting non-UTF8 addresses

With "smtputf8_enable = yes", Postfix requires that non-ASCII address information is encoded in UTF-8 and will reject other encodings such as ISO-8859. It is not practical for Postfix to support multiple encodings at the same time. There is no problem with RFC 2047 encodings such as "=?ISO-8859-1?Q?text?=", because those use only characters from the ASCII characterset.

Rejecting non-ASCII addresses in non-SMTPUTF8 transactions

Setting "strict_smtputf8 = yes" in addition to "smtputf8_enable = yes" will enable stricter enforcement of the SMTPUTF8 protocol. Specifically, the Postfix SMTP server will not only reject non-UTF8 sender or recipient addresses, it will in addition accept UTF-8 sender or recipient addresses only when the client requests an SMTPUTF8 mail transaction.

Compatibility with IDNA2003

Postfix ≥ 3.2 by default disables the 'transitional' compatibility between IDNA2003 and IDNA2008, when converting UTF-8 domain names to/from the ASCII form that is used in DNS lookups. This makes Postfix behavior consistent with current versions of the Firefox and Chrome web browsers. Specify "enable_idna2003_compatibility = yes" to get the historical behavior.

This affects the conversion of domain names that contain for example the German sz (ß) and the Greek zeta (ς). See for more examples.