How to set up MTA-STS

Setting up MTA-STS requires two things:

• Hosting the policy in a text file on an HTTPS-enabled subdomain.
• Creating a TXT record for MTA-STS discovery.

Before starting the setup, make sure you’ve also enabled TLS reporting so that you’re notified of delivery issues.

Composing the policy

Before starting, you should identify the MX records of your email-receiving domain (the policy domain).

For example, if you receive email messages on the domain example.com (e.g. hello@example.com), that’s the policy domain.

Find out which MX records you’re using (this depends on the DNS provider you’re using), or, alternatively, query them from the command line:

dig example.com MX +short

Then, create a text file named mta-sts.txt and paste the following content:

version: STSv1
mode: testing
mx: YOUR_MX_HERE
max_age: 1209600

Make sure to replace YOUR_MX_HERE with the first of the MX hostnames you identified earlier.

If you have multiple MX servers, add more “mx” lines, like so:

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

This policy uses the testing mode, which is the best way to start: after reviewing that there are no delivery issues through TLS reports, you can move to enforce mode.

Hosting the policy

The MTA-STS policy file must be served via HTTPS on the mta-sts subdomain of your policy domain. This is called the policy host.

For example, if your domain is example.com, you have to set up the following HTTPS-enabled subdomain:

https://mta-sts.example.com

The policy file must be served as a text file from the .well-known/mta-sts.txt, for example:

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

The file must be served with a Content-Type response header of text/plain and a status code of 200 (OK). Redirects (3xx status codes) are not supported.

Additionally, HTTP caching must not be used and the policy must be served quickly enough to not incur into timeouts.

Finally, keep in mind that the HTTPS certificate must be chained to a publicly trusted Certificate Authority, which means you cannot use self-signed certificates.

Creating the TXT record

Finally, to signal that MTA-STS is available on your domain you have to create a TXT record on the _mta-sts subdomain.

The value of the record should be in the following format:

v=STSv1; id=123456789;

(The semicolon at the end is optional.)

The important part is the id: it can be any alphanumeric string, and you’ll need to change it every time you update the policy file.

Often, the id is a UNIX timestamp in seconds, like this:

v=STSv1; id=1748081191;

Or a more human-readable timestamp like:

v=STSv1; id=20250503T115500Z;

It can in theory also be a random string though, there’s no practical difference.

Use a relatively low TTL (like 3600, one hour) so that updates to the policy are picked up quickly.

Here’s what the record would look like on the domain example.com:

Updating the policy

When you want to update the policy (e.g. when the MX servers change), you should:

• Update the mta-sts.txt file with the updated information.
• Update the TXT record by changing the id value.

The order of the steps is very important: if you apply the changes in the opposite order, a sending server may see the new discovery ID but fetch the old policy, potentially causing email rejections.

Removing MTA-STS

When you want to disable MTA-STS, do not remove the TXT record and policy host immediately. Sending servers may still be enforcing a cached policy and must be given time to discover that MTA-STS is being removed.

To remove a manually hosted policy safely:

• Publish a new policy with mode: none and a short max_age, such as one day.
• Update the discovery TXT record with a new ID.
• Keep serving the none policy until every previously published policy has expired, including older policies that used a longer max age.
• Remove the discovery TXT record and policy host after the retirement period ends.

See Removing MTA-STS for more information about why this process is necessary.