Skip to content
Koltrix
FeaturesPricingCompareCustomersDocsBlog
Sign inStart 7-day free trialOpen app
Guides

MTA-STS from scratch: DNS record, policy file, testing

Set up MTA-STS for inbound mail: the _mta-sts TXT record, the HTTPS policy file, testing mode, then enforce, plus the mistakes that break delivery.

Koltrix Team5 min read
Fiber optic cables connected to a network switch
Photo by Kirill Sh on Unsplash
On this page(11 sections)
  1. What MTA-STS protects against
  2. Prerequisites
  3. Step 1: write the policy file
  4. Step 2: host it at the well-known URL
  5. Step 3: publish the DNS record
  6. Step 4: add TLS reporting
  7. Step 5: run in testing mode
  8. Step 6: switch to enforce
  9. Mistakes that break delivery
  10. Keeping it healthy
  11. Key takeaways

SMTP encryption between mail servers is opportunistic by default: if a connection cannot be encrypted, mail is usually delivered in plain text anyway. MTA-STS lets you tell sending servers that your domain always supports TLS, so they refuse to deliver over a downgraded or impersonated connection.

Setting it up takes one DNS record, one small text file and a web server.

What MTA-STS protects against

When a server sends mail to your domain, it looks up your MX records and connects to one of them. If your server offers STARTTLS, the connection is upgraded to TLS. But two attacks remain possible:

  • Downgrade. An attacker on the network path strips the STARTTLS offer from your server's greeting, so the sender delivers in plain text.
  • Impersonation. An attacker who can tamper with DNS answers or routing sends the sender to their own server, which presents some certificate the sender does not validate.

Most senders do not validate certificates for opportunistic TLS, because historically too many mail servers had self-signed or mismatched certificates. MTA-STS, defined in RFC 8461, gives a domain a way to opt in to strict behavior: "connect only to these MX hosts, require TLS, and require a valid certificate matching the hostname."

MTA-STS protects mail sent to your domain. It is a policy you publish for inbound delivery. Whether your own outbound mail is protected depends on the recipient domains publishing policies.

Prerequisites

Before you start, confirm:

  1. Every MX host supports STARTTLS with TLS 1.2 or later.
  2. Every MX host presents a valid certificate from a publicly trusted certificate authority, whose name matches the MX hostname. If your MX is mx1.example.com, the certificate must cover mx1.example.com.
  3. You can host a file over HTTPS at mta-sts.<your-domain> with a valid certificate.

If you use a hosted mailbox provider, the first two are usually already true for their MX hosts. Check their documentation for the MX hostnames to list in your policy.

Step 1: write the policy file

The policy is a plain-text file with a handful of key-value lines:

version: STSv1
mode: testing
mx: mx1.example.com
mx: mx2.example.com
max_age: 86400
  • version must be STSv1.
  • mode is testing, enforce or none. Start with testing.
  • mx lists each permitted MX hostname. Wildcards such as *.mail.example.net are allowed for the leftmost label, which helps with providers that use many MX hosts under one domain.
  • max_age is how long, in seconds, senders may cache the policy. RFC 8461 caps it at 31557600 (about a year). Start short, for example one day, while testing.

Lines end with CRLF or LF; the file is served as text/plain.

Step 2: host it at the well-known URL

Senders fetch the policy from exactly this location:

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

Requirements:

  • The host is literally mta-sts. followed by your domain.
  • HTTPS with a valid, publicly trusted certificate for mta-sts.example.com.
  • No redirects. RFC 8461 says senders must not follow HTTP redirects when fetching the policy.
  • A 200 response with the policy as the body.

Any static hosting works: a small virtual host on an existing web server, an object storage bucket behind a CDN with a custom domain, or a static site platform. Create the DNS record for mta-sts.example.com pointing at it and provision the certificate.

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

Step 3: publish the DNS record

The TXT record at _mta-sts tells senders that a policy exists and which version it is:

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

The id is an opaque string, up to 32 alphanumeric characters, that you change every time you change the policy file. Senders that have cached your policy compare IDs; a new ID tells them to fetch the file again. A timestamp makes a convenient ID.

Step 4: add TLS reporting

Publish a TLS-RPT record so receivers send you reports about failed TLS connections. Without it, you will be running testing mode blind.

_smtp._tls.example.com. TXT "v=TLSRPTv1; rua=mailto:[email protected]"

Reports arrive daily as JSON from senders that support TLS-RPT, summarizing successful and failed sessions and the policy they applied.

Step 5: run in testing mode

In testing mode, senders that support MTA-STS evaluate your policy and report failures through TLS-RPT, but still deliver mail even when the policy check fails. That lets you find problems without losing messages.

Watch reports for at least two weeks. Look for:

  • Failures on a specific MX host, often an expired or mismatched certificate.
  • MX hostnames receiving mail that are missing from your mx: lines.
  • Policy fetch errors, which usually mean a certificate or redirect problem on the policy host.

Step 6: switch to enforce

Once reports are clean, update the policy file:

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

Then change the id in the DNS record. In enforce mode, senders that support MTA-STS will refuse to deliver to an MX host that is not listed, does not offer TLS or presents an invalid certificate. Mail is queued and retried rather than delivered insecurely.

Raise max_age gradually once you are confident, from a day to a week and eventually to several weeks or more. A longer cache means a DNS-level attacker who blocks policy refresh cannot easily make senders forget your policy.

Mistakes that break delivery

Mistake Effect in enforce mode
Changing MX hosts without updating mx: lines Senders refuse the new hosts
Letting an MX certificate expire Mail to that host is deferred
Certificate name does not match MX hostname Mail to that host is deferred
Policy host redirects to www Senders cannot fetch the policy
Forgetting to change id after edits Senders keep the old cached policy

The first one deserves emphasis. When you migrate mailbox providers, update the policy to include both old and new MX hosts before changing MX records, or drop back to testing for the cutover.

Keeping it healthy

  • Monitor certificate expiry for every MX host and for mta-sts.example.com.
  • Keep the policy file in version control along with your DNS.
  • Read TLS-RPT summaries weekly, or alert on failure counts.
  • Document the procedure for MX changes so the policy is updated first.

Key takeaways

  • MTA-STS makes supporting senders require valid TLS when delivering to your domain, blocking downgrade and impersonation.
  • You need a policy file at https://mta-sts.<domain>/.well-known/mta-sts.txt, a _mta-sts TXT record with an id, and valid certificates on every MX host.
  • Start in testing mode with TLS-RPT enabled, then move to enforce once reports are clean.
  • Change the id every time the policy changes, and update mx: lines before any MX migration.

Start with Koltrix

Your domain, one inbox, and an API that sends.

A team inbox where AI sorts and drafts (nothing is sent without your click), plus the transactional API and SMTP relay your product sends with. 7 days free, no card.

Start your 7-day free trialOpen KoltrixRead the docs
SharePost on XLinkedIn

Keep reading

More in Guides →