Docs/API Reference

REST API v1

API Reference

Integrate DDMARC into your applications with our REST API. Manage domains, retrieve reports, and automate your email authentication workflow.

Fast

<100ms response time

Secure

TLS 1.3 encrypted

RESTful

JSON API format

Rate Limited

1000 req/min

Base URL

https://api.ddmarc.com/v1

All API requests must be made over HTTPS. Calls made over plain HTTP will fail.

Authentication

The DDMARC API uses API keys to authenticate requests. You can create and manage your API keys in the dashboard settings.

Authentication Header

Authorization: Bearer your_api_key_here

Keep your API key secure

Never expose your API key in client-side code or public repositories. Rotate keys regularly and use environment variables.

Example Request

curl -X GET "https://api.ddmarc.com/v1/domains" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Example Response

200 OKapplication/json

{
  "data": [
    {
      "id": "dom_abc123",
      "name": "example.com",
      "status": "verified",
      "dmarc_policy": "reject",
      "pass_rate": 98.5,
      "reports_last_30d": 1250,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "per_page": 20
  }
}

Endpoints

Domains

Method	Endpoint	Description
GET	/api/v1/domains	List all domains
POST	/api/v1/domains	Add a new domain
GET	/api/v1/domains/:id	Get domain details
PUT	/api/v1/domains/:id	Update domain settings
DELETE	/api/v1/domains/:id	Remove a domain
GET	/api/v1/domains/:id/dns	Get DNS records to configure
POST	/api/v1/domains/:id/verify	Verify domain ownership

Reports

Method	Endpoint	Description
GET	/api/v1/reports	List DMARC reports
GET	/api/v1/reports/:id	Get report details
GET	/api/v1/reports/aggregate	Get aggregated statistics
GET	/api/v1/reports/sources	List sending sources
GET	/api/v1/reports/failures	List authentication failures

Analytics

Method	Endpoint	Description
GET	/api/v1/analytics/summary	Get summary statistics
GET	/api/v1/analytics/trends	Get trend data over time
GET	/api/v1/analytics/geo	Get geographic distribution

Webhooks

Method	Endpoint	Description
GET	/api/v1/webhooks	List webhook endpoints
POST	/api/v1/webhooks	Create webhook endpoint
PUT	/api/v1/webhooks/:id	Update webhook
DELETE	/api/v1/webhooks/:id	Delete webhook
POST	/api/v1/webhooks/:id/test	Send test webhook

Rate Limiting

1,000

Requests per minute

100,000

Requests per day

429

Status when exceeded

Rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining) are included in every response. Enterprise plans have higher limits.

Error Codes

Code	Status	Description
400	Bad Request	Invalid request parameters
401	Unauthorized	Missing or invalid API key
403	Forbidden	Insufficient permissions
404	Not Found	Resource not found
429	Too Many Requests	Rate limit exceeded
500	Internal Error	Server error - contact support

SDKs & Libraries

Official client libraries to make integration easier:

Node.js

npm install @ddmarc/sdk

Python

pip install ddmarc

go get github.com/ddmarc/ddmarc-go

Documentation