TLS-RPT reports
decoded.
Paste the JSON content of a TLS-RPT aggregate report (the gzipped file
senders email to your rua= address). We parse it client-side,
extract the TLS connection outcomes, group failures by type, and tell you
what action each finding suggests.
# Paste a report or load the sample to start.
From XML-equivalent JSON to action items.
Visibility before enforcement
MTA-STS in testing mode is safe; senders report failures
but still deliver. To safely promote to enforce, you need
to know which senders are failing and why.
TLS-RPT reports answer that question. The reports arrive as JSON
attachments to your rua= address; reading them by hand
is painful. This tool surfaces the answers.
Connection outcomes
- Total successful sessions: clean TLS connections from this sender during the report period
- Total failure sessions: connection attempts that failed for any TLS-related reason
- Failure rate: failed / total, grouped by failure category
- Failure types: STARTTLS not supported, certificate validation failures, MX policy mismatches, STS policy fetch errors
- Sending IPs: which IPs from this sender produced the failures (useful when one of their MTAs is misconfigured)
Each finding has a fix
Cert validation failures usually mean your MX cert is expired, self-signed, or the hostname doesn't match. Renew the cert.
STARTTLS not supported means the sender's MTA isn't offering TLS. Their problem, not yours, but worth noting if it is a sender you care about.
MX policy mismatch means the sender connected to an MX that isn't in your MTA-STS policy file. Either add it to the policy or investigate why mail is going to that MX.
What this tool doesn't do
This is a parser, not a collector. It expects you to already have the JSON content in front of you. To collect TLS-RPT reports automatically, you need a backend that ingests the rua= mailbox and unpacks the gzipped attachments.
For production use, parsedmarc is the open-source
standard; it parses both DMARC and TLS-RPT reports into a queryable
database. We deploy it for managed customers as part of authentication
setup.
Want this running automatically against your rua= mailbox?
We deploy parsedmarc + a custom dashboard for any customer running MTA-STS or DMARC at scale. Reports parsed, indexed, alerted on anomalies. Open a Telegram conversation to discuss your setup.
The reports are dense JSON; here's what to look at first.
TLS-RPT (TLS Reporting) reports come in as JSON files
delivered to the address you publish in your TLS-RPT
DNS record (typically via the rua=mailto:
tag). Each report covers a 24-hour reporting window from
a specific sender, and contains aggregate counts of
successful and failed TLS connections to your inbound
MX hosts. The parser shows you the structured breakdown;
here's what to look at first.
Total session counts: success vs failure
The first signal is the ratio of successful TLS sessions to failures. A healthy domain might see 99%+ success rates; legitimate failure rates above 1-2% suggest something is wrong with your inbound TLS configuration. Note that "failures" includes both hard failures (TLS rejected) and policy failures (TLS succeeded but didn't meet MTA-STS or DANE requirements).
Failure reason codes
When failures appear, the report includes failure reason
codes per failure batch.
starttls-not-supported means the receiving
MTA didn't advertise STARTTLS at all (your MX is
rejecting TLS or not configured to support it).
certificate-expired is self-explanatory.
certificate-not-trusted means the cert chain
didn't validate. certificate-host-mismatch
means the certificate hostname didn't match the MX
hostname. validation-failure covers other
TLS handshake failures.
Per-sender vs aggregate analysis
TLS-RPT reports come from individual senders (Google, Microsoft, Mailbox.org, ProtonMail, others as adoption grows). Patterns matter: failures from a single sender might indicate that sender's specific TLS configuration issues (rare but possible). Failures from many senders indicate your inbound infrastructure has issues. Aggregate across senders to identify common patterns.
Policy versus connection failures
A TLS connection can succeed (handshake completes, encryption established) but still fail policy if MTA-STS required specific MX hosts and the actual delivery went to a non-listed host. Policy failures are about what your MTA-STS policy declared, not what TLS itself did. If you see policy failures, audit MTA-STS policy alignment with actual MX configuration.
Patterns we see when parsing real TLS-RPT reports.
certificate-expired across multiple senders
Your inbound MX certificate has expired and renewed certificate hasn't been deployed. Mail from senders with TLS enforcement (Gmail outbound, Outlook365, others) fails. Fix: deploy renewed certificate immediately; configure automated renewal (Let's Encrypt, certbot) to prevent recurrence; verify cert chain via openssl s_client before considering renewal complete.
certificate-host-mismatch
Certificate doesn't include the MX hostname in Subject Alternative Names. Common cause: certificate issued for the apex domain but MX is on a subdomain not covered by the cert. Fix: re-issue certificate including all MX hostnames in SAN; or use wildcard certificate covering the MX subdomain pattern.
starttls-not-supported on backup MX
Primary MX supports STARTTLS but backup MX does not. When primary fails over to backup, TLS fails. Fix: configure STARTTLS on all MX hosts in your priority chain; backup MX should match primary in TLS configuration to maintain the protection guarantees.
validation-failure during cipher negotiation
TLS handshake fails during cipher selection. Common causes: server only supports very old TLS versions (TLS 1.0/1.1, deprecated by major receivers), mismatched cipher suite preferences. Fix: ensure server supports TLS 1.2 minimum (TLS 1.3 preferred); review cipher suite configuration; update outdated TLS implementations.
Policy failures despite successful connections
TLS handshake completes but MTA-STS policy specifies
MX hosts that don't match actual delivery destination.
Fix: align MTA-STS policy MX list with current DNS
MX records; verify id= in DNS was
updated when policy changed (cached old policy can
cause this).
Reports arriving from only 1-2 senders
TLS-RPT adoption is still uneven. Reports from Google, Microsoft, and a handful of others are common; many other senders don't yet send TLS-RPT reports. Limited report volume is normal, not a configuration error. The reports you do receive are still valuable; patterns from major senders cover most of your inbound traffic.
How to receive reports so you have something to parse.
The parser on this page is useful when you have TLS-RPT aggregate reports to inspect. If you do not yet receive reports, the setup is straightforward and the workflow below produces reports flowing within 24-72 hours of completion.
Step 1: Publish the TLS-RPT DNS record.
Add a TXT record at _smtp._tls.yourdomain.com
with content
v=TLSRPTv1; rua=mailto:tls-reports@yourdomain.com.
The rua tag accepts a comma-separated list of email
addresses or HTTPS endpoints; most operators use a
dedicated mailbox that routes reports to their archival
and analysis pipeline. Multiple recipients are valid:
rua=mailto:tls@yourdomain.com,mailto:postmaster@yourdomain.com.
Step 2: Verify mailbox accepts reports. TLS-RPT reports arrive as MIME-attached JSON files, typically gzipped. The receiving mailbox needs to accept messages from any sender (since reports come from many different sending organisations), accept attachments including .gz and .json files, and not be rate-limited aggressively for legitimate report volume. Most modern mailbox infrastructure handles this by default; some tightly-configured corporate gateways need explicit allow-list entries for the report-generating domains.
Step 3: Set up automated processing. Reports arrive at a roughly daily cadence from each sender that has connection volume to your domain. For a domain receiving mail from typical mailbox providers (Gmail, Microsoft, Yahoo) and major commercial ESPs, expect 5-20 reports per day during typical operation, rising to 50+ during incidents. Manual review at scale is impractical; automated processing through a script that extracts JSON, parses it (the format is well- documented in RFC 8460), and aggregates failures by category and sender is the operational pattern most customers settle on.
Step 4: Establish baseline metrics. First 7-14 days of reports establish baseline. Typical baselines for well-configured domains: 99.5%+ success rate across all senders, no significant failure categories beyond occasional transient network issues. Failures concentrated in specific sender domains usually indicate an issue on the sender side that they need to fix; failures spread across multiple senders usually indicate an issue with your own MTA configuration. The parser on this page categorises failures by type and per-sender, which is what most operators need to identify which case applies.
What specific failure categories typically mean operationally.
starttls-not-supported: sender attempted
STARTTLS during SMTP handshake and the receiving MTA
either did not offer STARTTLS in its EHLO response or
rejected the STARTTLS command. For domains running MTA-STS
this should never happen against own infrastructure; if it
appears in your reports the cause is usually a
misconfigured MTA on your side (commonly a backup MX that
was added without STARTTLS configuration). Investigate
which MX produced the failure; the report includes
receiving-mx-hostname for each failure entry.
certificate-expired and certificate-not-trusted: the sender rejected your certificate during TLS handshake. Both indicate certificate management issues on your side: expired certificate that was not renewed, certificate chain that does not include a trusted intermediate, or hostname mismatch between certificate subject and MX hostname. Fix by ensuring all MX hostnames have valid certificates from a well-trusted CA with correct chain and adequate validity windows; LetsEncrypt with the automated renewal is the standard pattern for most operators.
certificate-host-mismatch: the certificate is valid and trusted but the hostname in the certificate does not match the MX hostname the sender connected to. Common cause is using a wildcard certificate that does not include the specific MX hostname pattern, or running a shared MX hostname across multiple domains without including all hostnames in subject alternative names. Fix by issuing a certificate that includes the specific MX hostname or using individual certificates per MX.
sts-policy-fetch-error: sender could
not fetch your MTA-STS policy file. Causes include
HTTPS serving issues on the mta-sts.yourdomain.com
subdomain, certificate issues on that subdomain, DNS
resolution failures, or rate-limiting on the policy
server. The policy file should be served by infrastructure
with very high availability since fetch failures during
enforce mode can block mail delivery. CDN hosting is the
common pattern for production deployments.
sts-policy-invalid: sender fetched the policy file but failed to parse it as a valid MTA-STS policy. Usually indicates a typo or formatting error in the policy file itself (missing newlines, incorrect mode values, missing required fields). The validator on the companion tool page checks policy syntax; if validation there passes but you still see sts-policy-invalid errors in reports, the sender may be using a stricter parser than ours; check the policy against RFC 8461 line by line.
mx-mismatch: sender connected to an MX that is not in your published MTA-STS policy mx allowlist. This commonly indicates that you added or changed an MX without updating the MTA-STS policy file. Update the policy to include all current MX hostnames, increment the DNS id value, and the failures should resolve within max_age (typically 7 days) as receivers refresh their policy cache.
Frequently asked.
Is TLS-RPT required for new sender requirements?
No, TLS-RPT is not required by Gmail/Yahoo February
2024 requirements. It's recommended for operations
running MTA-STS in testing or
enforce mode because TLS-RPT is the
primary feedback mechanism for understanding what
your MTA-STS policy is actually doing. Without
TLS-RPT, MTA-STS deployment is partly blind.
What's the difference between TLS-RPT and DMARC reports?
DMARC reports cover authentication outcomes (SPF, DKIM, DMARC alignment) for messages sent to recipients on your domain. TLS-RPT reports cover TLS connection outcomes for messages delivered to your inbound MX hosts. Different layers: DMARC is about message authenticity; TLS-RPT is about connection encryption. Both are useful, neither replaces the other.
How do I configure TLS-RPT?
Publish a TXT record at
_smtp._tls.yourdomain.com with content
v=TLSRPTv1; rua=mailto:tlsrpt@yourdomain.com.
Replace the email address with where you want reports
delivered. Most operations use a dedicated mailbox or
forwarding address, not a personal inbox; reports
come daily and the volume can be substantial.
Can TLS-RPT use HTTPS endpoint instead of email?
Yes, the spec supports
rua=https://yourdomain.com/path/ for HTTPS
endpoint reporting. Adoption is lower than mailto
currently; most senders send via email regardless.
Email-based reporting works reliably and integrates
with existing mail-based monitoring tools.
Should I parse reports automatically or review manually?
Automated parsing is appropriate at scale. Daily reports from multiple senders accumulate; manual review becomes impractical. Tools like this parser handle ad-hoc inspection; for ongoing monitoring, commercial tools or self-built pipelines parse reports and surface anomalies. Our Deliverability Monitoring service includes TLS-RPT report ingestion and alerting.
What if I don't have MTA-STS deployed?
You can still publish TLS-RPT and receive reports about TLS connection outcomes for inbound mail. Without MTA-STS the reports are less actionable (no policy to enforce against), but you still get visibility into TLS configuration health. Most operations deploy MTA-STS and TLS-RPT together; the combination is more useful than either alone.