Dr.Who
← blog

How to read a TLS-RPT (SMTP TLS) report

· tls-rpt · smtp · tls · email-security · mta-sts

tls-rptsmtptlsemail-securitymta-sts

A TLS-RPT report is a JSON document that a sending provider emails you once a day, summarizing how many SMTP sessions to your domain succeeded or failed over TLS and why. You opt in by publishing a _smtp._tls.<domain> TXT record (RFC 8460) with a rua=mailto: address. To read a report, look at the summary counts first to see if anything failed at all, then read failure-details[] to identify the exact failure type and the receiving host involved.

Requesting reports: the TLS-RPT record

Reports only arrive if you ask for them. Publish this TXT record:

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

Senders that support TLS-RPT (most large providers do) will then send a JSON aggregate report, usually gzip-compressed, to that address once per reporting period.

The JSON shape

A report has a small header, then a policies[] array. Each entry pairs the policy that was applied (your MTA-STS or DANE policy) with a summary and, when relevant, a list of failure-details:

{
  "organization-name": "Example Sender Inc.",
  "date-range": {
    "start-datetime": "2026-06-21T00:00:00Z",
    "end-datetime": "2026-06-21T23:59:59Z"
  },
  "policies": [
    {
      "policy": { "policy-type": "sts", "policy-domain": "example.com" },
      "summary": {
        "total-successful-session-count": 4821,
        "total-failure-session-count": 3
      },
      "failure-details": [
        {
          "result-type": "certificate-expired",
          "receiving-mx-hostname": "mail.example.com",
          "failed-session-count": 3
        }
      ]
    }
  ]
}

Read summary first. total-successful-session-count is sessions that negotiated TLS as your policy required; total-failure-session-count is sessions that did not. If failures are zero, you are done — TLS is being applied cleanly across that sender's traffic.

Acting on failure-details result-types

When there are failures, each failure-details[] entry names a result-type, a receiving-mx-hostname, and a count. The common types and what each means:

  • certificate-expired — the certificate on the named MX host is past its validity date. Renew it. This is the most frequent and most actionable failure.
  • starttls-not-supported — the receiving MX advertised SMTP but did not offer STARTTLS. Enable TLS on that MX, or fix a downgrade-stripping middlebox in front of it.
  • validation-failure — the certificate did not validate against the policy: wrong hostname, untrusted chain, or self-signed. Reissue with a trusted CA and a SAN matching the MX hostname.
  • certificate-host-mismatch — the certificate is valid but does not cover the MX name the sender connected to. Add the hostname to the certificate's SANs.
  • dane-required — DANE was expected (a TLSA record exists) but the TLS connection did not satisfy it. Check that the TLSA record matches the certificate currently served.

The receiving-mx-hostname tells you which of your MX servers to fix, so even a small failure count points you straight at the broken host.

Check your TLS-RPT record →

Further reading