REST API

Domains API

Programmatically manage domains in your DDMARC account. Add new domains, verify ownership, configure settings, and retrieve DNS records.

Endpoints

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

GET

List All Domains

Retrieve a list of all domains in your organization.

GET /api/v1/domains

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

Response200 OK

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

POST

Add New Domain

Add a new domain to your organization for DMARC monitoring.

POST /api/v1/domains

curl -X POST "https://api.ddmarc.com/v1/domains" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "example.com"
  }'

Request Body

Field	Type	Required	Description
domain	string	Required	The domain name to add

Response201 Created

{
  "data": {
    "id": "dom_xyz789",
    "domain": "example.com",
    "status": "pending",
    "verification_token": "ddmarc-verify-abc123",
    "created_at": "2024-01-20T15:00:00Z"
  }
}

GET

Get Domain Details

Retrieve detailed information about a specific domain.

GET /api/v1/domains/:id

curl -X GET "https://api.ddmarc.com/v1/domains/dom_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST

Verify Domain Ownership

Trigger domain verification. The domain must have the DMARC record configured.

POST /api/v1/domains/:id/verify

curl -X POST "https://api.ddmarc.com/v1/domains/dom_abc123/verify" \
  -H "Authorization: Bearer YOUR_API_KEY"

Success Response200 OK

{
  "data": {
    "id": "dom_abc123",
    "domain": "example.com",
    "status": "verified",
    "verified_at": "2024-01-20T15:30:00Z"
  },
  "message": "Domain verified successfully"
}

GET

Get DNS Records

Retrieve the DNS records that should be configured for a domain.

GET /api/v1/domains/:id/dns

curl -X GET "https://api.ddmarc.com/v1/domains/dom_abc123/dns" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response200 OK

{
  "data": {
    "dmarc": {
      "host": "_dmarc",
      "type": "TXT",
      "value": "v=DMARC1; p=none; rua=mailto:dmarc@rua.ddmarc.com"
    },
    "mta_sts": {
      "host": "_mta-sts",
      "type": "TXT",
      "value": "v=STSv1; id=20240120"
    },
    "verification": {
      "host": "_ddmarc-verify",
      "type": "TXT",
      "value": "ddmarc-verify-abc123"
    }
  }
}

DELETE

Delete Domain

Remove a domain from your organization. This will delete all associated reports.

DELETE /api/v1/domains/:id

curl -X DELETE "https://api.ddmarc.com/v1/domains/dom_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Warning: This action is irreversible. All reports and data for this domain will be permanently deleted.

Domain Object

Field	Type	Description
id	string	Unique domain identifier
domain	string	The domain name
status	string	pending, verified, or failed
dmarc_policy	string	Current DMARC policy (none, quarantine, reject)
pass_rate	number	Authentication pass rate (0-100)
created_at	string	ISO 8601 creation timestamp
verified_at	string	ISO 8601 verification timestamp

Documentation