How to Read a TLS-RPT Report: Interpreting the JSON and Fixing TLS Errors
You published a TLS-RPT record, and now a steady stream of JSON files lands in your inbox or your reporting tool every morning. That is the system working as intended. The harder part comes next: a TLS-RPT report is dense, machine-oriented and easy to ignore until a delivery problem forces you to open one. This guide walks through the structure of a report, explains what each field is telling you, and turns the cryptic result-type values into concrete actions.
If you have not enabled reporting yet, start with TLS-RPT and come back here once data is flowing. This article assumes the record is live and the reports are arriving.
What a TLS-RPT report is for
TL;DR: A TLS-RPT report is a daily JSON summary that sending providers deliver to the address in your _smtp._tls DNS record. It tells you how many email sessions to your domain were encrypted successfully and, for the rest, gives a result-type that names the exact failure. Reading these reports is how you find a broken certificate, a stripped STARTTLS or a misconfigured MX before it turns into bounced mail. TLS-RPT is the visibility layer for MTA-STS and DANE.
TLS-RPT, defined in RFC 8460, does not enforce anything. Its only job is reporting. Every day, each participating provider that sent mail to your domain bundles the outcome of those connections into a single JSON document and delivers it to the endpoint you published. The value is simple but easy to underestimate: without these reports you are running encrypted transport blind, with no way to know whether a partner silently fell back to plain text or hit an expired certificate on one of your MX hosts.
The structure of a TLS-RPT report
Every report follows the same shape. Once you recognise the four building blocks, any report from any provider becomes readable.
1. The envelope. At the top you find organization-name, a date-range with a start and end timestamp, and a contact-info and report-id. This tells you who is reporting and for which 24 hour window.
2. The policy block. For each policy that the sender evaluated, the report records the policy-type (for example sts for MTA-STS or tlsa for DANE), the policy string itself and the mx-host entries it applied to. This is how you confirm that the remote side actually saw your MTA-STS policy or your TLSA record.
3. The summary. Two counters matter most here: total-successful-session-count and total-failure-session-count. A healthy domain shows a high success count and a zero or near-zero failure count. A sudden jump in failures is your signal to read further.
4. The failure-details. This is where the diagnosis happens. For every kind of failure, the report lists a result-type, the sending-mta-ip, the receiving-mx-hostname, the receiving-ip and a failed-session-count. The result-type is the key field: it names the exact reason the encrypted session could not be established.
A practical reading habit: skip straight to the summary, and only dig into failure-details when the failure count is non-zero. That keeps daily review to a few seconds per report.
Mapping result-types to cause and fix
The result-type is a fixed vocabulary, so once you know what each value means you can act without guesswork. The table below maps the most common values to their likely cause and the side that owns the fix.
| result-type | What it means | Likely cause and fix |
|---|
| starttls-not-supported | The receiving server did not offer STARTTLS | An MX with STARTTLS disabled, or a relay that strips the capability. Enable STARTTLS on every MX and remove any downgrading hop. Owned by the receiver. |
| certificate-expired | The TLS certificate had passed its validity date | A lapsed certificate on a receiving MX. Renew it and automate renewal so it never expires again. Owned by the receiver. |
| certificate-host-mismatch | The certificate name did not cover the MX hostname | The Subject Alternative Name list is missing an MX name. Reissue or extend the certificate to cover every MX hostname in DNS. Owned by the receiver. |
| tlsa-invalid | A DANE TLSA record did not match the served certificate | A rotated certificate without an updated TLSA record. Republish the matching TLSA hash whenever the certificate changes. Owned by the receiver. |
| dnssec-invalid | DNSSEC validation of the TLSA lookup failed | A broken or unsigned DNSSEC chain. Repair signing on the zone so DANE lookups validate. Owned by the receiver. |
| validation-failure | A generic TLS negotiation or trust failure | A weak protocol version, an untrusted chain or a handshake error. Update the TLS stack and serve a complete, trusted certificate chain. Owned by the receiver. |
Two patterns are worth internalising. First, almost every failure is owned by the receiving side, which means a failure against your own domain points at your MX configuration, not the sender. Second, the certificate-related types (certificate-expired, certificate-host-mismatch) and the DANE types (tlsa-invalid, dnssec-invalid) tend to appear in clusters right after a certificate rotation, so a spike the morning after a renewal is a strong hint that an automation step was missed.
A practical note on Microsoft 365
There is one operational detail that trips up many teams. Microsoft 365 delivers a TLS-RPT report to only the first rua endpoint listed in your DNS record. If you publish more than one destination, for example a mailto address and an https collector, Exchange Online uses the first entry and ignores the others.
The consequence is subtle: a second tool can look broken when it is simply never receiving Microsoft 365 data. The fix is to consolidate reporting onto a single receiver, or to make sure the receiver you actually monitor is listed first. This is exactly the kind of gap that an aggregating service removes, because there is then only ever one endpoint to publish.
How Conbool MailGuard reads the reports for you
Manual review works for a single domain on a quiet week. It does not scale to a fleet of domains, several providers and the inevitable certificate rotation that lands at the wrong moment. Conbool MailGuard takes the reports off your plate.
MailGuard hosts a single reporting endpoint, so you publish one rua value and the Microsoft 365 first-endpoint limitation stops mattering. Incoming reports from every provider are parsed, normalised and aggregated across all your domains, so you see a trend rather than a pile of raw JSON. Failures are grouped by result-type and by receiving MX, which means a certificate-expired cluster surfaces as a single clear finding with the affected host named, instead of a count buried in a file you would have to open by hand. The day-to-day question shifts from what does this JSON mean to which host needs attention.
You can check the current transport posture of any domain first with the free transport security check, then see the managed reporting on the TLS-RPT page.
How this ties to MTA-STS and DANE
TLS-RPT is not a standalone control. It is the feedback loop for the two standards that actually enforce encrypted transport. MTA-STS tells sending servers to require TLS, but it gives you no insight into whether that requirement is being met in the field. TLS-RPT closes that loop: it is what makes the move from MTA-STS testing to enforce a decision backed by evidence rather than a leap of faith. For a closer comparison of the two enforcement approaches, see MTA-STS or DANE.
The same applies to DANE. A TLSA record binds your certificate through DNSSEC, but a rotated certificate with a stale TLSA hash will fail silently for senders that validate it. The tlsa-invalid and dnssec-invalid result-types are your early warning that the binding broke. Read together, MTA-STS, DANE and TLS-RPT form a complete loop of enforce, bind and verify.
Frequently asked questions
What does a TLS-RPT report contain?
A TLS-RPT report is a JSON document a sending provider delivers once per day. It names the reporting organisation and the date range, then describes the policy it tried to apply for your domain, a summary with the count of successful and failed sessions, and for any failures a list of failure-details with a machine-readable result-type, the sending and receiving IP addresses and the number of affected connections.
What does the result-type starttls-not-supported mean?
It means the sending server connected to your mail server but STARTTLS was not offered or was rejected, so no encrypted session could be established. The usual causes are a receiving MX with STARTTLS disabled, a relay or appliance in front of the mail server that strips the capability, or an attacker downgrading the connection. Check that every MX host advertises STARTTLS and that no intermediate hop removes it.
What do certificate-expired and certificate-host-mismatch mean?
Certificate-expired means the TLS certificate on the receiving MX passed its validity date and was rejected. Certificate-host-mismatch means the name in the certificate did not cover the MX hostname the sender connected to. Both are fixed on the receiving side: renew the certificate before it lapses, or issue it so the Subject Alternative Name list includes every MX hostname in your DNS.
Why are some reports missing under Microsoft 365?
Microsoft 365 sends a TLS-RPT report only to the first rua endpoint in your DNS record. If you publish several mailto or https endpoints, Exchange Online uses the first one and ignores the rest, so a second tool can appear to receive nothing. Consolidate reporting on a single receiver, or place that receiver first in the rua list.
MTA-STS and DANE enforce encrypted transport, while TLS-RPT provides the visibility into whether that enforcement works. The reports show how many sessions matched your policy and why others failed, which lets you move an MTA-STS policy from testing to enforce with evidence and confirm that a DANE TLSA record validates in the field.
Conclusion
A TLS-RPT report stops being intimidating the moment you know its four parts and the fixed vocabulary of result-type values. Read the summary first, open failure-details only when the count is non-zero, and treat each result-type as a pointer to a specific host and a specific fix. That habit turns daily JSON into a reliable early warning for expired certificates, stripped STARTTLS and broken DANE bindings, well before any of them reaches your delivery.
The next step is yours: run the free transport security check on your domain, then let Conbool MailGuard collect and analyse the reports so you act on findings instead of parsing JSON.
Further reading:
