TLS-RPT (TLS Reporting)

TLS-RPT (SMTP TLS Reporting) provides visibility into TLS connection failures when other mail servers try to deliver email to your domain.

How TLS-RPT Works

The Problem

When TLS connections fail during email delivery:

• You have no visibility into failures
• Can't diagnose certificate or configuration issues
• Don't know if MTA-STS is working correctly

The Solution

TLS-RPT enables sending servers to report:

• TLS connection attempts
• Success and failure counts
• Specific failure reasons
• Policy mode being used

Sender's Server                     Your Domain
      │                                  │
      │  1. Try TLS connection           │
      │ ─────────────────────────────>   │
      │                                  │
      │  2. Connection succeeds/fails    │
      │                                  │
      │  3. Log the result               │
      │                                  │
      │  4. Send daily TLS-RPT report    │
      │ ─────────────────────────────>   │
      │     (to your reporting address)  │

TLS-RPT Record Format

TLS-RPT records are TXT records at:

_smtp._tls.example.com

Example:

v=TLSRPTv1; rua=mailto:tls-reports@example.com

Record Tags

Tag	Required	Description
v	Yes	Version (TLSRPTv1)
rua	Yes	Report URI(s)

Report URIs

Reports can be sent via:

Email:

rua=mailto:tls-reports@example.com

HTTPS:

rua=https://example.com/tls-reports

Multiple destinations:

rua=mailto:tls@example.com,https://api.example.com/tls

Report Format

TLS-RPT reports are JSON documents:

{
  "organization-name": "Google Inc.",
  "date-range": {
    "start-datetime": "2024-01-15T00:00:00Z",
    "end-datetime": "2024-01-15T23:59:59Z"
  },
  "contact-info": "postmaster@google.com",
  "report-id": "2024011500001",
  "policies": [
    {
      "policy": {
        "policy-type": "sts",
        "policy-string": ["version: STSv1", "mode: enforce", ...],
        "policy-domain": "example.com",
        "mx-host": "mail.example.com"
      },
      "summary": {
        "total-successful-session-count": 1250,
        "total-failure-session-count": 3
      },
      "failure-details": [...]
    }
  ]
}

Report Sections

Organization Info:

• Reporter name (e.g., Google, Microsoft)
• Contact information
• Report date range

Policy Details:

• Policy type (sts, tlsa, no-policy-found)
• Policy domain
• MX host checked

Summary:

• Total successful connections
• Total failed connections

Failure Details:

• Specific failure reasons
• Count per failure type
• IP addresses involved

Failure Types

Certificate Failures

Code	Description
certificate-expired	Certificate past validity
certificate-not-valid-yet	Certificate not yet valid
certificate-host-mismatch	Hostname doesn't match
certificate-not-trusted	Untrusted CA

Connection Failures

Code	Description
starttls-not-supported	Server doesn't support STARTTLS
validation-failure	General validation error
sts-policy-fetch-error	Can't retrieve MTA-STS policy
sts-policy-invalid	Policy file is malformed

MTA-STS Failures

Code	Description
sts-webpki-invalid	Policy HTTPS certificate invalid
sts-policy-invalid	Policy content malformed

Setting Up TLS-RPT

Step 1: Choose Reporting Destination

Options:

• Your email address
• MailShield's reporting address
• Your own HTTPS endpoint

Step 2: Add DNS Record

Add TXT record at _smtp._tls.example.com:

v=TLSRPTv1; rua=mailto:YOUR-ID@reports.mailshield.app

Replace YOUR-ID with your MailShield Report ID.

Step 3: Wait for Reports

Reports typically arrive:

• Daily from most providers
• Weekly from some providers
• First reports within 24-48 hours

Reading TLS-RPT Reports

Success Metrics

Monitor:

• total-successful-session-count - TLS working
• Trend over time - should be stable or increasing

Failure Analysis

When failures occur:

1. Check failure type
2. Identify affected MX host
3. Review failure count vs. success count
4. Investigate root cause

Common Issues to Watch

Issue	Indicator
Certificate expiry	certificate-expired failures
Wrong hostname	certificate-host-mismatch
MTA-STS misconfiguration	sts-policy-* failures
TLS disabled	starttls-not-supported

TLS-RPT and MTA-STS

TLS-RPT is especially valuable with MTA-STS:

Without MTA-STS:

• Reports show opportunistic TLS status
• Failures are less critical (email still delivered)

With MTA-STS:

• Reports show policy enforcement
• Failures may cause delivery issues
• Critical for monitoring enforcement

Recommended Setup

Always deploy together:

_mta-sts.example.com   TXT  "v=STSv1; id=20240115"
_smtp._tls.example.com TXT  "v=TLSRPTv1; rua=mailto:tls@example.com"

Using MailShield for TLS-RPT

MailShield provides:

1. Report Reception

   • Receives reports at your unique address
   • Parses JSON automatically

2. Report Analysis

   • Visual summary of success/failure
   • Trend analysis over time
   • Failure categorization

3. Alerting

   • Notifications for high failure rates
   • Alerts for new failure types

Best Practices

Do

✅ Configure TLS-RPT alongside MTA-STS
✅ Monitor reports regularly
✅ Investigate failures promptly
✅ Use a dedicated report address
✅ Keep certificates up to date

Don't

❌ Ignore TLS-RPT reports
❌ Deploy MTA-STS enforce without TLS-RPT
❌ Use a full inbox for reports (high volume)
❌ Dismiss low failure counts (investigate anyway)

Troubleshooting

No Reports Received

1. Verify DNS record exists
2. Check record syntax
3. Wait 24-48 hours (reports are periodic)
4. Verify email address works

High Failure Rate

1. Check certificate validity
2. Verify hostname matches certificate
3. Test TLS connectivity manually
4. Review MTA-STS policy accuracy

Parse Errors

If using a custom endpoint:

• Reports are JSON with gzip compression
• Content-Type may vary by sender
• Handle different sender formats

Example Records

Basic Configuration

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

With MailShield

_smtp._tls.example.com  TXT  "v=TLSRPTv1; rua=mailto:abc123@reports.mailshield.app"

Multiple Destinations

_smtp._tls.example.com  TXT  "v=TLSRPTv1; rua=mailto:tls@example.com,mailto:abc123@reports.mailshield.app"