TLS-RPT: SMTP TLS Reporting

Gain visibility into TLS connection failures during email delivery with RFC 8460 reporting.

RFC 8460 overview

SMTP TLS Reporting (TLS-RPT), defined in RFC 8460, is a mechanism for receiving mail servers to request reports about TLS negotiation failures from sending mail servers. When a sender attempts to deliver mail to your MX servers and encounters a TLS problem -- an expired certificate, a cipher mismatch, or a policy violation -- the sender generates a structured report and delivers it to the address you specify in DNS.

TLS-RPT is the observability layer for two related standards:

Without TLS-RPT, you have no way to know when these policies cause delivery failures. A misconfigured MTA-STS policy or an expired TLSA record can silently reject legitimate mail. TLS-RPT closes this feedback loop.

What TLS-RPT reports contain

Reports are JSON documents (typically gzip-compressed when sent via email) that cover a 24-hour reporting period. Each report contains:

Common failure result types include:

DNS TXT record format

TLS-RPT is published as a TXT record at _smtp._tls.<domain>:

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

The record has two components:

You can specify multiple reporting URIs by separating them with commas:

_smtp._tls.example.com. IN TXT "v=TLSRPTv1; rua=mailto:tlsrpt@example.com,https://reporting.example.com/tlsrpt"

Setting up a reporting endpoint

There are two approaches to receiving TLS-RPT reports:

Email-based reporting

The simplest approach: create a dedicated mailbox (e.g., tlsrpt@example.com) and point rua=mailto:tlsrpt@example.com at it. Reports arrive as email attachments containing gzip-compressed JSON files.

Considerations:

HTTPS-based reporting

More suitable for automated processing: deploy an HTTPS endpoint that accepts POST requests with JSON bodies. The endpoint URL goes into the rua= tag:

rua=https://reporting.example.com/v1/tlsrpt

Your endpoint must:

Interpreting JSON report fields

A TLS-RPT JSON report follows this structure:

{
  "organization-name": "Example Sender Inc.",
  "date-range": {
    "start-datetime": "2026-04-08T00:00:00Z",
    "end-datetime": "2026-04-08T23:59:59Z"
  },
  "contact-info": "tlsrpt@sender.example.com",
  "report-id": "2026-04-08T00:00:00Z_example.com",
  "policies": [
    {
      "policy": {
        "policy-type": "sts",
        "policy-string": [
          "version: STSv1",
          "mode: enforce",
          "mx: mail.example.com",
          "max_age: 604800"
        ],
        "policy-domain": "example.com"
      },
      "summary": {
        "total-successful-session-count": 4523,
        "total-failure-session-count": 12
      },
      "failure-details": [
        {
          "result-type": "certificate-expired",
          "sending-mta-ip": "198.51.100.42",
          "receiving-mx-hostname": "mail.example.com",
          "receiving-ip": "203.0.113.10",
          "failed-session-count": 8,
          "additional-information": "Certificate expired 2026-04-07T12:00:00Z"
        },
        {
          "result-type": "sts-webpki-invalid",
          "sending-mta-ip": "198.51.100.43",
          "receiving-mx-hostname": "mail.example.com",
          "failed-session-count": 4,
          "additional-information": "Unable to fetch MTA-STS policy: TLS handshake failed"
        }
      ]
    }
  ]
}

Key fields to monitor:

Practical examples

Publishing a TLS-RPT DNS record

# DNS zone file entry
_smtp._tls.example.com. 3600 IN TXT "v=TLSRPTv1; rua=mailto:tlsrpt@example.com"

# Verify it's published
dig +short TXT _smtp._tls.example.com
# Expected: "v=TLSRPTv1; rua=mailto:tlsrpt@example.com"

Decompressing an email-delivered report

Reports arrive as gzip-compressed JSON attachments. To read one:

# Extract and pretty-print a report
gunzip -c report.json.gz | python3 -m json.tool

Monitoring workflow

A recommended deployment sequence:

  1. Deploy TLS-RPT first -- publish the _smtp._tls record before enforcing MTA-STS or DANE. This gives you visibility before policies start rejecting mail.
  2. Deploy MTA-STS in testing mode -- set mode: testing in the MTA-STS policy. Senders will evaluate the policy and report failures via TLS-RPT, but will not reject mail.
  3. Monitor reports for 2-4 weeks -- look for certificate-expired, certificate-host-mismatch, or sts-policy-fetch-error results. Fix any issues.
  4. Switch to enforce mode -- once reports confirm clean delivery, change the MTA-STS policy to mode: enforce. Continue monitoring TLS-RPT for regressions.

Common pitfalls

Check your domain's email security with beacon