Reports API

Access DMARC aggregate report data programmatically: individual reports with their per-source records, rolled-up statistics, file upload, and CSV export.

Endpoints

Returns reports for your organization, most recently ingested first, each with its full records array.

curl -X GET "https://api.ddmarc.com/api/v1/reports?domain_id=42&limit=50&offset=0" \
  -H "X-API-Key: $DDMARC_API_KEY"

[
  {
    "id": 9012,
    "domain_id": 42,
    "report_id": "16058034545453596399",
    "org_name": "google.com",
    "date_range_begin": "2026-07-17T00:00:00Z",
    "date_range_end": "2026-07-17T23:59:59Z",
    "policy_domain": "example.com",
    "policy_adkim": "r",
    "policy_aspf": "r",
    "policy_p": "reject",
    "policy_sp": null,
    "policy_pct": 100,
    "created_at": "2026-07-18T09:04:11Z",
    "records": [
      {
        "id": 551201,
        "source_ip": "209.85.220.41",
        "count": 843,
        "disposition": "none",
        "dkim_result": "pass",
        "spf_result": "pass",
        "header_from": "example.com",
        "envelope_from": "example.com",
        "envelope_to": null
      }
    ]
  }
]

Returns one report with all of its records, in the same shape as an element of the list response.

curl -X GET "https://api.ddmarc.com/api/v1/reports/9012" \
  -H "X-API-Key: $DDMARC_API_KEY"

{report_id} here is the integer idfield, not the reporter's report_id string.

Rolls up volume and pass rates over a time window, without you having to page through every report.

curl -X GET "https://api.ddmarc.com/api/v1/reports/stats/summary?domain_id=42&days=30" \
  -H "X-API-Key: $DDMARC_API_KEY"

{
  "total_reports": 184,
  "total_emails": 412903,
  "pass_rate": 98.4,
  "dkim_pass_rate": 99.1,
  "spf_pass_rate": 97.2,
  "top_sources": [
    { "source_ip": "209.85.220.41", "total": 180422 }
  ]
}

Rates are percentages rounded to one decimal place. A message counts as passing only when both DKIM and SPF pass.

Ingests a DMARC aggregate report you already hold as a file. Accepts raw XML, ZIP or GZIP as a multipart upload, up to 10 MB. Requires a key with write scope, and is limited to 30 uploads per minute.

curl -X POST "https://api.ddmarc.com/api/v1/reports/upload" \
  -H "X-API-Key: $DDMARC_API_KEY" \
  -F "file=@google.com!example.com!1752710400!1752796799.xml.gz"

{
  "message": "1 report(s) uploaded successfully",
  "uploaded": [
    {
      "report_id": "16058034545453596399",
      "domain": "example.com",
      "org_name": "google.com",
      "records_count": 12,
      "total_emails": 1843
    }
  ],
  "duplicates_skipped": 0,
  "no_domain_skipped": 0
}

If nothing lands, the call fails instead of returning an empty result: 409 when every report in the file was already ingested, and 400when the report's domain is not in your organization — add the domain first.

Report Object

A report carries no pre-computed totals or pass rate. Sum records[].count yourself, or use the summary endpoint.

Record Object

Raw reports tell you what happened; the failure-analysis endpoints tell you why. They live under their own prefix and each accept days(1–365, default 30) and an optional domain_id.

{
  "total_failures": 6604,
  "total_emails": 412903,
  "failure_rate": 1.6,
  "period_days": 30,
  "by_reason": [
    {
      "reason": "spf_only",
      "display_name": "SPF Only Failed",
      "count": 4102,
      "percentage": 62.1,
      "description": "SPF authentication failed but DKIM passed. Check SPF records and authorized senders."
    }
  ]
}

Continue to