Skip to main content

MailDNS API v1

Automate the evidence behind email authentication.

Manage verified domains, run bounded checks, retrieve findings, operate incidents, and configure signed webhooks through one tenant-scoped REST API. DMARC and TLS report resources are documented, while inbound aggregation remains a closed beta on this deployment.

Browse API referenceOpenAPI 3.1 JSONAPI discovery JSON
First requestcURL
curl --fail-with-body \
  -H "Authorization: Bearer $MAILDNS_API_KEY" \
  "https://getmaildns.com/api/v1/domains?limit=25"

Built for unattended integrations.

Least-privilege keys

Keys are hashed at rest, expire, can be CIDR-bound, and grant only explicitly selected read or write scopes.

Safe retries

Every write requires a UUID Idempotency-Key, so a network retry cannot create a second domain or webhook.

Bounded by design

Opaque cursors, bounded date ranges, export caps, and durable organization-wide limits keep automation predictable.

Evidence, not a score

DNS observations, findings, incident transitions, and delivery outcomes preserve the evidence behind each result.

Explicit at every boundary.

Web sessions never authenticate API v1. Create a key from the authenticated workspace, copy its one-time token, and send it as a Bearer credential from your server.

  1. 01

    Create a scoped key

    Choose only the scopes and CIDR ranges the integration needs. Tokens are shown once.

  2. 02

    Send a Bearer token

    Use Authorization on every call. Cookies and browser sessions are intentionally ignored.

  3. 03

    Retry writes safely

    Attach a fresh UUID Idempotency-Key to POST, PATCH, and DELETE requests.

  4. 04

    Follow response limits

    Read RateLimit headers, preserve opaque cursors, and honor Retry-After on 429 responses.

The same workflows as the control plane.

30 documented operations across the full monitoring workflow.

View parameters and responses

Organization

  • GET/organizationGet organization

Domains

  • GET/domainsList domains
  • POST/domainsCreate domain
  • GET/domains/{domainId}Get domain
  • PATCH/domains/{domainId}Update domain
  • DELETE/domains/{domainId}Archive domain
  • POST/domains/{domainId}/verifyVerify domain ownership
  • POST/domains/{domainId}/verificationReplace verification challenge
  • POST/domains/{domainId}/report-address/rotateRotate report address
  • POST/domains/{domainId}/report-address/{addressId}/revokeRevoke previous report address

Checks and evidence

  • GET/checksList check runs
  • POST/checksRun a domain check
  • GET/checks/{checkRunId}Get check run
  • GET/findingsList findings
  • GET/findings/{findingId}Get finding

Incidents

  • GET/incidentsList incidents
  • GET/incidents/{incidentId}Get incident
  • PATCH/incidents/{incidentId}Update incident state

Reports

  • GET/reports/dmarcQuery DMARC analytics
  • GET/reports/tlsQuery TLS report analytics
  • GET/sending-sourcesList sending sources
  • GET/sending-sources/exportExport sending sources
  • GET/sending-sources/{sourceId}Get sending source
  • PATCH/sending-sources/{sourceId}Review sending source

Webhooks

  • GET/webhooksList webhooks
  • POST/webhooksCreate webhook
  • GET/webhooks/{endpointId}Get webhook
  • PATCH/webhooks/{endpointId}Update webhook
  • DELETE/webhooks/{endpointId}Delete webhook
  • POST/webhooks/{endpointId}/secret/rotateRotate webhook secret

Shared across every key in the organization.

Creating more keys cannot multiply either allowance. Every authenticated request consumes the same PostgreSQL-backed minute and UTC calendar-month budgets. Ordinary calls cost 1 unit, report analytics 5, and starting a check 25. Exhaustion returns 429 api_quota_exceeded; there is no automatic overage charge.

PlanRequests/minuteAPI units/monthActive keysCheck cooldown
Free202,000115 minutes
Pro120100,00055 minutes
Agency3001,000,000252 minutes