gh-christianlouis-dmarq/docs/reference/api.md

API Reference

DMARQ provides a comprehensive REST API that allows you to integrate with external systems and build custom workflows.

Authentication

Stable automation endpoints live under /api/v1/public and require a scoped API token in the X-API-Key header. Admin endpoints continue to require an administrator session or admin API key.

API Keys

To use the API, you need to generate an API key:

Create scoped API tokens with:

POST /api-tokens

Request:

{
  "name": "SIEM export",
  "scopes": ["reports:read", "posture:read", "tls-reports:read"]
}

The raw token is returned once. DMARQ stores only a hash, prefix, scopes, and usage audit metadata.

Authentication Header

Include your API key in all requests using the X-API-Key header:

X-API-Key: your_api_key_here

Base URL

The base URL for all API endpoints is:

https://your-dmarq-instance.com/api/v1

Replace your-dmarq-instance.com with your actual DMARQ hostname.

API Endpoints

Stable Public API

These endpoints are read-only and intended for automation. They are versioned through the /public path and avoid UI-specific payloads.

Endpoint	Required scope	Purpose
GET /public/domains	reports:read	Domain report and DNS summary list
GET /public/domains/{domain_id}/reports	reports:read	Recent DMARC aggregate report summaries
GET /public/domains/{domain_id}/posture	posture:read	Evidence-first posture dashboard payload
GET /public/tls-reports/summary	tls-reports:read	SMTP TLS report trends and failure groups

Successful public API calls update the token's last-used timestamp, source IP, and usage count for auditing.

API Tokens

List API Tokens

GET /api-tokens

Returns token metadata, scopes, activity state, and audit fields. Raw token secrets and hashes are never returned.

Create API Token

POST /api-tokens

Creates a scoped read-only token. The response includes token once and metadata for future list/revoke operations.

Revoke API Token

DELETE /api-tokens/{token_id}

Deactivates a token immediately. Revoked tokens can no longer access public API endpoints.

Domains

List Domains

GET /domains

Returns a list of all domains in your DMARQ instance.

Example Response:

{
  "domains": [
    {
      "id": "1",
      "name": "example.com",
      "added_at": "2025-01-15T14:30:00Z",
      "status": "active",
      "compliance_rate": 87.5
    },
    {
      "id": "2",
      "name": "example.org",
      "added_at": "2025-01-16T09:15:00Z",
      "status": "active",
      "compliance_rate": 95.2
    }
  ],
  "total": 2
}

Get Domain Details

GET /domains/{domain_id}

Returns details for a specific domain.

Example Response:

{
  "id": "1",
  "name": "example.com",
  "added_at": "2025-01-15T14:30:00Z",
  "status": "active",
  "compliance_rate": 87.5,
  "reports_count": 45,
  "last_report_date": "2025-04-01T00:00:00Z",
  "dns_records": {
    "spf": "v=spf1 include:_spf.example.com ~all",
    "dmarc": "v=DMARC1; p=none; rua=mailto:dmarc@example.com",
    "mx": ["10 mail.example.com"]
  }
}

Get BIMI Posture

GET /domains/{domain_id}/dns/bimi

Returns the cached BIMI TXT posture for the default selector, including the queried DNS name, record text, logo URL, certificate URL, warnings, and errors.

Get Posture Dashboard

GET /domains/{domain_id}/posture

Returns the evidence-first posture dashboard for one domain. The response contains the posture score, coverage for DMARC, SPF, DKIM, MTA-STS, and BIMI, actionable recommendations, recent provider-backed DNS drift summaries, and short operator playbooks. Recommendation and playbook evidence links point back to the page section that triggered the finding.

Add Domain

POST /domains

Adds a new domain to DMARQ.

Request Body:

{
  "name": "newdomain.com"
}

Example Response:

{
  "id": "3",
  "name": "newdomain.com",
  "added_at": "2025-04-21T14:22:00Z",
  "status": "active"
}

Remove Domain

DELETE /domains/{domain_id}

Removes a domain from DMARQ.

Example Response:

{
  "success": true,
  "message": "Domain removed successfully"
}

Reports

List Reports

GET /reports

Returns a list of DMARC reports.

Query Parameters:

• domain_id - Filter by domain
• start_date - Filter by start date (YYYY-MM-DD)
• end_date - Filter by end date (YYYY-MM-DD)
• source_org - Filter by source organization
• page - Page number for pagination (default: 1)
• limit - Number of results per page (default: 25, max: 100)

Example Response:

{
  "reports": [
    {
      "id": "1",
      "domain": "example.com",
      "report_id": "google.com:1234567890",
      "date_range": {
        "begin": "2025-04-01T00:00:00Z",
        "end": "2025-04-01T23:59:59Z"
      },
      "source_org": "google.com",
      "source_email": "noreply-dmarc-support@google.com",
      "message_count": 156,
      "pass_count": 142,
      "fail_count": 14,
      "pass_rate": 91.0
    }
  ],
  "total": 245,
  "page": 1,
  "limit": 25,
  "total_pages": 10
}

Get Report Details

GET /reports/{report_id}

Returns details for a specific report.

Example Response:

{
  "id": "1",
  "domain": "example.com",
  "report_id": "google.com:1234567890",
  "date_range": {
    "begin": "2025-04-01T00:00:00Z",
    "end": "2025-04-01T23:59:59Z"
  },
  "source_org": "google.com",
  "source_email": "noreply-dmarc-support@google.com",
  "policy_published": {
    "domain": "example.com",
    "adkim": "r",
    "aspf": "r",
    "p": "none",
    "sp": "none",
    "pct": 100
  },
  "records": [
    {
      "source_ip": "192.0.2.1",
      "count": 34,
      "policy_evaluated": {
        "disposition": "none",
        "dkim": "pass",
        "spf": "pass"
      },
      "identifiers": {
        "header_from": "example.com",
        "envelope_from": "bounces.example.com"
      },
      "auth_results": {
        "dkim": {
          "domain": "example.com",
          "selector": "default",
          "result": "pass"
        },
        "spf": {
          "domain": "bounces.example.com",
          "result": "pass"
        }
      }
    }
  ]
}

Upload Report

POST /reports/upload

Uploads a new DMARC report for processing.

Request Body:

• Multipart form with file upload (XML, ZIP, or GZ format)

Example Response:

{
  "success": true,
  "message": "Report uploaded and queued for processing",
  "task_id": "abcd1234"
}

TLS Reports

Upload TLS Report

POST /tls-reports/upload

Uploads an SMTP TLS Reporting aggregate attachment. Supported file types are .json, .json.gz, and .zip.

Example Response:

{
  "success": true,
  "report_id": "tls-report-20260520",
  "policies_created": 1,
  "policies_skipped": 0,
  "duplicate": false,
  "message": "TLS report imported."
}

Summarize TLS Reports

GET /tls-reports/summary?domain=example.com&days=30

Returns aggregate TLS trends, top failure causes, affected domains, and the privacy controls for stored TLS-RPT data.

Statistics

Compliance Summary

GET /stats/{domain_id}/compliance

Returns compliance statistics for a domain.

Query Parameters:

• start_date - Start date (YYYY-MM-DD)
• end_date - End date (YYYY-MM-DD)
• interval - Aggregation interval (day, week, month)

Example Response:

{
  "domain": "example.com",
  "date_range": {
    "start": "2025-03-01",
    "end": "2025-04-01"
  },
  "overall": {
    "total_messages": 4586,
    "pass": 4102,
    "fail": 484,
    "compliance_rate": 89.4,
    "spf_aligned": 4220,
    "dkim_aligned": 4315
  },
  "trend": [
    {
      "date": "2025-03-01",
      "total": 152,
      "pass": 132,
      "fail": 20,
      "rate": 86.8
    },
    // Additional days...
  ]
}

Source Summary

GET /stats/{domain_id}/sources

Returns statistics about sending sources.

Example Response:

{
  "domain": "example.com",
  "top_sources": [
    {
      "source_ip": "192.0.2.1",
      "source_domain": "mail-server.example.com",
      "message_count": 2156,
      "pass_count": 2156,
      "fail_count": 0,
      "pass_rate": 100.0
    },
    // Additional sources...
  ]
}

System

System Status

GET /system/status

Returns the status of the DMARQ system.

Example Response:

{
  "status": "healthy",
  "version": "1.2.0",
  "uptime": 1234567,
  "database": "connected",
  "imap": "connected",
  "domains_count": 5,
  "reports_count": 12543
}

Rate Limiting

The API is rate limited to prevent abuse:

• 60 requests per minute for most endpoints
• 10 requests per minute for upload endpoints

If you exceed these limits, you'll receive a 429 Too Many Requests response.

Errors

The API uses standard HTTP status codes to indicate the success or failure of requests:

• 200 OK - Request succeeded
• 201 Created - Resource created successfully
• 400 Bad Request - Invalid request parameters
• 401 Unauthorized - Missing or invalid API key
• 403 Forbidden - API key doesn't have sufficient permissions
• 404 Not Found - Resource not found
• 429 Too Many Requests - Rate limit exceeded
• 500 Internal Server Error - Server error

Error responses include a JSON body with details:

{
  "error": "validation_error",
  "message": "Invalid domain name format",
  "details": {
    "field": "name",
    "reason": "Does not match domain name pattern"
  }
}

SDKs and Integrations

DMARQ provides client libraries for common programming languages:

• Python: dmarq-python
• JavaScript/Node.js: dmarq-node

API Versioning

The API uses versioning in the URL path (/api/v1/) to ensure backward compatibility. When breaking changes are necessary, we'll introduce a new version (e.g., /api/v2/).

Webhooks

DMARQ can notify your systems about events via webhooks:

1. Navigate to Settings > API Access > Webhooks
2. Click Add Webhook
3. Configure:
   • Destination URL
   • Secret token (for verification)
   • Events to subscribe to

Supported events:

• report.processed - When a new report is processed
• compliance.threshold - When compliance falls below threshold
• domain.added - When a domain is added
• domain.removed - When a domain is removed