What is the 'policy_text_version' in MTA-STS?

Suped DMARC monitor

Free forever, no credit card required

Get started for free

Trusted by teams securing millions of inboxes

Before we dive into the specifics of policy_text_version, it's important to understand where it fits. MTA-STS (Mail Transfer Agent Strict Transport Security) policies are defined in a simple text file. This file is hosted on your web server at a specific URL, which allows mail servers to fetch and read your policy.

This policy file contains a list of key-value pairs that instruct receiving mail servers on how to handle email for your domain. The primary keys are:

• version: The protocol version, which must be STSv1.
• mode: The policy mode, which can be testing, enforce, or none.
• mx: A list of your domain's valid mail exchange (MX) server hostnames.
• max_age: The maximum time in seconds that a receiving server should cache the policy.

Now, let's talk about the policy_text_version. This isn't a key inside the policy file itself. Instead, it's a value within your MTA-STS DNS TXT record. The full DNS record looks something like this: v=STSv1; id=2024010101;. In this example, 2024010101 is the policy's ID, which I'll call the text version.

The policy_text_version (or the id field in the DNS record) serves one critical purpose: it acts as a change indicator. Receiving mail servers cache your MTA-STS policy to reduce the overhead of fetching it for every single email. They use the max_age value to know how long to keep the cached version.

When a receiving server checks your domain's DNS, it compares the id value in the TXT record with the version it has stored in its cache. If the id in the DNS is newer or different, the server knows that your policy has changed. This prompts it to discard the old, cached policy and fetch the new one from your web server. If the id is the same, it continues using the cached version until it expires.

The value itself can be any string of 1 to 32 alphanumeric characters. There's no strict format, but a common and highly effective convention is to use a timestamp or a date-based sequence number. For example, 2024052101 could represent the first revision on May 21st, 2024.

When you update your MTA-STS policy, such as changing the mode from testing to enforce, you must remember to also update the id in your DNS record. If you forget this step, servers with a cached policy will not know a change has occurred and will not fetch your new, enforced policy until their cache expires. This could delay the protection offered by the enforce mode.

In short, the policy_text_version is the trigger that tells the email world you've updated your security rules. It’s a simple but vital part of the MTA-STS mechanism that ensures your policies are propagated efficiently and reliably.