API Reference for Programmatic Access

Integrate DMARCTrust data into your monitoring systems, dashboards, and automation workflows.

The DMARCTrust API provides RESTful access to your DMARC data. Retrieve reports, monitor domain health, and integrate email authentication insights into your existing tools.

This guide covers everything from generating API keys to making your first request, with examples in multiple languages.

Prerequisites

An active DMARCTrust subscription (Starter or Pro plan)
At least one domain configured in your account

Getting Started

Step 1: Generate an API Key

  1. Log in to your DMARCTrust dashboard
  2. Navigate to Settings (gear icon in the sidebar)
  3. Scroll to the API Keys section
  4. Click Create API Key
  5. Enter a descriptive name (e.g., "Production Server" or "Monitoring Script")
  6. Click Create

A modal will display your API key. Copy it immediately as it will only be shown once. The key format is:

dt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Store this key securely. Treat it like a password.

Step 2: Make Your First Request

Test your API key by fetching your account information:

curl -H "Authorization: Bearer YOUR_API_KEY" \ https://www.dmarctrust.com/api/v1/account

A successful response looks like:

{ "data": { "id": "usr_123", "email": "[email protected]", "reporting_address": "[email protected]", "subscription": { "plan": "pro", "status": "active", "included_domains": 5, "total_allowed_domains": 6, "active_domains": 4, "retention_days": 30 }, "usage": { "reports_30d": 156, "messages_30d": 12847 } }, "meta": { "request_id": "abc123-def456-..." } }

Authentication

All API requests require a Bearer token in the Authorization header:

Authorization: Bearer dt_live_your_api_key_here

Error Responses

Invalid or missing API key (401):

{ "error": { "code": "invalid_api_key", "message": "Invalid or missing API key", "request_id": "..." } }

Subscription required (403):

{ "error": { "code": "subscription_required", "message": "API access requires an active subscription...", "request_id": "..." } }

Rate Limits

Client Type Limit
Authenticated (with API key) 30 requests/minute
Unauthenticated 2 requests/minute per IP

When rate limited, you receive a 429 response with retry information:

{ "error": { "code": "rate_limit_exceeded", "message": "Rate limit exceeded. Please wait before making more requests.", "retry_after": 45 } }

Headers included: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

API Reference

Base URL: https://www.dmarctrust.com/api/v1

Account

Get Account Information

GET /account

Returns your account details, subscription status, and usage statistics.

Domains

List All Domains

GET /domains

Returns all domains in your account.

{ "data": [ { "id": "ud_19", "domain": "example.com", "active": true, "dns_status": "valid", "dns_status_message": "DNS Verified", "activated_at": "2025-10-13T08:58:52Z", "created_at": "2025-10-13T08:58:48Z", "reporting_address": "[email protected]" } ], "meta": { "total_count": 4, "has_more": false, "next_cursor": null } }

Get Single Domain

GET /domains/:id

Returns detailed information about a specific domain, including 30-day statistics.

Add a Domain

POST /domains

Body: {"domain": "newdomain.com"}

Domain Actions

  • POST /domains/:id/activate - Activate a domain to start receiving reports
  • POST /domains/:id/deactivate - Deactivate a domain
  • POST /domains/:id/refresh_dns - Trigger an immediate DNS check

Domain DNS Records

Get DNS Records

GET /domains/:id/dns

Returns the current DMARC, SPF, and BIMI DNS records for a domain.

{ "data": { "domain": "example.com", "last_checked_at": "2025-01-17T16:20:01Z", "dmarc": { "status": "valid", "record": "v=DMARC1; p=quarantine; rua=mailto:...", "policy": "quarantine", "dmarctrust_configured": true }, "spf": { "status": "valid", "record": "v=spf1 include:_spf.google.com -all", "all_mechanism": "-all" }, "bimi": { "status": "valid", "record": "v=BIMI1; l=https://example.com/logo.svg" } } }

Domain Statistics

Get Daily Statistics

GET /domains/:id/stats

Query Parameters:

Parameter Default Description
start_date 30 days ago Start date (YYYY-MM-DD)
end_date today End date (YYYY-MM-DD)

Domain Sources

Get Email Sources

GET /domains/:id/sources

Returns email sources (senders) that have sent email on behalf of your domain.

Query Parameters:

Parameter Default Description
range 7d Time range: "48h", "7d", or "30d"
date - Specific date (YYYY-MM-DD), overrides range

Reports

List Reports

GET /reports

Returns DMARC aggregate reports received for your domains.

Query Parameters:

Parameter Description
domain_id Filter by domain ID (e.g., "ud_19")
domain Filter by domain name (partial match)
sender_org Filter by sender organization (partial match)
start_date Filter reports created after this date
end_date Filter reports created before this date
limit Results per page (default: 25, max: 100)
cursor Pagination cursor for next page

Get Report Details

GET /reports/:id

Returns full details of a specific report, including individual record entries with source IPs, hostnames, and authentication results.

Pagination

List endpoints use cursor-based pagination. Check the meta object in responses:

{ "meta": { "total_count": 915, "has_more": true, "next_cursor": "eyJpZCI6OTE0LC..." } }

To fetch the next page, pass the cursor:

GET /reports?cursor=eyJpZCI6OTE0LC...

ID Formats

Resources use prefixed IDs for clarity:

Resource Prefix Example
User usr_ usr_123
Domain ud_ ud_19
Report rpt_ rpt_915

When making requests, you can use either the prefixed ID or the raw numeric ID:

GET /domains/ud_19 GET /domains/19

Error Handling

All errors follow a consistent format:

{ "error": { "code": "error_code", "message": "Human-readable description", "request_id": "abc123-..." } }

Common error codes:

Code Status Description
invalid_api_key 401 API key is missing or invalid
subscription_required 403 No active subscription
not_found 404 Resource does not exist
invalid_date 400 Date parameter is malformed
rate_limit_exceeded 429 Too many requests

Code Examples

Python

import requests API_KEY = "dt_live_your_key_here" BASE_URL = "https://www.dmarctrust.com/api/v1" headers = {"Authorization": f"Bearer {API_KEY}"} # Get all domains response = requests.get(f"{BASE_URL}/domains", headers=headers) domains = response.json()["data"] for domain in domains: print(f"{domain['domain']}: {domain['dns_status']}") # Get reports for a specific domain response = requests.get( f"{BASE_URL}/reports", headers=headers, params={"domain_id": "ud_19", "limit": 50} ) reports = response.json()["data"]

JavaScript (Node.js)

const API_KEY = "dt_live_your_key_here"; const BASE_URL = "https://www.dmarctrust.com/api/v1"; async function getDomains() { const response = await fetch(`${BASE_URL}/domains`, { headers: { Authorization: `Bearer ${API_KEY}` } }); const { data } = await response.json(); return data; } async function getReports(domainId, limit = 25) { const url = new URL(`${BASE_URL}/reports`); url.searchParams.set("domain_id", domainId); url.searchParams.set("limit", limit); const response = await fetch(url, { headers: { Authorization: `Bearer ${API_KEY}` } }); return response.json(); }

Ruby

require "net/http" require "json" API_KEY = "dt_live_your_key_here" BASE_URL = "https://www.dmarctrust.com/api/v1" def api_request(endpoint, params = {}) uri = URI("#{BASE_URL}#{endpoint}") uri.query = URI.encode_www_form(params) if params.any? request = Net::HTTP::Get.new(uri) request["Authorization"] = "Bearer #{API_KEY}" response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end JSON.parse(response.body) end # Get account info account = api_request("/account") puts "Email: #{account['data']['email']}" # Get domains domains = api_request("/domains") domains["data"].each do |domain| puts "#{domain['domain']}: #{domain['dns_status']}" end

Managing API Keys

Viewing Keys

All your API keys are listed in Settings > API Keys. You can see:

  • Key name
  • Key prefix (first 12 characters)
  • Creation date
  • Last used date

Revoking Keys

To revoke an API key:

  1. Go to Settings > API Keys
  2. Find the key you want to revoke
  3. Click the trash icon
  4. Confirm the revocation

Revoked keys immediately stop working. Any applications using that key will receive 401 Unauthorized responses.

Best Practices

  • Use descriptive names - Name keys after their purpose (e.g., "Production Monitoring", "CI/CD Pipeline")
  • Rotate regularly - Create new keys and revoke old ones periodically
  • One key per application - Use separate keys for different applications to enable granular revocation
  • Never commit keys - Use environment variables or secrets management
  • Monitor usage - Check "Last Used" dates to identify unused keys for cleanup

Need help? If you encounter issues with the API, contact support through the dashboard with the request_id from error responses. This helps us debug your specific request.

Was this page helpful? Send us feedback

← Back to Home Start now