DMARCguard API v1

Read your organization's DMARC data programmatically. Authenticate with an API key, page with limit and offset, and watch the rate-limit headers.

Base URL and versioning

Every path in this reference is relative to https://api.dmarcguard.io/api/v1. The version segment is part of the contract: fields are only added within a version, never renamed or removed. A breaking change ships as a new version at a new base URL, and the old one keeps serving.

Quick start bash

curl "https://api.dmarcguard.io/api/v1/reports" \
  -H "Authorization: Bearer dg_your_key"

Download the OpenAPI document for this version. Tools that discover APIs automatically can start from the API catalog.

Authentication

Send an API key as a bearer token. Keys start with dg_, are bound to one organization and carry a scope (read or full) that narrows what the owner's role allows. Each endpoint lists the permission it checks and the scopes that satisfy it. See the authentication guide for how keys are issued, scoped and revoked.

Conventions

IDs are opaque strings (Crockford Base32). Never parse one as a number.
Timestamps are RFC 3339 in UTC with whole seconds, e.g. 2026-09-15T16:03:43Z, never another offset and never fractional seconds. A field naming a calendar day rather than a moment (a trend bucket, a snapshot date, a date-range bound, a last-report date) is an RFC 3339 full date: 2026-09-15. An absent value is null, never 0 and never "". Two exceptions: the report object inside GET /reports/{id} keeps the reporter's own epoch seconds, since it is passed through exactly as sent, and X-RateLimit-Reset stays epoch seconds, the convention for that header everywhere.
Rates such as compliance_rate are percentages from 0 to 100, not fractions.
Paging: every list endpoint (reports, sources, events, domains and top sending IPs) returns an envelope holding the rows under their own key plus total, limit and offset. total counts everything matching the filter before paging, so it is what you page through, while limit and offset are the values the server actually applied, so a limit above 200 comes back clamped to 200. Reports and sources also carry has_any, which ignores the filter: use it to tell a page that matched nothing apart from an organization with no data yet.
Empty lists: a list is always an array. An empty list is [], never null.
Rate limits are reported on every metered response on a plan with an hourly quota, in the X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, RateLimit-Policy, RateLimit headers, and Retry-After on a rejection. The rate limits guide explains the budgets.
Methods: every documented operation is a GET; any other method returns 405 with an Allow header and no body.
Unknown paths: a path that is not in this reference returns 404 with the error shape below.

Errors

Every non-2xx response is JSON with this shape, except a 405, which has no body. The error text is for people; branch on code when one is present.

Field	Type	Notes
`error`	`string`	Human-readable, title-cased reason.
`code`	`string` optional	Optional machine-readable discriminator, e.g. quota_exceeded.
`required`	`string` optional	The permission the request lacked; present only on a permission denial.

Status	When
`401`	Missing, malformed, revoked, expired or not-entitled API key.
`403`	The key's scope or its owner's role does not allow this operation.
`429`	Hourly quota or an abuse limit exceeded; the body's code says which. Honour Retry-After.
`500`	Unexpected server error; retry with backoff.
`503`	A transient failure resolving the organization or reading storage; retry after a short pause.

A 429 carries code rate_limited when an abuse control rejected the request (back off for Retry-After) and quota_exceeded when the hourly quota is spent (nothing helps before X-RateLimit-Reset).