Setting up TLS-RPT

There is a category of mail failure you cannot see from your own server: mail that never arrives because the sender refused to deliver it. Their server tried, your TLS was broken, their policy said do not fall back to plain text, and they gave up. No bounce reaches you, because nothing of yours was involved. Your logs show a connection that closed.

TLS-RPT is how you find out. It costs one DNS record.

Which direction this runs, because it is easy to get backwards

You publish TLS-RPT for your own domain, and other people’s servers report to you about reaching you. RFC 8460 calls your domain the Policy Domain — “typically the same as the envelope recipient domain”.

So the failures in your reports are in your receiving setup. In a report you receive, policy-domain is your domain, receiving-mx-hostname and receiving-ip are your mail server, and sending-mta-ip belongs to whoever sent the report. An expired certificate in your report is your certificate.

This is worth stating plainly because getting it round the wrong way sends you to email a third party about a problem sitting on your own server, while inbound mail keeps failing.

The record

A TXT record at _smtp._tls under your domain, naming where reports should go:

_smtp._tls.example.com.  TXT  "v=TLSRPTv1; rua=mailto:tlsrpt@example.com"

That is the whole thing. Two details are worth getting right:

• The mailbox should be a dedicated one, not a person’s inbox. You will receive one report per reporting provider per day, each a gzipped JSON attachment, indefinitely. In a human inbox they become noise within a week and get filtered, which defeats the point.
• rua= can also be an HTTPS endpoint — rua=https://example.com/tlsrpt — and reporters will POST the report rather than mail it. Useful if you would rather ingest them programmatically, though mail is what most people start with.

You can list more than one destination, separated by commas. If reports should go to a domain you do not control, that domain has to authorise it — the same external-destination check DMARC uses.

What you get

Within a day or two, mail from the large providers that implement RFC 8460 — Google and Microsoft most visibly. Each report covers a 24-hour window and looks like this once decompressed:

{
  "organization-name": "Google Inc.",
  "date-range": { "start-datetime": "...", "end-datetime": "..." },
  "policies": [{
    "policy": { "policy-type": "sts", "policy-domain": "example.com" },
    "summary": {
      "total-successful-session-count": 4126,
      "total-failure-session-count": 17
    },
    "failure-details": [{
      "result-type": "certificate-expired",
      "receiving-mx-hostname": "mail.example.com",
      "failed-session-count": 12
    }]
  }]
}

The summary counts are the part to watch over time. A handful of failures in thousands of sessions is normal background noise — transient network problems, odd senders. A number that climbs, or a result type that appears where there was none, is the signal.

Reading them without going mad

The reports are gzipped JSON, which is the entire reason they go unread. Most mail clients will not open a .json.gz attachment, so they accumulate in a folder nobody looks at, and the failure they were meant to warn you about happens anyway.

The analyzer on this site takes them as they arrive — drag several days in at once and they merge. It decompresses and parses in your browser, so the file is not uploaded anywhere, which matters given a report is a list of your MX hosts, their addresses and who has been writing to you.

What to do with a failure

Two categories, and the difference decides how urgently you act:

• Certificate and negotiation failures — certificate-expired, certificate-host-mismatch, starttls-not-supported. Senders enforcing a policy are not delivering to you at all. Treat these as outages.
• Policy failures — sts-policy-fetch-error, sts-webpki-invalid. Mail is still arriving, but unencrypted, because your policy is not being applied. Less urgent, and quietly worse than it looks.

TLS-RPT on its own is still worth it

You do not need MTA-STS or DANE to benefit. Publish the TLS-RPT record by itself and you still get told when your certificate expires or your MX stops offering STARTTLS — you are simply reading reports about connections that mostly succeeded.

That is the sensible order, in fact: TLS-RPT first, watch for a couple of weeks to confirm your TLS is healthy and to see who actually sends you mail, and only then publish an MTA-STS policy. Enforcing a policy before you can see the failures it causes is how inbound mail disappears with nobody noticing.