Skip to content

API Documentation

Programmatic access to DMARC.WS for domain management, DNS lookups, and report retrieval.

API key access requires an Enterprise or MSP plan

Base URL

https://api.dmarc.ws/v1

Authentication

JWT Token (User sessions)

Authorization: Bearer eyJhbGciOi...

API Key (Programmatic access)

X-API-Key: dmws_k1_abc123...

Create API keys in Dashboard → API Keys. Keys are scoped to your user and can access all your organizations.

Rate Limits

Free

100 req/hr

Enhanced

1,000 req/hr

Enterprise

10,000 req/hr

Endpoints

POST
/auth/signup

Register a new user account

None
POST
/auth/login

Log in and receive a JWT

None
GET
/auth/me

Get current user profile

JWT
POST
/dmarc/check

Look up DMARC DNS record

None
POST
/spf/check

Look up SPF DNS record

None
POST
/dkim/check

Look up DKIM DNS record

None
POST
/bimi/check

Look up BIMI DNS record

None
POST
/mta-sts/check

Check MTA-STS DNS + policy

None
GET
/orgs/:orgId/domains

List organization domains

JWT / API Key
POST
/orgs/:orgId/domains

Add a domain

JWT / API Key
PATCH
/orgs/:orgId/domains/:id

Update domain settings

JWT / API Key
DELETE
/orgs/:orgId/domains/:id

Remove a domain

JWT / API Key
POST
/orgs/:orgId/domains/:id/validate

Validate domain DNS

JWT / API Key
GET
/orgs/:orgId/domains/:id/stats

Get domain report stats

JWT / API Key
GET
/orgs/:orgId/domains/:id/reports

List DMARC reports

JWT / API Key
GET
/orgs/:orgId/domains/:id/health

Get DNS health + score

JWT / API Key
GET
/orgs/:orgId/domains/:id/policy-history

Get DMARC policy change history

JWT / API Key
GET
/orgs/:orgId/domains/:id/geo

Get geographic sender distributionEnhanced+

JWT / API Key
GET
/orgs/:orgId/domains/:id/failure-reports

List RUF failure reportsEnhanced+

JWT / API Key
GET
/orgs/:orgId/domains/:id/tls-reports

List TLS reportsEnhanced+

JWT / API Key
GET
/orgs/:orgId/domains/:id/export-pdf

Download PDF reportEnhanced+

JWT / API Key
GET
/orgs/:orgId/domains/:id/export-csv

Download CSV exportEnhanced+

JWT / API Key
GET
/orgs/:orgId/domains/:id/services

Detect sending servicesEnhanced+

JWT / API Key
GET
/orgs/:orgId/domains/:id/ai-insights

Get cached AI analysis

JWT / API Key
POST
/orgs/:orgId/domains/:id/ai-insights

Generate AI analysis (SSE stream)

JWT / API Key
GET
/orgs/:orgId/domains/:id/sender-auth

List sender authorizationsEnhanced+

JWT / API Key
PUT
/orgs/:orgId/domains/:id/sender-auth

Upsert sender authorizationEnhanced+

JWT / API Key
GET
/orgs/:orgId/audit-log

Get audit log entriesEnterprise

JWT / API Key
GET
/orgs/:orgId/webhooks

List webhooksEnhanced+

JWT / API Key
POST
/orgs/:orgId/webhooks

Create webhookEnhanced+

JWT / API Key
GET
/v1/health

API health check

None

Response Format

Success

{
  "data": {
    "domains": [...]
  },
  "requestId": "clx9a2b..."
}

Error

{
  "error": "Domain limit reached",
  "requestId": "clx9a2b..."
}

HTTP Status Codes

200

Success

Request completed successfully.

400

Validation Error

Request body or query parameters failed Zod validation.

401

Unauthorized

Missing, expired, or invalid JWT / API key.

402

Plan Upgrade Required

Feature requires a higher plan (Enhanced+ or Enterprise).

404

Not Found

Resource does not exist or is not accessible to your account.

429

Rate Limited

Too many requests. Retry after the time in the Retry-After header.

Pagination

All list endpoints support pagination via query parameters. Results are returned in reverse-chronological order by default.

page

Page number, starting at 1 (default).

limit

Items per page, max 100. Default 50.

GET /v1/orgs/:orgId/domains?page=2&limit=25

// Response includes a pagination object:
{
  "data": {
    "domains": [...],
    "pagination": {
      "page": 2,
      "limit": 25,
      "total": 73,
      "pages": 3
    }
  }
}

Request / Response Examples

Expand each endpoint to see a complete curl example and sample JSON response.

POST /dmarc/check

Look up a DMARC DNS record (no auth required)

Request

                    curl -X POST https://api.dmarc.ws/v1/dmarc/check \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "example.com"
  }'

Response

                    {
  "data": {
    "domain": "example.com",
    "found": true,
    "record": "v=DMARC1; p=reject; rua=mailto:dmarc@example.com; pct=100",
    "parsed": {
      "v": "DMARC1",
      "p": "reject",
      "rua": "mailto:dmarc@example.com",
      "pct": "100"
    }
  },
  "requestId": "clx9a2b3c0001..."
}
GET /orgs/:orgId/domains

List all domains in your organization

Request

                    curl https://api.dmarc.ws/v1/orgs/org_abc123/domains \
  -H "X-API-Key: dmws_k1_your_key_here"

Response

                    {
  "data": {
    "domains": [
      {
        "id": "dom_1a2b3c",
        "domain": "example.com",
        "validated": true,
        "createdAt": "2025-06-01T12:00:00.000Z",
        "lastReportAt": "2025-06-15T08:30:00.000Z"
      },
      {
        "id": "dom_4d5e6f",
        "domain": "mail.example.org",
        "validated": false,
        "createdAt": "2025-06-10T09:00:00.000Z",
        "lastReportAt": null
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 2,
      "pages": 1
    }
  },
  "requestId": "clx9b4d5e0002..."
}
GET /orgs/:orgId/domains/:id/stats

Retrieve aggregated report statistics for a domain

Request

                    curl https://api.dmarc.ws/v1/orgs/org_abc123/domains/dom_1a2b3c/stats \
  -H "X-API-Key: dmws_k1_your_key_here"

Response

                    {
  "data": {
    "totalReports": 142,
    "totalMessages": 58340,
    "passRate": 97.2,
    "dkimAlignRate": 98.1,
    "spfAlignRate": 96.8,
    "failedMessages": 1632,
    "periodStart": "2025-05-01T00:00:00.000Z",
    "periodEnd": "2025-06-15T23:59:59.000Z"
  },
  "requestId": "clx9c6f7g0003..."
}
GET /orgs/:orgId/domains/:id/health

Get DNS health score and detailed check results

Request

                    curl https://api.dmarc.ws/v1/orgs/org_abc123/domains/dom_1a2b3c/health \
  -H "X-API-Key: dmws_k1_your_key_here"

Response

                    {
  "data": {
    "score": 85,
    "grade": "B+",
    "results": {
      "dmarc": {
        "status": "pass",
        "record": "v=DMARC1; p=reject; rua=mailto:dmarc@example.com",
        "policy": "reject"
      },
      "spf": {
        "status": "pass",
        "record": "v=spf1 include:_spf.google.com ~all",
        "lookups": 4
      },
      "dkim": {
        "status": "pass",
        "selectors": ["google", "s1"],
        "validKeys": 2
      },
      "bimi": {
        "status": "missing",
        "record": null
      },
      "mtaSts": {
        "status": "pass",
        "mode": "enforce"
      }
    },
    "checkedAt": "2025-06-15T12:00:00.000Z"
  },
  "requestId": "clx9d8h9i0004..."
}
PUT /orgs/:orgId/domains/:id/sender-auth

Upsert a sender authorization for a domain (Enhanced+)

Request

                    curl -X PUT https://api.dmarc.ws/v1/orgs/org_abc123/domains/dom_1a2b3c/sender-auth \
  -H "Content-Type: application/json" \
  -H "X-API-Key: dmws_k1_your_key_here" \
  -d '{
    "sourceIp": "198.51.100.25",
    "service": "Mailchimp",
    "status": "authorized",
    "note": "Marketing email campaigns"
  }'

Response

                    {
  "data": {
    "id": "sa_7g8h9i",
    "domainId": "dom_1a2b3c",
    "sourceIp": "198.51.100.25",
    "service": "Mailchimp",
    "status": "authorized",
    "note": "Marketing email campaigns",
    "createdAt": "2025-06-15T14:00:00.000Z",
    "updatedAt": "2025-06-15T14:00:00.000Z"
  },
  "requestId": "clx9e0j1k0005..."
}

Quick Example

# Check a DMARC record (no auth required)
curl -X POST https://api.dmarc.ws/v1/dmarc/check \
  -H "Content-Type: application/json" \
  -d '{"domain": "google.com"}'

# List your domains (API key required)
curl https://api.dmarc.ws/v1/orgs/YOUR_ORG_ID/domains \
  -H "X-API-Key: dmws_k1_your_key_here"