How to set up MTA-STS and TLS-RPT

The problem MTA-STS solves

When one mail server delivers to another, it asks whether the receiver supports encryption using a command called STARTTLS. If the answer is yes, the connection is upgraded. This is opportunistic: if the offer of STARTTLS is missing, the sender delivers in plain text, and most senders do not check that the certificate they are shown belongs to the right server.

Someone positioned between the two servers can therefore remove the STARTTLS offer, or answer for the mail server with a certificate of their own, and read or alter the mail. MTA-STS, defined in RFC 8461, closes this by letting the receiving domain publish a policy that says: mail for this domain must be delivered over TLS, to one of these named servers, with a certificate that is valid for that name. A sender that supports MTA-STS refuses to deliver otherwise.

The two parts of a policy

MTA-STS is unusual in that DNS alone is not enough. The policy lives in a text file served over HTTPS, and a DNS record signals that the file exists and when it has changed. The design is deliberate: fetching the policy over HTTPS means it is authenticated by a web certificate, so the mechanism does not depend on DNSSEC.

A sender first looks up the TXT record at _mta-sts under your domain. If it finds one, it fetches the policy file from a fixed address on the mta-sts host name of your domain and caches it. On later deliveries it only checks whether the id in the TXT record has changed.

_mta-sts.example.com.  TXT  "v=STSv1; id=20261110120000"

https://mta-sts.example.com/.well-known/mta-sts.txt

version: STSv1
mode: testing
mx: mx1.example.com
mx: mx2.example.com
max_age: 604800

What each line of the policy means

The version line is always STSv1. The mode is one of three values. In testing, senders deliver as usual and report failures if you have asked for reports. In enforce, senders must not deliver to a server that fails the checks. In none, senders are told that the domain no longer has a policy, which is how a policy is withdrawn cleanly.

Each mx line names a mail server that is allowed to receive mail for the domain. A line may start with a wildcard label, so that *.mail.example.com matches any single label in that position. The max_age line is the number of seconds a sender may cache the policy, up to about one year. One week is a sensible value while you gain confidence; longer values give more protection, because an attacker who blocks the policy file gains nothing until the cache expires.

Before you start

The policy describes your mail servers, so it has to be written from what they actually are. Three things need to be true before any policy can be enforced.

1. List the domain's MX records. These are the names that go into the mx lines.
2. Confirm that every MX host supports STARTTLS with TLS 1.2 or later.
3. Confirm that every MX host presents a certificate that is valid, unexpired, issued by a publicly trusted authority and covers the MX host name itself.
4. Decide where the policy file will be hosted. Any HTTPS host works, including a static hosting service.

dig example.com MX +short
openssl s_client -starttls smtp -connect mx1.example.com:25 -servername mx1.example.com </dev/null 2>/dev/null \
  | openssl x509 -noout -subject -enddate -ext subjectAltName

If you use a hosted mailbox provider

With a hosted provider you do not control the mail servers, and you do not need to. The provider's MX hosts already support TLS with valid certificates. Your part is to publish a policy that names them correctly, which means the mx lines must match the MX records the provider told you to use, usually with a wildcard for the provider's domain. The provider's documentation gives the exact pattern.

You still have to host the policy file yourself, on the mta-sts name of your own domain. The provider's mail servers do not serve it for you unless the provider offers that as a feature.

Publishing, in the right order

Order matters because a TXT record that points to a missing or unreachable file makes senders treat the policy as absent, and repeated fetch failures can leave a stale policy in their caches.

1. Create the DNS record for the mta-sts host name, pointing at wherever the file will be served.
2. Serve the policy file at /.well-known/mta-sts.txt over HTTPS, with a valid certificate for the mta-sts host name and a content type of text/plain. It must be served directly, not through a redirect.
3. Fetch the file yourself and confirm the content.
4. Publish the TLS-RPT record so that reports start as soon as the policy is seen.
5. Publish the _mta-sts TXT record with an id.
6. Read everything back with a checker that fetches the file the way a sender would.

curl -sS -i https://mta-sts.example.com/.well-known/mta-sts.txt

TLS-RPT: how you find out what is failing

TLS-RPT, defined in RFC 8460, is a single TXT record that gives an address for reports. Sending organisations that support it send one report a day summarising their deliveries to your domain: how many sessions negotiated TLS successfully and how many failed, grouped by the kind of failure and the mail server involved.

Publish it before or together with MTA-STS. In testing mode it is the only way to learn that a policy would have blocked mail. Reports are JSON, usually compressed, and can be sent to a mailbox or to an HTTPS endpoint.

_smtp._tls.example.com.  TXT  "v=TLSRPTv1; rua=mailto:tls-reports@example.com"

Reading a TLS report

Each report names the policy the sender applied and gives a count of successful and failed sessions. Failures are labelled with a result type. The ones seen most often are certificate-expired, certificate-host-mismatch, certificate-not-trusted, starttls-not-supported and validation-failure. For MTA-STS in particular, sts-policy-fetch-error means the sender could not retrieve your file, sts-policy-invalid means it could not be parsed, and sts-webpki-invalid means the certificate on the mta-sts host was not acceptable.

A small, steady number of failures from one sender is often that sender's problem. Failures that name one of your MX hosts, from several senders, are yours to fix.

Moving from testing to enforce

Stay in testing for at least two weeks, long enough to receive reports from the large mailbox providers and to see any mail server that is used only occasionally, such as a backup MX. Move to enforce when the reports show no failures attributable to your own servers.

1. Edit the policy file: change mode from testing to enforce.
2. Change the id in the TXT record. Without a new id, senders keep the cached testing policy until it expires.
3. Watch the TLS reports closely for the following week.
4. Once stable, raise max_age to a month or more.

Changing mail providers later

The most common MTA-STS outage happens months after setup, when the domain's MX records are changed and the policy is forgotten. Senders holding the cached policy see new MX hosts that are not on the list and, in enforce mode, refuse to deliver. Mail is queued and eventually returned.

Before changing MX records, add the new hosts to the policy file alongside the old ones and change the id. Wait for at least the max_age of the previous policy so that every sender has the new list. Then change the MX records, and remove the old hosts from the policy afterwards. If the timing cannot be managed, switch the policy to testing first.

Mistakes to avoid

Most failed deployments come from a short list of errors.

1. Editing the policy file without changing the id.
2. Listing the domain name in the mx lines instead of the MX host names.
3. Serving the file with an expired certificate, or one that does not cover the mta-sts name.
4. Serving the file behind a redirect, which senders must not follow.
5. Going straight to enforce without a period in testing with TLS-RPT.
6. Forgetting a backup MX host that is rarely used.
7. Deleting the TXT record to switch MTA-STS off, instead of publishing mode none first. Senders keep enforcing the cached policy until max_age runs out.

What MTA-STS does not do

MTA-STS protects mail in transit to your domain from senders that support it. It does not encrypt mail at rest, does not protect mail you send to others unless they publish their own policy, and has no effect on senders that do not implement it. It does not authenticate who sent a message; that is the job of SPF, DKIM and DMARC. DANE offers a comparable protection based on DNSSEC and can be used alongside it. The CloudSpex MTA-STS Checker reads the TXT record, fetches the policy file and compares it with the domain's MX records, and reports each step separately so that a failure can be located.