REST API
Reports API
Access your DMARC report data programmatically. Retrieve individual reports, aggregated statistics, sending sources, and authentication failures.
Endpoints
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/v1/reports | List DMARC reports |
| GET | /api/v1/reports/:id | Get report details |
| GET | /api/v1/reports/aggregate | Get aggregated statistics |
| GET | /api/v1/reports/sources | List sending sources |
| GET | /api/v1/reports/failures | List authentication failures |
GET
List DMARC Reports
Retrieve a paginated list of DMARC aggregate reports.
GET /api/v1/reportscurl -X GET "https://api.ddmarc.com/v1/reports?domain_id=dom_abc123&start_date=2024-01-01&end_date=2024-01-31" \
-H "Authorization: Bearer YOUR_API_KEY"Query Parameters
| Parameter | Type | Description |
|---|---|---|
| domain_id | string | Filter by domain ID |
| start_date | string | Start date (YYYY-MM-DD) |
| end_date | string | End date (YYYY-MM-DD) |
| page | integer | Page number (default: 1) |
| per_page | integer | Results per page (default: 20, max: 100) |
Response200 OK
{
"data": [
{
"id": "rpt_xyz789",
"domain_id": "dom_abc123",
"reporter": "google.com",
"date_range": {
"begin": "2024-01-15T00:00:00Z",
"end": "2024-01-15T23:59:59Z"
},
"total_count": 1250,
"pass_count": 1230,
"fail_count": 20,
"pass_rate": 98.4,
"received_at": "2024-01-16T06:00:00Z"
}
],
"meta": {
"total": 45,
"page": 1,
"per_page": 20,
"total_pages": 3
}
}GET
Get Report Details
Retrieve detailed information about a specific report, including all source records.
GET /api/v1/reports/:idcurl -X GET "https://api.ddmarc.com/v1/reports/rpt_xyz789" \
-H "Authorization: Bearer YOUR_API_KEY"GET
Get Aggregated Statistics
Retrieve aggregated statistics across all reports for a time period.
GET /api/v1/reports/aggregatecurl -X GET "https://api.ddmarc.com/v1/reports/aggregate?start_date=2024-01-01&end_date=2024-01-31" \
-H "Authorization: Bearer YOUR_API_KEY"Response200 OK
{
"data": {
"period": {
"start": "2024-01-01",
"end": "2024-01-31"
},
"totals": {
"emails": 125000,
"reports": 450,
"sources": 85
},
"authentication": {
"pass_rate": 97.8,
"spf_pass_rate": 98.5,
"dkim_pass_rate": 99.1,
"dmarc_pass_rate": 97.8
},
"daily": [
{
"date": "2024-01-01",
"emails": 4200,
"pass_rate": 98.1
}
]
}
}GET
List Sending Sources
Retrieve a list of all IP addresses and hostnames that have sent email on behalf of your domains.
GET /api/v1/reports/sourcescurl -X GET "https://api.ddmarc.com/v1/reports/sources?domain_id=dom_abc123" \
-H "Authorization: Bearer YOUR_API_KEY"Response200 OK
{
"data": [
{
"source_ip": "209.85.220.41",
"hostname": "mail-sor-f41.google.com",
"organization": "Google LLC",
"country": "US",
"total_count": 45000,
"pass_count": 44850,
"pass_rate": 99.7,
"spf_result": "pass",
"dkim_result": "pass",
"first_seen": "2024-01-01T00:00:00Z",
"last_seen": "2024-01-31T23:59:59Z"
}
],
"meta": {
"total": 25
}
}GET
List Authentication Failures
Retrieve a list of emails that failed DMARC authentication, grouped by source.
GET /api/v1/reports/failurescurl -X GET "https://api.ddmarc.com/v1/reports/failures?domain_id=dom_abc123&start_date=2024-01-01" \
-H "Authorization: Bearer YOUR_API_KEY"Response200 OK
{
"data": [
{
"source_ip": "192.168.1.100",
"hostname": "unknown",
"organization": "Unknown ISP",
"country": "CN",
"failure_count": 150,
"spf_result": "fail",
"dkim_result": "none",
"policy_applied": "reject",
"first_seen": "2024-01-15T08:00:00Z",
"last_seen": "2024-01-31T16:00:00Z"
}
],
"meta": {
"total": 8,
"total_failures": 320
}
}Export Reports
Add format=csv to any endpoint to download data as CSV:
GET /api/v1/reports?format=csv&start_date=2024-01-01&end_date=2024-01-31CSV export is available on Plus plan and above.
Report Object
| Field | Type | Description |
|---|---|---|
| id | string | Unique report identifier |
| domain_id | string | Associated domain ID |
| reporter | string | Organization that sent the report |
| date_range | object | Report period (begin/end timestamps) |
| total_count | integer | Total emails in report |
| pass_count | integer | Emails that passed DMARC |
| fail_count | integer | Emails that failed DMARC |
| pass_rate | number | Authentication pass rate (0-100) |
| received_at | string | When DDMARC received the report |