DMARC Management API

The DMARC Management API provides full programmatic control over your DMARC monitoring.

Method	Endpoint	Description
GET	/api/v1/dmarc/domains	List all domains
POST	/api/v1/dmarc/domains	Add a new domain
GET	/api/v1/dmarc/domains/{id}	Get domain details
DELETE	/api/v1/dmarc/domains/{id}	Remove domain + all reports
POST	/api/v1/dmarc/domains/{id}/verify	Verify domain ownership (DNS)
GET	/api/v1/dmarc/domains/{id}/reports	Get aggregate reports (paginated)
GET	/api/v1/dmarc/domains/{id}/tls-reports	Get TLS-RPT reports (TLS failures)
GET	/api/v1/dmarc/domains/{id}/stats	Get pass rates & top senders

Setup Workflow

1. POST /api/v1/dmarc/domains - Add domain, receive DNS setup instructions
2. Add TXT records to your DNS (verification + DMARC)
3. POST /api/v1/dmarc/domains/{id}/verify - Verify domain ownership
4. Wait 24-72h for first reports to arrive
5. GET /api/v1/dmarc/domains/{id}/reports - Retrieve reports
6. GET /api/v1/dmarc/domains/{id}/stats - Get statistics

Add Domain

POST /api/v1/dmarc/domains
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{ "domain": "example.com" }

Response:
{
  "success": true,
  "data": {
    "id": "abc-123",
    "domain": "example.com",
    "verified": false,
    "reportEmail": "d-xxx@dmarc.provider.tools",
    "dmarcRecord": "v=DMARC1; p=none; rua=mailto:...; ruf=mailto:...",
    "setup": {
      "step1": { "host": "_provider-tools.example.com", "type": "TXT", "value": "provider-tools-verify=..." },
      "step2": { "host": "_dmarc.example.com", "type": "TXT", "value": "v=DMARC1; ..." },
      "step3": { "method": "POST", "url": "/api/v1/dmarc/domains/abc-123/verify" }
    }
  }
}

Verify Domain

POST /api/v1/dmarc/domains/{domainId}/verify
Authorization: Bearer YOUR_TOKEN

// Success:
{ "success": true, "verified": true, "message": "Domain verified successfully!" }

// Not yet:
{ "success": true, "verified": false, "expected": { "host": "...", "value": "..." }, "found": [] }

Get Statistics

GET /api/v1/dmarc/domains/{domainId}/stats?days=30
Authorization: Bearer YOUR_TOKEN

Response:
{
  "data": {
    "totalMessages": 52340,
    "dkimPassRate": 97,
    "spfPassRate": 95,
    "topSenders": [
      { "organization": "google.com", "messages": 30000, "dkimPassRate": 99, "spfPassRate": 98 }
    ]
  }
}

Get TLS-RPT Reports

GET /api/v1/dmarc/domains/{domainId}/tls-reports?days=30
Authorization: Bearer YOUR_TOKEN

Response:
{
  "data": {
    "domain": "example.com",
    "tlsRptRecord": "v=TLSRPTv1; rua=mailto:t-xxx@dmarc.provider.tools",
    "summary": {
      "totalReports": 12,
      "totalSuccessfulSessions": 45230,
      "totalFailedSessions": 3,
      "failureRate": 0,
      "topReporters": [{"organization": "google.com", "success": 30000, "fail": 1}]
    },
    "reports": [{
      "orgName": "google.com", "policyType": "sts",
      "totalSuccessful": 5000, "totalFailure": 0
    }]
  }
}

TLS-RPT DNS Record: _smtp._tls.example.com TXT "v=TLSRPTv1; rua=mailto:t-xxx@dmarc.provider.tools"

Delete Domain

DELETE /api/v1/dmarc/domains/{domainId}
Authorization: Bearer YOUR_TOKEN

// WARNING: Permanently deletes domain and ALL reports!
{ "success": true, "message": "Domain example.com removed" }