Agg reports
List, Search and Paginate the Aggregate Reports. Plus get all the details of an individual Aggregat Report.

Supported Formats

Errors

Examples

{
  "reports": [
    {
      "id": 1,
      "raw_xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>...",
      "org_name": "google.com",
      "email": "noreply-dmarc-support@google.com",
      "extra_contact_info": "https://support.google.com/a/answer/2466580",
      "report_id": "1627703331531660819",
      "date_begin": "2019-02-10T00:00:00.000Z",
      "date_end": "2019-02-10T23:59:59.000Z",
      "policy_domain": "twlnet.com",
      "dkim_alignment": "s",
      "spf_alignment": "s",
      "domain_policy": "reject",
      "subdomain_policy": "reject",
      "percentage": 100,
      "domain_id": 1,
      "created_at": "2019-10-10T11:47:11.613Z",
      "updated_at": "2019-10-10T11:47:11.613Z",
      "records_count": null,
      "report_email_message_id": null
    },
    {
      "id": 2,
      "raw_xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>...",
      "org_name": "google.com",
      "email": "noreply-dmarc-support@google.com",
      "extra_contact_info": "https://support.google.com/a/answer/2466580",
      "report_id": "949348866075514174",
      "date_begin": "2019-02-12T00:00:00.000Z",
      "date_end": "2019-02-12T23:59:59.000Z",
      "policy_domain": "borschow.com",
      "dkim_alignment": "r",
      "spf_alignment": "r",
      "domain_policy": "reject",
      "subdomain_policy": "reject",
      "percentage": 100,
      "domain_id": 1,
      "created_at": "2019-10-10T11:48:07.386Z",
      "updated_at": "2019-10-10T11:48:07.386Z",
      "records_count": null,
      "report_email_message_id": null
    },
    ...
  ],
  "meta": {
    "total_reports": 5,
    "current_page": 1,
    "per_page": 25,
    "total_pages": 2
  }
}

Params

Each record’s ip_address now includes an email_service block when the source IP matches a known mail provider in our research database. See the agg_reports/:id endpoint description for the block shape and semantics — both endpoints return the same enrichment.

Supported Formats

Errors

Examples

{
  "records": [
    {
      "id": 1,
      "count": 1,
      "disposition": "none",
      "dkim_status": "pass",
      "spf_status": "pass",
      "reason": "",
      "org_name": "google.com",
      "header_from": "twlnet.com",
      "dmarc_compliance": "Compliant",
      "is_in_spf_record": true,
      "created_at": "2019-02-10T18:42:17.000Z",
      "updated_at": "2019-02-10T18:42:17.000Z",
      "auth_results": [
        {
          "id": 1,
          "type": "Dkim",
          "domain": "twlnet.com",
          "result": "pass",
          "selector": "201810",
          "created_at": "2019-02-10T18:42:17.000Z",
          "updated_at": "2019-02-10T18:42:17.000Z"
        },
        {
          "id": 2,
          "type": "Spf",
          "domain": "twlnet.com",
          "result": "pass",
          "selector": "",
          "created_at": "2019-02-10T18:42:17.000Z",
          "updated_at": "2019-02-10T18:42:17.000Z"
        }
      ],
      "ip_address": {
        "id": 3,
        "sane_source_ip": "87.106.127.28",
        "blacklisted": 0,
        "ptr": "ec2-52-30-166-6.eu-west-1.compute.amazonaws.com",
        "country": "de",
        "created_at": "2019-02-09T11:03:55.000Z",
        "updated_at": "2026-04-15T08:21:33.000Z",
        "email_service": {
          "id": 1042,
          "name": "Google",
          "ptr_domain": "google.com",
          "service_type": "sender",
          "supports_dkim": true,
          "supports_spf": true,
          "supports_dmarc": true,
          "dkim_setup_url": "https://support.google.com/a/answer/180504",
          "spf_setup_url": "https://support.google.com/a/answer/33786",
          "data_source": "research_database",
          "last_updated": "2026-04-15T08:21:33.000Z"
        }
      }
    }
  ],
  "meta": {
    "total_reports": 8421,
    "current_page": 1,
    "per_page": 25,
    "total_pages": 12
  }
}

Params

Each record’s ip_address now includes an email_service block when the source IP matches a known mail provider in our research database (Google, Office 365, Mailgun, SendGrid, etc.). The block identifies the service, classifies it as sender vs. forwarder, and surfaces capability flags (supports_dkim/spf/dmarc) plus setup URLs. Returns email_service: null when no match is found. Use is_in_spf_record on the record level for the authoritative SPF-alignment check — email_service describes what the IP IS, not whether it’s authorised for this domain.

Supported Formats

Errors

Examples

{
  "id": 1,
  "raw_xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>...",
  "report_id": "1627703331531660819",
  "org_name": "google.com",
  "email": "noreply-dmarc-support@google.com",
  "extra_contact_info": "https://support.google.com/a/answer/2466580",
  "date_begin": "2019-02-10T00:00:00.000Z",
  "date_end": "2019-02-10T23:59:59.000Z",
  "policy_domain": "twlnet.com",
  "dkim_alignment": "s",
  "spf_alignment": "s",
  "domain_policy": "reject",
  "subdomain_policy": "reject",
  "percentage": 100,
  "domain_id": 1,
  "records_count": 1,
  "report_email_message_id": "CADzZ48nQp+vKj7Bz1xJqQ@mail.gmail.com",
  "created_at": "2019-02-11T03:14:00.000Z",
  "updated_at": "2019-02-11T03:14:00.000Z",
  "records": [
    {
      "id": 1,
      "count": 1,
      "disposition": "none",
      "dkim_status": "pass",
      "spf_status": "pass",
      "reason": "",
      "header_from": "twlnet.com",
      "dmarc_compliance": "Compliant",
      "is_in_spf_record": true,
      "created_at": "2019-02-10T18:42:17.000Z",
      "updated_at": "2019-02-10T18:42:17.000Z",
      "auth_results": [
        {
          "id": 1,
          "type": "Dkim",
          "domain": "twlnet.com",
          "result": "pass",
          "selector": "201810",
          "created_at": "2019-02-10T18:42:17.000Z",
          "updated_at": "2019-02-10T18:42:17.000Z"
        },
        {
          "id": 2,
          "type": "Spf",
          "domain": "twlnet.com",
          "result": "pass",
          "selector": "",
          "created_at": "2019-02-10T18:42:17.000Z",
          "updated_at": "2019-02-10T18:42:17.000Z"
        }
      ],
      "ip_address": {
        "id": 3,
        "sane_source_ip": "87.106.127.28",
        "blacklisted": 0,
        "ptr": "ec2-52-30-166-6.eu-west-1.compute.amazonaws.com",
        "country": "de",
        "created_at": "2019-02-09T11:03:55.000Z",
        "updated_at": "2026-04-15T08:21:33.000Z",
        "email_service": {
          "id": 1042,
          "name": "Google",
          "ptr_domain": "google.com",
          "service_type": "sender",
          "supports_dkim": true,
          "supports_spf": true,
          "supports_dmarc": true,
          "dkim_setup_url": "https://support.google.com/a/answer/180504",
          "spf_setup_url": "https://support.google.com/a/answer/33786",
          "data_source": "research_database",
          "last_updated": "2026-04-15T08:21:33.000Z"
        }
      }
    }
  ]
}

Response now includes alignment-based counts alongside compliance counts: spf_count and dkim_count (record volume where SPF/DKIM authentication passed) and reject_count (record volume where the applied disposition was reject). These are sourced from Record.stats_count. Existing fields — compliant, non_compliant, forwarded, total, none, quarantine, reject — remain unchanged.

Supported Formats

Errors

Examples

{
  "compliant": 4174,
  "non_compliant": 166,
  "forwarded": 1,
  "total": 4355,
  "none": 4188,
  "quarantine": 1,
  "reject": 166,
  "spf_count": 4188,
  "dkim_count": 3902,
  "reject_count": 166
}

Params

Returns the top email sources (senders) for a domain, aggregated by PTR domain.

Each source includes: - source: The PTR domain of the sending servers (e.g., “google.com”, “sendgrid.net”) - total: Total email volume from this source - compliant: DMARC-compliant emails (passed authentication) - non_compliant: Non-compliant emails (failed authentication) - compliance_rate: Percentage of compliant emails (0-100)

Sources are sorted by total volume (highest first).

Use this to identify: - Your legitimate email services and their authentication status - High-volume senders that may need SPF/DKIM configuration - Unknown sources that could be spoofing attempts

Supported Formats

Errors

Examples

{
  "domain": "example.com",
  "period": {
    "start_date": "2026-05-01",
    "end_date": "2026-05-31"
  },
  "total_sources": 5,
  "sources": [
    {
      "source": "google.com",
      "total": 450,
      "compliant": 448,
      "non_compliant": 2,
      "compliance_rate": 99.6
    },
    {
      "source": "sendgrid.net",
      "total": 120,
      "compliant": 85,
      "non_compliant": 35,
      "compliance_rate": 70.8
    },
    {
      "source": "mailchimp.com",
      "total": 75,
      "compliant": 75,
      "non_compliant": 0,
      "compliance_rate": 100.0
    },
    {
      "source": "Unknown",
      "total": 45,
      "compliant": 0,
      "non_compliant": 45,
      "compliance_rate": 0.0
    },
    {
      "source": "amazonses.com",
      "total": 30,
      "compliant": 28,
      "non_compliant": 2,
      "compliance_rate": 93.3
    }
  ]
}

Params

Returns email sources that are failing DMARC authentication, ranked by failure volume.

Each failure entry includes: - source: The PTR domain of the failing sender - failure_count: Number of non-compliant emails - percentage_of_total_failures: This source’s share of all failures

Use this to identify: - Legitimate services that need SPF/DKIM configuration - Potential spoofing sources to investigate - Priority order for remediation (highest volume first)

Note: Sources with email_service identification can be cross-referenced with get_email_sources to find setup instructions for SPF/DKIM configuration.

Supported Formats

Errors

Examples

{
  "domain": "example.com",
  "period": {
    "start_date": "2026-05-01",
    "end_date": "2026-05-31"
  },
  "total_failure_sources": 4,
  "total_failure_count": 84,
  "failures": [
    {
      "source": "Unknown",
      "failure_count": 45,
      "percentage_of_total_failures": 53.6
    },
    {
      "source": "sendgrid.net",
      "failure_count": 35,
      "percentage_of_total_failures": 41.7
    },
    {
      "source": "google.com",
      "failure_count": 2,
      "percentage_of_total_failures": 2.4
    },
    {
      "source": "amazonses.com",
      "failure_count": 2,
      "percentage_of_total_failures": 2.4
    }
  ]
}

Params

Returns daily compliance statistics for analyzing trends over time.

Response includes: - data_points: Array of daily statistics sorted by date (oldest first) - summary: Aggregated statistics for the entire period

Each data point includes: - date: The date (YYYY-MM-DD) - compliant: DMARC-compliant email count - non_compliant: Non-compliant email count - forwarded: Forwarded email count - total: Total email volume - compliance_rate: Daily compliance percentage

Use this to: - Visualize compliance improvements over time - Identify sudden drops in authentication rates - Track the impact of SPF/DKIM configuration changes - Monitor for potential email spoofing incidents

Supported Formats

Errors

Examples

{
  "domain": "example.com",
  "period": {
    "start_date": "2026-05-01",
    "end_date": "2026-05-31"
  },
  "data_points": [
    {
      "date": "2026-05-01",
      "compliant": 145,
      "non_compliant": 12,
      "forwarded": 3,
      "total": 160,
      "compliance_rate": 90.6
    },
    {
      "date": "2026-05-02",
      "compliant": 152,
      "non_compliant": 8,
      "forwarded": 2,
      "total": 162,
      "compliance_rate": 93.8
    },
    {
      "date": "2026-05-03",
      "compliant": 138,
      "non_compliant": 15,
      "forwarded": 5,
      "total": 158,
      "compliance_rate": 87.3
    },
    {
      "date": "2026-05-04",
      "compliant": 167,
      "non_compliant": 6,
      "forwarded": 2,
      "total": 175,
      "compliance_rate": 95.4
    },
    {
      "date": "2026-05-05",
      "compliant": 171,
      "non_compliant": 4,
      "forwarded": 1,
      "total": 176,
      "compliance_rate": 97.2
    }
  ],
  "summary": {
    "total_days": 5,
    "total_volume": 831,
    "total_compliant": 773,
    "total_non_compliant": 45,
    "total_forwarded": 13,
    "overall_compliance_rate": 93.0
  }
}

Params

Returns a branded PDF audit report containing DMARC compliance data, authentication statistics, and email source analysis for the specified date range.

The PDF includes: - Executive summary with security grade (A-F) - Compliance overview with SPF/DKIM/DMARC stats - Daily message volume chart - Email source categorization (authenticated, needs config, unauthenticated) - MTA-STS report (if enabled) - Recommendations and next steps

White-labeled accounts receive branded reports with their custom logo.

Supported Formats

Errors

Params