TLS-RPT

MTA-STS in mode: testing is safe: sending MTAs report failures but still deliver. To safely promote to mode: enforce, you need to know whether real senders are actually completing TLS handshakes against your MX servers. TLS-RPT is how you find out.

Each day, senders that support TLS-RPT compile a JSON report of every TLS connection attempt to your domain: how many succeeded, how many failed, what the failure types were, which sending IPs were involved. The report is mailed to the address you specify in your TLS-RPT DNS record.

Without TLS-RPT, MTA-STS testing mode generates no observable signal. You'd be promoting blind. With TLS-RPT, you can see exactly what would happen under enforce mode and fix issues before they break real mail.

TLS-RPT is configured via a TXT record at _smtp._tls.<domain>:

_smtp._tls.example.com. IN TXT "v=TLSRPTv1; rua=mailto:tls-rpt@example.com"

Decoded:

• v=TLSRPTv1. Version. Always 1 in current use.
• rua=mailto:.... Where reports get sent. Multiple addresses can be specified, comma-separated.
• rua=https://.... Reports can also be POSTed to an HTTPS endpoint instead of mailed. Useful for senders with high-volume reporting that want HTTP ingestion.

One DNS record is enough. TLS-RPT doesn't need policy files, version negotiation, or anything beyond the destination for reports.

Reports are JSON, gzipped, attached to a daily mail to your rua= address. The structure (RFC 8460):

{
  "organization-name": "Example Sender Inc",
  "date-range": {
    "start-datetime": "2026-05-08T00:00:00Z",
    "end-datetime": "2026-05-08T23:59:59Z"
  },
  "contact-info": "tlsrpt@sender.example",
  "report-id": "2026-05-08T00:00:00Z_recipient.com",
  "policies": [{
    "policy": {
      "policy-type": "sts",
      "policy-string": ["version: STSv1", "mode: enforce", "mx: mail.recipient.com", "max_age: 86400"],
      "policy-domain": "recipient.com",
      "mx-host": ["mail.recipient.com"]
    },
    "summary": {
      "total-successful-session-count": 1247,
      "total-failure-session-count": 23
    },
    "failure-details": [{
      "result-type": "validation-failure",
      "sending-mta-ip": "203.0.113.42",
      "receiving-mx-hostname": "mail.recipient.com",
      "failed-session-count": 18
    }]
  }]
}

Key fields:

• policies[]. One entry per policy your domain published. Usually one (the MTA-STS policy).
• summary.total-successful-session-count. Clean TLS connections from this sender during the period.
• summary.total-failure-session-count. Connection attempts that failed.
• failure-details[]. Per-failure-type breakdown. Tells you exactly why connections failed.

Common failure types include starttls-not-supported, certificate-host-mismatch, certificate-expired, validation-failure, sts-policy-fetch-error. Each has its own remediation. Our TLS-RPT parser decodes these reports into action items.

Manually reading TLS-RPT reports is painful. They're structured JSON not formatted for humans, they arrive daily from many senders, and the volume scales with how many senders deliver to your domain.

Automated parsing pipeline:

1. Receive reports at the rua= mailbox (or HTTPS endpoint).
2. Parse each report (gunzip, JSON decode).
3. Index per sender, per failure type, per date.
4. Compute aggregate failure rate across all senders, weighted by volume.
5. Surface trends, threshold alerts, per-sender drill-down.

Open-source parsers exist. parsedmarc handles both DMARC aggregate reports and TLS-RPT reports. Self-hosted, fairly easy to set up, indexes into Elasticsearch or PostgreSQL. We deploy parsedmarc plus a custom dashboard for managed customers running MTA-STS at scale.

The deployment ramp depends on what TLS-RPT shows:

1. Day 0. Publish TLS-RPT record. Wait for first reports (up to 48 hours from major senders).
2. Days 1-7. Reports arriving but volume is low. Verify the parser is ingesting correctly.
3. Day 7. Publish MTA-STS policy in mode: testing. From this point, TLS-RPT reports include MTA-STS-specific failures (policy fetch errors, MX-not-in-policy events).
4. Days 7-30. Watch failure rate. Initial weeks often show 1-3% failure rate from old senders, mis-cached policies, transient TLS issues. Investigate the persistent failure types and fix what you can on your side.
5. Day 30. Decision point. If failure rate is consistently under 1% across major senders (Google, Microsoft, Yahoo, Apple), you can promote to mode: enforce. If higher, identify what's failing and address before promoting.
6. Day 30+. In enforce mode, continued TLS-RPT monitoring catches regressions. New senders failing? Cert expiry? MX migration breaking policy? Reports tell you within 24 hours.

Promoting MTA-STS without TLS-RPT visibility is asking for blocked legitimate mail. The two are designed to work together.

TLS-RPT reports follow RFC 8460 JSON format. The schema is straightforward but verbose: contact info, organization name, report ID, date range, and an array of policies with per-policy failure-counter buckets. Senders package reports into .gz-compressed JSON files attached to a single email per reporting period.

Parsing approaches scale with operation size. For low-volume operations (under 100 reports/day), manual review with a JSON formatter is sufficient. The free TLS-RPT parser tool we provide handles ad-hoc inspection. For mid-scale operations (100-1000 reports/day), automated ingestion into a database with dashboard views becomes worthwhile; a simple Python script extracting reports from email and writing to PostgreSQL covers most needs. For large operations (1000+ reports/day), commercial tools (Valimail, dmarcian, Sendforensics) handle ingestion plus alerting; the cost is justified by the volume of signal that would otherwise be lost.

Parsing gotchas. Failure type field uses controlled vocabulary defined in RFC 8460; new types may appear as the spec evolves. Report IDs are not necessarily unique across reporting periods; use the combination of report-id + date-range as the key. Some senders send reports daily; others weekly. Some senders deliver reports to the rua= address inline; others (notably some smaller providers) send to operations@ or postmaster@ addresses regardless of rua= configuration. Reliable parsing accepts reports from multiple addresses.

Persistent failure investigation requires per-sender pattern analysis. A failure occurring once might be transient (network blip, certificate cache lag); a failure occurring across multiple report periods from the same sender is a real configuration issue. The diagnostic flow: identify the persistent failure, identify the sender, identify your inbound MX hosts they're trying to reach, test those MX hosts directly (openssl s_client) to reproduce the failure, fix the underlying issue.

TLS-RPT (RFC 8460) has reached production-grade adoption across major mailbox providers through 2024-2026. Gmail, Microsoft 365, Yahoo, Apple, ProtonMail, Fastmail, and all major commercial ESPs send TLS-RPT aggregate reports to domains that publish the receiving endpoint. Enterprise gateways including Mimecast, Proofpoint, Barracuda, and Cisco IronPort also send reports though their participation has been less consistent historically.

The structural value of TLS-RPT is that it produces the only externally-verifiable visibility into TLS connection outcomes between senders and your inbound infrastructure. Without TLS-RPT, an operator cannot easily distinguish between a sender that connected successfully and one that fell back to cleartext or failed entirely; the operator only sees the messages that arrived. With TLS-RPT, the operator sees the connection attempts that failed for TLS reasons and can address the root causes before they affect production mail.

The reports arrive as JSON files attached to email messages, gzipped, sent to the address specified in the TLS-RPT DNS record. The format is well-documented and stable; multiple open-source parsers exist and the major DMARC/TLS-RPT dashboard services all consume the format. The frequency varies by sender: most send daily aggregate reports, some send per-incident reports for specific failure events, a few send weekly aggregates only.

For domains running MTA-STS in testing mode, TLS-RPT reports are the primary input to the decision to transition to enforce mode. Without TLS-RPT visibility, the transition is effectively blind; the operator cannot verify that the policy is working as expected and that legitimate senders are not failing in ways that would block mail under enforce. Most operators completing MTA-STS deployments through 2024-2026 use 14-30 days of TLS-RPT data before transitioning to enforce, which is the period needed to see reports from the long tail of less-frequent senders.

The setup is straightforward but requires getting several pieces right simultaneously. The pattern below has produced reliable TLS-RPT reception across the deployments we have completed for customers.

DNS record: publish a TXT record at _smtp._tls.yourdomain.com with content v=TLSRPTv1; rua=mailto:tls-reports@yourdomain.com. The rua tag accepts comma-separated mailbox addresses or HTTPS endpoints. Multiple recipients are valid: rua=mailto:tls@yourdomain.com,mailto:postmaster@yourdomain.com. Some operators publish HTTPS endpoints (rua=https://reports.example.com/tlsrpt) for direct API ingestion; mailbox endpoints remain more common because they require less infrastructure.

Receiving mailbox: dedicated mailbox that accepts mail from any sender (since reports come from many senders), accepts attachments (JSON files, often gzipped), is not aggressively rate-limited, and routes to your processing pipeline. Most modern mailbox infrastructure handles this; tightly-configured corporate gateways may need explicit allow-listing for the sender domains that produce reports.

Processing pipeline: automated parsing of inbound reports. Reports are JSON; the format is documented in RFC 8460. Multiple open-source parsers exist (ParseDMARC handles both DMARC and TLS-RPT, several language-specific libraries). The processed data should flow into a queryable store (Elasticsearch, ClickHouse, or simple PostgreSQL works for moderate volume) for trend analysis and alerting.

Alerting and review: production deployments should alert on aggregate failure rate exceeding baseline (typically 1-2% across all senders is normal; sustained rates above 5% indicate a real configuration issue), on new failure categories appearing (a sender that previously sent successfully starting to fail for a specific reason), and on absence of expected reports (a sender that historically sent daily reports stopping for more than 7 days, which sometimes indicates the sender hit a problem rather than that everything is fine).

The failure categories enumerated in RFC 8460 cover the operational scenarios that produce report-able outcomes. Operators reading their first few weeks of reports typically encounter the same handful of categories repeatedly.

starttls-not-supported: sender attempted STARTTLS and the receiving MTA did not offer it or rejected it. For domains running MTA-STS this should never happen against own infrastructure; if it appears, an MX is misconfigured (often a backup MX added without STARTTLS configuration). The operator response is to identify the specific MX from the report and configure STARTTLS correctly.

certificate-host-mismatch: certificate is valid but does not match the MX hostname. Common cause is using a wildcard certificate that does not include the MX hostname pattern, or using a single certificate across multiple MX hostnames without including all in subject alternative names. The operator response is to issue a certificate that includes the specific MX hostname, or to use per-MX individual certificates.

certificate-expired and certificate-not-trusted: certificate management issues. Expired certificate that was not renewed, certificate chain missing trusted intermediate, certificate from an untrusted CA. The operator response is to ensure all MX hostnames have valid certificates from trusted CAs with adequate validity windows; LetsEncrypt with automated renewal is the standard pattern.

sts-policy-fetch-error: sender could not fetch your MTA-STS policy file from mta-sts.yourdomain.com. Causes include HTTPS serving issues, certificate issues on that subdomain, DNS resolution failures, or temporary network issues. The operator response is to ensure the policy server has very high availability; CDN hosting is the standard production pattern.

sts-policy-invalid: sender fetched the policy file but could not parse it as valid MTA-STS. Usually indicates a typo or formatting error in the policy file. The operator response is to validate the policy file against RFC 8461 syntax; the companion MTA-STS validator tool on this site catches most issues.

mx-mismatch: sender connected to an MX not in your published MTA-STS mx allowlist. Indicates the MTA-STS policy is out of sync with the actual MX records. The operator response is to update the policy file to include all current MX hostnames and increment the DNS id value.

transient-network-error: connection failure unrelated to TLS, included in reports for completeness. Operationally not actionable in isolation; sustained transient errors from a specific sender may indicate routing or congestion issues that the sender needs to address on their side.

TLS-RPT and DMARC aggregate reporting (rua) cover different layers of the email infrastructure and produce complementary visibility rather than overlapping data. Most production deployments need both; either alone produces incomplete operational picture.

DMARC aggregate reports cover authentication outcomes: did SPF pass, did DKIM pass, did DMARC alignment succeed, what disposition did the receiver apply. The reports surface authentication misconfigurations, third-party sending sources operating without authorization, and content modifications during transit that break DKIM signatures. The temporal cadence is typically daily; the volume scales with the diversity of receivers your mail reaches.

TLS-RPT reports cover transport-layer outcomes: did the TLS handshake succeed, what was the cipher selected, did the certificate validate correctly, did the policy fetch succeed if MTA-STS is published. The reports surface transport configuration issues that DMARC reports cannot see because authentication operates on messages that have already established a transport channel.

Operationally, the two report streams should flow into the same analysis infrastructure. Both formats are JSON (DMARC is XML historically but JSON variant is increasingly common; TLS-RPT is JSON natively); both are sent as email attachments to dedicated mailboxes; both produce time-series data that benefits from the same monitoring tooling. Most operators set up the two streams together during initial deliverability infrastructure deployment, and the combined visibility catches most configuration issues before they produce customer-facing impact.

For operators new to email infrastructure observability, the priority order is: DMARC aggregate reporting first because authentication is the foundational concern, TLS-RPT second once MTA-STS or DANE deployment is on the roadmap. Setting up both simultaneously is operationally fine but represents more configuration work than most teams want to do in a single sprint; sequential deployment is typical.

TLS-RPT aggregate reports from major receivers arrive at substantial daily volume for production sending operations. The analysis patterns that surface actionable insight versus producing noise are specific enough that operators benefit from explicit guidance rather than developing patterns through trial and error.

The first-pass aggregation: sum total successful sessions and total failure sessions across all senders for the reporting period, calculate aggregate failure rate as failures divided by total. Healthy operations show failure rate below 1% sustained; rates above 2% indicate configuration issues that need investigation. The aggregate rate is the headline metric for operational health.

The per-sender breakdown: group failures by reporting sender (the receiver that sent the report). Concentrations in specific receivers indicate configuration issues specific to your interaction with those receivers; spread across many receivers indicates broader configuration issues. The breakdown identifies whether remediation should target specific receiver relationships or broader infrastructure.

The per-failure-type breakdown: group failures by result-type (starttls-not-supported, certificate-host-mismatch, certificate-expired, sts-policy-fetch-error, mx-mismatch, others). Each failure type has specific remediation steps; the volume per type indicates which remediation matters most. Most operations show one dominant failure type rather than diverse failure distribution.

The temporal pattern analysis: compare current-period aggregates to previous periods. Failure rates increasing indicate degradation; failure rates decreasing indicate successful remediation. Sudden spikes typically indicate discrete events (certificate expiration, MX change, infrastructure deployment); gradual increases indicate slow accumulating issues. The trending analysis identifies whether the situation needs immediate response or routine attention.

The receiver-side correlation: correlate TLS-RPT failure patterns with deliverability metrics from other monitoring sources. TLS failures that correlate with placement degradation at the same receivers indicate the TLS issues are producing measurable delivery impact; failures that do not correlate may be cosmetic from a delivery perspective. The correlation analysis helps prioritize remediation by impact rather than by failure volume alone.

For operators planning eventual DANE deployment, TLS-RPT provides operational visibility into the TLS posture that supports the DANE migration decision. The aggregate reports show whether existing senders are reaching your infrastructure through clean TLS connections; the data informs whether DANE deployment would produce material additional security or whether MTA-STS plus opportunistic TLS already covers the threat surface that matters operationally.

The structural pattern: deploy MTA-STS and TLS-RPT first, run for 6-12 months observing the actual TLS connection patterns, evaluate DANE deployment based on observed traffic and threat-model requirements. DANE deployment produces additional security in specific scenarios (targeted downgrade attacks, advanced traffic interception) that most operators do not face routinely. The TLS-RPT data shows whether the operator is in one of the scenarios where DANE adds meaningful protection.