This article explains how to publish an MTA-STS and TLS Reporting policy using the Valimail API. Please note that hosting is available only to Enforce users.

If you are using Valimail Monitor and want to configure TLS reporting, please follow the instructions outlined here to set up reporting.

Prerequisites

Expand each section to see additional instructions.

API access enabled on the account

API Access is required for creating the MTA-STS and TLS-RPT policies. If your Enforce account does not include API access, reach out to [email protected], and our team will create the policies for you (Steps 2-5).

Account slug

To locate your account slug, log in to your Enforce account at app.valimail.com. The account slug appears in your browser’s address bar within the URL. Specifically, it is the text displayed between app/ and /dmarc, as illustrated in the example below:

https://app.valimail.com/app/ACCOUNT_SLUG/dmarc/overview

If you're not seeing the account slug, click on Account Overview in the Enforce side menu, then recheck the URL.

API credentials: ClientID and AppID

If you don't already have a set of API credentials, you can create one following the instructions here. You will need to create the credentials for the Configuration API.

DNS access to publish CNAMEs for _mta-sts.<domain>, _smtp._tls.<domain>, and mta-sts.<domain>

Three CNAME records are required for pointing the MTA-STS, TLS-RPT, and HTTPS policy to Valimail. This article contains the full set of instructions for publishing the CNAME records.

API server:

The API endpoints required for the next steps are in the Valimail Configuration API: https://api.valimail.com/docs/config.html

Implementation Flow (high level)

Publish DNS CNAMEs for discovery and TLSRPT (and optionally for Valimail-hosted policy endpoint), and allow for DNS propagation, which may not occur until the TTL time of 60 minutes has passed and the update is globally established.
Authenticate → POST /auth to obtain a bearer token.
Ensure the domain exists → POST /accounts/{slug}/domains.
Create MTA-STS policy → POST /accounts/{slug}/domains/{domain}/mta_sts_policy.
Create TLS-RPT policy → POST
/accounts/{slug}/domains/{domain}/smtp_tls_policy.
Validate via API (GET policy endpoints) and via DNS (dig/curl).
Optionally fetch TLS summary and failure details for monitoring.

1) Publish Required DNS CNAMEs (CNAME-only)

Create these records at your DNS provider. Do not mix NS delegation on the same labels. Go to this article for more detailed instructions.

MTA-STS discovery (TXT served by Valimail)

Host/Name: _mta-sts.<yourdomain>
Type: CNAME
Target/Value: <yourdomain>._mta-sts.vali.email.

HTTPS policy file

Host/Name: mta-sts.<yourdomain>
Type: CNAME
Target/Value: policy.mta-vali.email

TLS-RPT discovery (TXT served by Valimail)

Host/Name: _smtp._tls.<yourdomain>
Type: CNAME
Target/Value: <yourdomain>._smtptlsrpt.vali.email

Replace <yourdomain> with the actual domain or subdomain.

Allow DNS propagation (lower TTLs can help during rollout).

The DNS records should be created before proceeding with any next steps for MTA-STS policy creation. Issuance of the certificate for your domain depends on these DNS records.

2) Authenticate

Request (curl):

curl -sS -X POST 
https://api.valimail.com/auth   
 -H 'Content-Type: application/json'   
 -d '{
    "ClientID": "YOUR_CLIENT_ID",
    "AppID": "YOUR_APP_ID"
  }'

Replace YOUR_CLIENT_ID and YOUR_APP_ID with your own API credentials.

Successful response returns a bearer token and expiration:

{
  "token": "#########",
  "expires-at": "2029-10-31T18:26:50.597068836Z"
}

Use the token in the Authorization header: Bearer <token> for all subsequent calls.

3) Ensure the Domain Exists

Create the domain if it DOES NOT already exist.

Request (curl):

curl -sS -X POST 
https://api.valimail.com/accounts/{slug}/domains   
 -H 'Authorization: Bearer <token>'   
 -H 'Content-Type: application/json'   
 -d '{
    "domain": "{domain}"
  }'

Replace <token> with the bearer token generated at Step 2.
Replace {slug} with your Account Slug.
Replace {domain} with the Domain Name that you want to add to your account.

4) Create MTA-STS Policy

POST /accounts/{slug}/domains/{domain}/mta_sts_policy

Example (policy-mode=testing → switch to enforce after validation):

curl -sS -X POST https://api.valimail.com/accounts/{slug}/domains/{domain}/mta_sts_policy
  -H 'Authorization: Bearer <token>'   
  -H 'Content-Type: application/json'   
  -d '{
    "policy-mode": "testing",
    "mx-hosts": [
      "mx1.valimail.com",
      "mx2.valimail.com"
],
    "max-age": 86400
  }'

Replace {slug} with your Account Slug.
Replace <token> with the bearer token generated at Step 2.
Replace {domain} with the domain or subdomain you are creating the mta_sts_policy for.
Replace the Hosts under "mx-hosts" with the MX record hosts of your own domain/subdomain.

If successful, the response will contain the DNS TXT contents (mta-sts-record-text), a generated record ID, and the policy body. Always begin in testing mode, verify delivery, then switch to enforce when ready. Switching too soon might prevent emails from being delivered.

If you encounter the error "Failed to retrieve SSL certificate expiration date", please wait 5-10 minutes before retrying the API call. In some cases, certificate issuance may take several minutes to complete.

If the issue persists after retrying, please contact [email protected] for further assistance and troubleshooting.

5) Create TLS-RPT Policy

POST /accounts/{slug}/domains/{domain}/smtp_tls_policy

Example:

curl -sS -X POST https://api.valimail.com//accounts/{slug}/domains/{domain}/smtp_tls_policy
  -H 'Authorization: Bearer <token>'   
  -H 'Content-Type: application/json'   
  -d '{
  "rua-uris": [
    "mailto:[email protected]"
  ]
}'

Replace {slug} with your Account Slug.
Replace {domain} with the domain or subdomain you are creating the smtp_tls_policy for.
Replace <token> with the bearer token generated at Step 2.

The response includes dns-record-host and dns-record-type guidance, plus tls-rpt-record-text.

6) Validate Configuration

API checks

# MTA-STS policy (should show mta-sts-record-text and policy data)

curl -sS GET
https://api.valimail.com/accounts/{slug}/domains/{domain}/mta_sts_policy
  -H 'accept: application/json'
  -H 'Authorization: Bearer <token>'

Replace {slug} with your Account Slug.
Replace {domain} with your Domain Name.
Replace <token> with the bearer token generated at Step 2.

# TLS-RPT policy (configured may be true/false depending on DNS status)

curl -sS GET
https://api.valimail.com/accounts/{slug}/domains/{domain}/smtp_tls_policy
  -H 'accept: application/json' 
  -H 'Authorization: Bearer <token>'

Replace {slug} with your Account Slug.
Replace {domain} with your Domain Name.
Replace <token> with the bearer token generated at Step 2.

#DNS checks

Run the following lines in the Command terminal:

dig +short TXT _mta-sts.valimail.com

dig +short TXT _smtp._tls.valimail.com

curl -s https://mta-sts.your_domain/.well-known/mta-sts.txt

7) Retrieve TLS Summary & Failure Details (Optional)

TLS summary (paginated):

curl -sS GET 
https://api.valimail.com/accounts/{slug}/mta-sts/tls?start-date=YYYY-MM-DD&end-date=YYYY-MM-DD&limit=20&page=1
   -H 'accept: application/json' 
   -H 'Authorization: Bearer <token>'

Replace {slug} with your Account Slug.
Replace YYYY-MM-DD with the start and end dates.
Replace <token> with the bearer token generated at Step 2.

Failure details for a specific report-id/domain:

curl -sS GET
"https://api.valimail.com/accounts/{slug}/mta-sts/tls/failure-details?report-id={Report-ID}&domain-name={domain}" 
   -H 'accept: application/json' 
   -H 'Authorization: Bearer <token>'

Replace {slug} with your Account Slug.
Replace {domain} with your Domain Name.
Replace <token> with the bearer token generated at Step 2.
Replace {Report-ID} with the ID for the specific report you are searching for.

Update Policies

Switch to enforcement and/or update mx-hosts and max-age when ready:

curl -sS PUT  https://api.valimail.com/accounts/{slug}/domains/{domain}/mta_sts_policy
   -H 'accept: application/json' 
   -H 'Authorization: Bearer <token>' 
   -H 'Content-Type: application/json' 
   -d '{
   "policy-mode": "testing",
   "mx-hosts": [
      "mx1.valimail.com",
      "mx2.valimail.com"
   ],
   "max-age": 604800
 }'

Replace {slug} with your Account Slug.
Replace {domain} with your Domain Name.
Replace <token> with the bearer token generated at Step 2.
Update "policy-mode", "mx-hosts", or "max-age", if needed.

The mx-hosts above are examples; replace those values with your own.

Update TLS-RPT destination. This step is required only if you need to send reports to an additional destination.

curl -sS -X PUT https://api.valimail.com/accounts/{slug}/domains/{domain}/smtp_tls_policy
   -H 'accept: application/json' 
   -H 'Authorization: Bearer <token>' 
   -H 'Content-Type: application/json' 
   -d '{ 
   "rua-uris": [
     "mailto:[email protected]",
     "mailto:[email protected]"
   ] 
}'

Replace {slug} with your Account Slug.
Replace {domain} with your Domain Name.
Replace <token> with the bearer token generated at Step 2.
Replace [email protected] with an additional reporting address.

The [email protected] reporting address cannot be removed. You can only supplement the RUA tag with additional reporting addresses.

Appendix A: Sample MTA-STS Policy Text (Valimail.com)

version: STSv1
mode: enforce
mx: mx1.valimail.com
mx: mx2.valimail.com
max_age: 604800

Appendix B: Error Handling Cheatsheet

HTTP	Meaning	Typical Fix
400	Bad Request / missing param	Check body/required fields & types
401	Unauthorized	Refresh token / verify Authorization header
403	Forbidden	Confirm account/domain access
404	Not Found	Check slug/domain/reportID exists
409	Conflict	Duplicate resource (e.g., DKIM selector)
422	Unprocessable	Invalid value (e.g., policy-mode, rua format)
429	Rate limited	Back off & retry again
500	Server error	Retry and contact support if persistent

Appendix C: End-to-End (bash)

#Publish DNS CNAMEs for _mta-sts.<yourdomain>, mta-sts.<yourdomain>, and _smtp._tls.<yourdomain>.

#Authenticate and obtain a bearer token

API=https://api.valimail.com
SLUG=valimail
DOMAIN=valimail.com
CLIENT_ID=YOUR_CLIENT_ID
APP_ID=YOUR_APP_ID

TOKEN=$(curl -sS -X POST $API/auth -H 'Content-Type: application/json' -d "{"ClientID":"$CLIENT_ID","AppID":"$APP_ID"}" | python3 -c 'import sys,json;print(json.load(sys.stdin)["token"])')

# Ensure domain exists

curl -sS -X POST $API/accounts/$SLUG/domains   -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json'   -d "{"domain":"$DOMAIN"}"

# Create MTA-STS policy (testing first)

curl -sS -X POST https://api.valimail.com/accounts/{slug}/domains/{domain}/mta_sts_policy
  -H 'Authorization: Bearer <token>'   
  -H 'Content-Type: application/json'   
  -d '{
    "policy-mode": "testing",
    "mx-hosts": [
      "mx1.valimail.com",
      "mx2.valimail.com"
],
    "max-age": 86400
  }'

# Create TLS-RPT policy

curl -sS -X POST https://api.valimail.com//accounts/{slug}/domains/{domain}/smtp_tls_policy
  -H 'Authorization: Bearer <token>'   
  -H 'Content-Type: application/json'   
  -d '{
  "rua-uris": [
    "mailto:[email protected]"
  ]
}'

How to set up TLS reporting and MTA-STS

How to Implement MTA-STS Hosting and TLS Reporting with Valimail

Implement MTA-STS Hosting & TLS Reporting with Valimail - API Guide