TLS-RPT Generator

How to use this TLS-RPT generator

Step 1: Add reporting destinations

Enter where you want to receive TLS failure reports:

Email (recommended for starting)

mailto:tlsrpt@captaindns.com

HTTPS webhook (for automation)

https://tlsrpt.captaindns.com/v1/report

You can add multiple destinations - reports go to all of them.

Step 2: Copy the generated record

The generator creates a valid RFC 8460 record:

v=TLSRPTv1; rua=mailto:tlsrpt@captaindns.com

Step 3: Publish to DNS

Create a TXT record at _smtp._tls.captaindns.com with the generated value.

Example for captaindns.com:

• Type: TXT
• Host: _smtp._tls
• Value: v=TLSRPTv1; rua=mailto:tlsrpt@captaindns.com

Step 4: Verify publication

Use our TLS-RPT Record Checker to confirm correct configuration.

What TLS-RPT actually reports

TLS-RPT is a pure observability tool: it never changes how a server behaves; it reveals what really happened during inbound TLS connections to your MX hosts.

Sending operators report things like:

• a STARTTLS downgrade or strip, where the session falls back to cleartext
• an expired, untrusted or self-signed certificate
• a certificate whose hostname does not match the expected MX
• a failure to fetch or validate an MTA-STS policy
• a DANE failure: invalid TLSA record or broken DNSSEC chain

TLS-RPT enforces no rule. Refusing to deliver a message in the clear comes from MTA-STS or DANE; TLS-RPT only tells you when and why encryption failed, so you can fix it before switching to enforce.

TLS-RPT record format

Required components

URI schemes supported

mailto: - Email delivery

rua=mailto:security-team@captaindns.com

Reports arrive as compressed JSON attachments.

https: - Webhook delivery

rua=https://api.captaindns.com/tlsrpt/ingest

Reports are POSTed as JSON with the header Content-Type: application/tlsrpt+gzip.

Multiple destinations

Separate with commas:

v=TLSRPTv1; rua=mailto:reports@captaindns.com,https://tlsrpt.captaindns.com/report

Send reports to a third-party domain

A rua that points to a domain other than your own works as-is, with no authorization record on the recipient side.

This is a major difference from DMARC. DMARC requires a _report._dmarc record on the third-party domain before it accepts cross-domain reports. RFC 8460 deliberately dropped that mechanism (section 7): the amplification risk with TLS-RPT is lower than with DMARC, and trust is secured another way. mailto: reports are DKIM-signed by the sending operator, and https: reports rely on the endpoint owning its DNS and certificate.

v=TLSRPTv1; rua=mailto:reports@tlsrpt-service.com

No action is required on tlsrpt-service.com for this rua to be valid.

To keep things simple, an address on your own domain is enough in most cases:

v=TLSRPTv1; rua=mailto:tlsrpt@captaindns.com

DNS provider examples

Cloudflare

1. Go to DNS settings for your domain
2. Add a record:
   • Type: TXT
   • Name: _smtp._tls
   • Content: Your generated record value
   • TTL: Auto

AWS Route 53

1. Open the hosted zone for your domain
2. Create a record:
   • Record name: _smtp._tls
   • Record type: TXT
   • Value: "v=TLSRPTv1; rua=mailto:tlsrpt@captaindns.com"
   • TTL: 3600

OVH / Google Domains

1. Go to the DNS zone
2. Add an entry:
   • Subdomain: _smtp._tls
   • Type: TXT
   • Target: Your generated record value
   • TTL: 3600

Understanding TLS-RPT reports

A TLS-RPT report is an aggregated, gzip-compressed JSON document that summarizes one operator's TLS sessions to your domain over a single day.

Anatomy of a report

{
  "organization-name": "Google Inc.",
  "date-range": {
    "start-datetime": "2024-01-15T00:00:00Z",
    "end-datetime": "2024-01-16T00:00:00Z"
  },
  "contact-info": "postmaster@google.com",
  "report-id": "2024011512345",
  "policies": [{
    "policy": {
      "policy-type": "sts",
      "policy-string": ["version: STSv1", "mode: enforce", "mx: mail.captaindns.com", "max_age: 604800"],
      "policy-domain": "captaindns.com"
    },
    "summary": {
      "total-successful-session-count": 8432,
      "total-failure-session-count": 3
    },
    "failure-details": [{
      "result-type": "certificate-expired",
      "sending-mta-ip": "198.51.100.1",
      "receiving-mx-hostname": "mail.captaindns.com",
      "failed-session-count": 3
    }]
  }]
}

Failure types (result-type)

The IANA registry defines 11 possible values for result-type:

Policy types (policy-type)

Each session is tied to one of the 3 policy-type values:

Transport and cadence

Every report is gzip-compressed. Two delivery channels exist, depending on the scheme of your rua:

• HTTPS: the report is sent via POST with the header Content-Type: application/tlsrpt+gzip (or application/tlsrpt+json). The endpoint confirms receipt with a 2xx status.
• Email: the message is a multipart/report; report-type="tlsrpt" with an application/tlsrpt+gzip attachment. It carries the TLS-Report-Domain and TLS-Report-Submitter headers, a subject of the form Report Domain: captaindns.com Submitter: google.com Report-ID: 2024011512345, and it is DKIM-signed with the selector s=tlsrpt.

Cadence: each sending operator emits one aggregated report per day, covering the 00:00 to 24:00 UTC window. If delivery fails, it retries for up to 24 hours.

Who sends the reports

The large operators emit TLS-RPT reports: Google, Microsoft and Yahoo do so consistently; Apple and Comcast are reported to do so as well. Each operator produces its own independent report, so you may receive several per day, one per sender.

TLS-RPT with MTA-STS and DANE

TLS-RPT is the observability loop for MTA-STS and DANE. These protocols enforce encryption; TLS-RPT shows you the effect of that enforcement, both before and after going to production.

Recommended deployment order

1. Publish TLS-RPT, and MTA-STS in mode: testing
2. Analyze the reports for 2 to 4 weeks
3. Switch MTA-STS to mode: enforce
4. Keep monitoring via TLS-RPT

Switching to enforce without TLS-RPT means moving blind: if a policy breaks deliverability, you will only learn about it through user complaints.

Related tools

• Generate an MTA-STS policy
• Check MTA-STS status
• Check TLS-RPT status
• Check DANE TLSA records

Best practices and common pitfalls

Best practices

• Point the rua at a dedicated mailbox or endpoint, able to absorb the volume and parse the JSON. Never a human inbox: reports arrive every day, as gzipped JSON, from every operator.
• Use an aggregation tool to turn these reports into actionable trends rather than opening them one by one.

Pitfalls to avoid

• Two TXT records at _smtp._tls make the configuration invalid. Keep a single record with a single value.
• Percent-encode the ,, ! and ; characters when they appear in a URI (for example in a mailto: with parameters), otherwise record parsing breaks.

Real-world use cases

Each scenario below maps to a specific result-type in your reports:

• A backup MX never configured for TLS: starttls-not-supported. You spot it before an attacker takes advantage of it.
• A partner's certificate has expired: certificate-expired on the sessions it covers.
• An MX presents a certificate issued for the wrong hostname: certificate-host-mismatch.
• An active STARTTLS downgrade (on-path attack) collapses encrypted sessions: a spike of starttls-not-supported.
• Your own MTA-STS policy is broken or unreachable: sts-policy-fetch-error or sts-policy-invalid, before it blocks legitimate mail.
• A misconfigured DANE: tlsa-invalid (a TLSA that no longer matches after a certificate rotation) or dnssec-invalid (a broken DNSSEC chain).

Complementary tools

Useful resources

• RFC 8460 - SMTP TLS Reporting (official specification)
• RFC 8461 - MTA-STS (companion protocol)
• Google - Configure TLS reporting
• Postfix - TLS documentation