dist/html/SMTPUTF8_README.html

<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
        "http://www.w3.org/TR/html4/loose.dtd">

<html>

<head>

<title>Postfix SMTPUTF8 support</title>

<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">

</head>

<body>

<h1><img src="postfix-logo.jpg" width="203" height="98" ALT="">
Postfix SMTPUTF8 support
</h1>

<hr>

<h2> Overview </h2>

<p> This document describes Postfix support for Email Address
Internationalization (EAI) as defined in <a href="https://tools.ietf.org/html/rfc6531">RFC 6531</a> (SMTPUTF8 extension),
<a href="https://tools.ietf.org/html/rfc6532">RFC 6532</a> (Internationalized email headers) and <a href="https://tools.ietf.org/html/rfc6533">RFC 6533</a> (Internationalized
delivery status notifications). Introduced with Postfix version
3.0, this fully supports UTF-8 email addresses and UTF-8 message
header values. </p>

<p> Topics covered in this document: </p>

<ul>

<li><a href="#building">Building with/without SMTPUTF8 support</a>

<li><a href="#enabling">Enabling Postfix SMTPUTF8 support</a>

<li><a href="#using">Using Postfix SMTPUTF8 support</a>

<li><a href="#detecting">SMTPUTF8 autodetection</a>

<li><a href="#limitations">Limitations of the current implementation</a>

<li><a href="#compatibility">Compatibility with pre-SMTPUTF8 environments</a>

<li><a href="#idna2003">Compatibility with IDNA2003</a>

<li><a href="#credits">Credits</a>

</ul>

<h2> <a name="building">Building Postfix with/without SMTPUTF8 support</a> </h2>

<p> Postfix will build with SMTPUTF8 support if the ICU version
&ge; 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.
</p>

<blockquote>

<table border="1">

<tr> <th> OS Distribution </th> <th> Package </th> </tr>

<tr> <td> FreeBSD, NetBSD, etc. </td> <td> icu </td> </tr>

<tr> <td> Centos, Fedora, RHEL </td> <td> libicu-devel </td> </tr>

<tr> <td> Debian, Ubuntu </td> <td> libicu-dev </td> </tr>

</table>

</blockquote>

<p> To force Postfix to build without SMTPUTF8, specify: </p>

<blockquote>
<pre>
$ <b>make makefiles CCARGS="-DNO_EAI ..."</b>
</pre>
</blockquote>

<p> See the <a href="INSTALL.html">INSTALL</a> document for more "make makefiles" options. </p>

<h2> <a name="enabling">Enabling Postfix SMTPUTF8 support</a> </h2>

<p> 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. </p>

<p> Postfix SMTPUTF8 support is enabled by default, but it may be
disabled as part of a backwards-compatibility safety net (see the
<a href="COMPATIBILITY_README.html">COMPATIBILITY_README</a> file). </p>

<p> SMTPUTF8 support is enabled by setting the <a href="postconf.5.html#smtputf8_enable">smtputf8_enable</a>
parameter in <a href="postconf.5.html">main.cf</a>:</p>

<blockquote>
<pre>
# <b>postconf "<a href="postconf.5.html#smtputf8_enable">smtputf8_enable</a> = yes"</b>
# <b>postfix reload</b>
</pre>
</blockquote>

<p> (With Postfix &le; 3.1, you may also need to specify "<b>option_group
= client</b>" in Postfix MySQL client files, to enable UTF8 support
in MySQL queries. This setting is the default as of Postfix 3.2.) </p>

<p> With SMTPUTF8 support enabled, Postfix changes behavior with
respect to earlier Postfix releases: </p>

<ul>

<li> <p> UTF-8 is permitted in the <a href="postconf.5.html#myorigin">myorigin</a> parameter value. However,
the <a href="postconf.5.html#myhostname">myhostname</a> and <a href="postconf.5.html#mydomain">mydomain</a> parameters must currently specify
ASCII-only domain names. This limitation may be removed later. </p>

<li> <p> UTF-8 is the only form of non-ASCII text that Postfix
supports in access tables, address rewriting tables, and other
tables that are indexed with an email address, hostname, or domain
name. </p>

<li> <p> The <a href="postconf.5.html#header_checks">header_checks</a>-like and <a href="postconf.5.html#body_checks">body_checks</a>-like features are
not UTF-8 enabled, and therefore they do not enforce UTF-8 syntax
rules on inputs and outputs.  The reason is that non-ASCII text may
be sent in encodings other than UTF-8, and that real email sometimes
contains malformed headers.  Instead of skipping non-UTF-8 content,
Postfix should be able to filter it.  You may try to enable UTF-8
processing by starting a PCRE pattern with the sequence (*UTF8),
but this is will result in "message not accepted, try again later"
errors when the PCRE pattern matcher encounters non-UTF-8 input.
Other features that are not UTF-8 enabled are <a href="postconf.5.html#smtpd_command_filter">smtpd_command_filter</a>,
<a href="postconf.5.html#smtp_reply_filter">smtp_reply_filter</a>, the *_delivery_status_filter features, and the
*_dns_reply_filter features (the latter because DNS is by definition
an ASCII protocol).  </p>

<li> <p> The Postfix SMTP server announces SMTPUTF8 support in the
EHLO response. </p>

<pre>
220 server.example.com ESMTP Postfix
<b>EHLO client.example.com</b>
250-server.example.com
250-PIPELINING
250-SIZE 10240000
250-VRFY
250-ETRN
250-STARTTLS
250-AUTH PLAIN LOGIN
250-ENHANCEDSTATUSCODES
250-8BITMIME
250-DSN
250 SMTPUTF8
</pre>

<li> <p> The Postfix SMTP server accepts the SMTPUTF8 request in
MAIL FROM and VRFY commands. </p>

<pre>
<b>MAIL FROM:&lt;address&gt; SMTPUTF8 ...</b>

<b>VRFY address SMTPUTF8</b>
</pre>

<li> <p> The Postfix SMTP client may issue the SMTPUTF8 request in
MAIL FROM commands. </p>

<li> <p> The Postfix SMTP server accepts UTF-8 in email address
domains, but only after the remote SMTP client issues the
SMTPUTF8 request in MAIL FROM or VRFY commands.  </p>

</ul>

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

<h2> <a name="using">Using Postfix SMTPUTF8 support</a> </h2>

<p> 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. </p>

<ul>

<li> <p> When the Postfix SMTP server receives a message WITHOUT
the SMTPUTF8 request, Postfix handles the message as it has always
done (at least that is the default, see autodetection below).
Specifically, the Postfix SMTP server does not accept UTF-8 in the
envelope sender domain name or envelope recipient domain name, and
the Postfix SMTP client does not issue the SMTPUTF8 request when
delivering that message to an SMTP or LMTP server that announces
SMTPUTF8 support (again, that is the default). Postfix will accept
UTF-8 in message header values and in the localpart of envelope
sender and recipient addresses, because it has always done that.
</p>

<li> <p>  When the Postfix SMTP server receives a message WITH the
SMTPUTF8 request, Postfix will issue the SMTPUTF8 request when
delivering that message to an SMTP or LMTP server that announces
SMTPUTF8 support. This is not configurable. </p>

<li> <p>  When a message is received with the SMTPUTF8 request,
Postfix will deliver the message to a non-SMTPUTF8 SMTP or LMTP
server ONLY if: </p>

    <ul>

    <li> <p>  No message header value contains UTF-8. </p>

    <li> <p>  The envelope sender address contains no UTF-8, </p>

    <li> <p>  No envelope recipient address for that specific
    SMTP/LMTP delivery transaction contains UTF-8. </p>

        <blockquote> <p> NOTE: Recipients in other email delivery
        transactions for that same message may still contain UTF-8.
        </p> </blockquote>

   </ul>

   <p> Otherwise, Postfix will return the recipient(s) for that
   email delivery transaction as undeliverable. The delivery status
   notification message will be an SMTPUTF8 message. It will therefore
   be subject to the same restrictions as email that is received
   with the SMTPUTF8 request. </p>

<li> <p>  When the Postfix SMTP server receives a message with the
SMTPUTF8 request, that request also applies after the message is
forwarded via a virtual or local alias, or $HOME/.forward file.
</p>

</ul>

<h2> <a name="detecting">SMTPUTF8 autodetection</a> </h2>

<p> This section applies only to systems that have SMTPUTF8 support
turned on (<a href="postconf.5.html#smtputf8_enable">smtputf8_enable</a> = yes). </p>

<p> 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.
</p>

<p> 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. </p>

<blockquote>
<pre>
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
    <a href="postconf.5.html#smtputf8_autodetect_classes">smtputf8_autodetect_classes</a> = sendmail, verify
</pre>
</blockquote>

<p> However, if you have a non-ASCII <a href="postconf.5.html#myorigin">myorigin</a> or <a href="postconf.5.html#mydomain">mydomain</a> 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: </p>

<blockquote>
<pre>
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
    <a href="postconf.5.html#smtputf8_autodetect_classes">smtputf8_autodetect_classes</a> = all
</pre>
</blockquote>

<p> 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. </p>

<h2> <a name="limitations">Limitations of the current implementation</a>
</h2>

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

<h3> No automatic conversions between ASCII and UTF-8 domain names. </h3>

<p> Some background: According to <a href="https://tools.ietf.org/html/rfc6530">RFC 6530</a> 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. </p>

<p> 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 <a href="postconf.5.html#mydestination">mydestination</a>, <a href="postconf.5.html#relay_domains">relay_domains</a> or in
lookup tables such as access tables, etc., before using domain names
in a policy daemon or Milter request, or before logging events.
</p>

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

<p> In order to use Postfix SMTPUTF8 support: </p>

<ul>

<li> <p> The Postfix parameters <a href="postconf.5.html#myhostname">myhostname</a> and <a href="postconf.5.html#mydomain">mydomain</a> must be in
ASCII form. One is a substring of the other, and the <a href="postconf.5.html#myhostname">myhostname</a>
value is used in SMTP commands and responses that require ASCII.
The parameter <a href="postconf.5.html#myorigin">myorigin</a> (added to local addresses without domain)
supports UTF-8.  </p>

<li> <p> You need to configure both the ASCII and UTF-8 forms of
an Internationalized domain name in Postfix parameters such as
<a href="postconf.5.html#mydestination">mydestination</a> and <a href="postconf.5.html#relay_domains">relay_domains</a>, as well as lookup table search
keys. </p>

<li> <p> Milters, content filters, policy servers and logfile
analysis tools need to be able to handle both the ASCII and UTF-8
forms of Internationalized domain names. </p>

</ul>

<h2> <a name="compatibility">Compatibility with pre-SMTPUTF8
environments</a> </h2>

<h3> Mailing lists with UTF-8 and non-UTF-8 subscribers </h3>

<p> 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 <a href="https://tools.ietf.org/html/rfc2047">RFC 2047</a> encoding to
satisfy that last condition. </p>

<h3> Pre-existing non-ASCII email flows </h3>

<p> With "<a href="postconf.5.html#smtputf8_enable">smtputf8_enable</a> = 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. </p>

<h3> Rejecting non-UTF8 addresses </h3>

<p> With "<a href="postconf.5.html#smtputf8_enable">smtputf8_enable</a> = 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 <a href="https://tools.ietf.org/html/rfc2047">RFC 2047</a> encodings such as "=?ISO-8859-1?Q?text?=",
because those use only characters from the ASCII characterset. </p>

<h3> Rejecting non-ASCII addresses in non-SMTPUTF8 transactions </h3>

<p> Setting "<a href="postconf.5.html#strict_smtputf8">strict_smtputf8</a> = yes" in addition to "<a href="postconf.5.html#smtputf8_enable">smtputf8_enable</a>
= 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. </p>

<h2> <a name="idna2003">Compatibility with IDNA2003</a> </h2>

<p> Postfix &ge; 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 "<a href="postconf.5.html#enable_idna2003_compatibility">enable_idna2003_compatibility</a>
= yes" to get the historical behavior. </p>

<p> This affects the conversion of domain names that contain for
example the German sz (ß) and the Greek zeta (ς). See
<a href="http://unicode.org/cldr/utility/idna.jsp">http://unicode.org/cldr/utility/idna.jsp</a> for more examples. </p>

<h2> <a name="credits">Credits</a> </h2>

<ul>

<li> <p> May 15, 2014: Arnt Gulbrandsen posted his patch for Unicode
email support.  This work was sponsored by CNNIC. </p>

<li> <p> July 15, 2014: Wietse integrated Arnt Gulbrandsen's code
and released Postfix with SMTPUTF8 support. </p>

<li> <p> January 2015: Wietse added UTF-8 support for casefolding
in Postfix lookup tables and caseless string comparison in Postfix
list-based features. </p>

</ul>

</body>

</html>