Skip to main content
Developer guide

Stable REST contract

API v1 reference

Base URL: https://getmaildns.com/api/v1. All business endpoints require a scoped API key; the OpenAPI document is public and cacheable.

OpenAPI 3.1 JSON

Request conventions

Authentication

Send Authorization: Bearer maildns_live_.... Browser sessions never grant API v1 access, and write scopes do not imply their read equivalents.

Strict JSON

Unknown body or query fields are rejected. Timestamps are UTC ISO 8601 values ending in Z; identifiers are UUIDs.

Monthly API units

Ordinary requests cost 1 unit, report analytics cost 5, and starting a check costs 25. Read X-Usage-* on every authenticated response. A depleted quota returns 429 api_quota_exceeded with no overage charge.

Pagination

Lists return data and an opaque nextCursor. Pass the cursor unchanged and never decode or reuse it on a different endpoint.

Idempotency

Every POST, PATCH, and DELETE requires a UUID Idempotency-Key. Reusing it with different input returns 409 idempotency_conflict.

Idempotent check request
curl --fail-with-body \
  -X POST \
  -H "Authorization: Bearer $MAILDNS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 21f85fa5-a82b-4571-899a-d8c8fc963c2f" \
  --data '{"domainId":"f203b128-18f7-4293-99ab-a277934918d8"}' \
  "https://getmaildns.com/api/v1/checks"
Error envelope
{
  "error": {
    "code": "invalid_query",
    "message": "Check the query parameters."
  }
}

Treat 429 as flow control, honor Retry-After, and add jitter. Creating more API keys does not multiply an organization's allowance.

Organization

1 operation

GET/organization

Get organization

Returns the organization identity, current plan, and effective entitlements for the authenticated API key.

Required scope
organization:read
Idempotency key
Not used
Monthly usage
1 unit

Documented responses

  • 200Organization identity, plan, and effective entitlements.
  • 400Malformed JSON, a missing Idempotency-Key, or an invalid trusted client-IP header.
  • 401The Bearer token is missing, invalid, expired, or revoked.
  • 403The key lacks the required scope or its CIDR restriction rejects the trusted client IP.
  • 404The tenant-scoped organization does not exist or is not visible.
  • 413The JSON body exceeds the endpoint's documented byte limit.
  • 414The request URL exceeds 8,192 characters.
  • 422A path, query, or strict JSON field is invalid.
  • 429The organization rate limit, monthly API-unit quota (`api_quota_exceeded`), or an operation cooldown was reached.

Domains

9 operations

GET/domains

List domains

Lists tenant-scoped domains with opaque cursor pagination and optional status or monitoring filters.

Required scope
domains:read
Idempotency key
Not used
Monthly usage
1 unit

Parameters

  • limit query, optionalNumber of items to return.
  • cursor query, optionalOpaque cursor from the previous page.
  • status query, optionalFilter by lifecycle status.
  • monitoringEnabled query, optionalFilter by whether monitoring is enabled.

Documented responses

  • 200A tenant-scoped domain page.
  • 400Malformed JSON, a missing Idempotency-Key, or an invalid trusted client-IP header.
  • 401The Bearer token is missing, invalid, expired, or revoked.
  • 403The key lacks the required scope or its CIDR restriction rejects the trusted client IP.
  • 413The JSON body exceeds the endpoint's documented byte limit.
  • 414The request URL exceeds 8,192 characters.
  • 422A path, query, or strict JSON field is invalid.
  • 429The organization rate limit, monthly API-unit quota (`api_quota_exceeded`), or an operation cooldown was reached.
POST/domains

Create domain

Creates a pending domain and reveals its DNS challenge and report address exactly once.

Required scope
domains:write
Idempotency key
Required
Monthly usage
1 unit

Parameters

  • Idempotency-Key header, requiredA fresh UUID for this logical mutation. Reuse it only to retry the exact same operation and normalized body.

Request body

Strict domain creation input. Unknown fields are rejected. Content type: application/json.

{
  "domain": "example.com"
}

Documented responses

  • 201Pending domain, one-time report address, and DNS ownership challenge.
  • 400Malformed JSON, a missing Idempotency-Key, or an invalid trusted client-IP header.
  • 401The Bearer token is missing, invalid, expired, or revoked.
  • 402The plan's monitored-domain entitlement was reached.
  • 403The key lacks the required scope or its CIDR restriction rejects the trusted client IP.
  • 409The resource state conflicts with the requested mutation, or the Idempotency-Key was reused with different input.
  • 413The JSON body exceeds the endpoint's documented byte limit.
  • 414The request URL exceeds 8,192 characters.
  • 422A path, query, or strict JSON field is invalid.
  • 429The organization rate limit, monthly API-unit quota (`api_quota_exceeded`), or an operation cooldown was reached.
GET/domains/{domainId}

Get domain

Returns one tenant-scoped domain, including monitoring settings, schedules, and safe report-address hints.

Required scope
domains:read
Idempotency key
Not used
Monthly usage
1 unit

Parameters

  • domainId path, requiredUUID of the tenant-scoped domain.

Documented responses

  • 200Domain settings, schedules, and safe report-address hints.
  • 400Malformed JSON, a missing Idempotency-Key, or an invalid trusted client-IP header.
  • 401The Bearer token is missing, invalid, expired, or revoked.
  • 403The key lacks the required scope or its CIDR restriction rejects the trusted client IP.
  • 404The tenant-scoped domain does not exist or is not visible.
  • 413The JSON body exceeds the endpoint's documented byte limit.
  • 414The request URL exceeds 8,192 characters.
  • 422A path, query, or strict JSON field is invalid.
  • 429The organization rate limit, monthly API-unit quota (`api_quota_exceeded`), or an operation cooldown was reached.
PATCH/domains/{domainId}

Update domain

Changes monitoring or retention settings while enforcing the organization's current entitlements.

Required scope
domains:write
Idempotency key
Required
Monthly usage
1 unit

Parameters

  • domainId path, requiredUUID of the tenant-scoped domain.
  • Idempotency-Key header, requiredA fresh UUID for this logical mutation. Reuse it only to retry the exact same operation and normalized body.

Request body

At least one domain setting. Unknown fields are rejected. Content type: application/json.

{
  "monitoringEnabled": true,
  "retentionDays": 30
}

Documented responses

  • 200Updated domain settings and current alert-delivery readiness. Monitoring is not blocked when delivery setup is incomplete.
  • 400Malformed JSON, a missing Idempotency-Key, or an invalid trusted client-IP header.
  • 401The Bearer token is missing, invalid, expired, or revoked.
  • 402The requested setting exceeds the current plan entitlement.
  • 403The key lacks the required scope or its CIDR restriction rejects the trusted client IP.
  • 404The tenant-scoped domain does not exist or is not visible.
  • 409The resource state conflicts with the requested mutation, or the Idempotency-Key was reused with different input.
  • 413The JSON body exceeds the endpoint's documented byte limit.
  • 414The request URL exceeds 8,192 characters.
  • 422A path, query, or strict JSON field is invalid.
  • 429The organization rate limit, monthly API-unit quota (`api_quota_exceeded`), or an operation cooldown was reached.
DELETE/domains/{domainId}

Archive domain

Archives a domain and disables all of its monitoring schedules without destroying historical evidence.

Required scope
domains:write
Idempotency key
Required
Monthly usage
1 unit

Parameters

  • domainId path, requiredUUID of the tenant-scoped domain.
  • Idempotency-Key header, requiredA fresh UUID for this logical mutation. Reuse it only to retry the exact same operation and normalized body.

Documented responses

  • 200Archive confirmation. Historical retained evidence is not destroyed.
  • 400Malformed JSON, a missing Idempotency-Key, or an invalid trusted client-IP header.
  • 401The Bearer token is missing, invalid, expired, or revoked.
  • 403The key lacks the required scope or its CIDR restriction rejects the trusted client IP.
  • 404The tenant-scoped domain does not exist or is not visible.
  • 409The resource state conflicts with the requested mutation, or the Idempotency-Key was reused with different input.
  • 413The JSON body exceeds the endpoint's documented byte limit.
  • 414The request URL exceeds 8,192 characters.
  • 422A path, query, or strict JSON field is invalid.
  • 429The organization rate limit, monthly API-unit quota (`api_quota_exceeded`), or an operation cooldown was reached.
POST/domains/{domainId}/verify

Verify domain ownership

Checks the DNS ownership challenge and returns retry guidance while the TXT record is not visible.

Required scope
domains:write
Idempotency key
Required
Monthly usage
1 unit

Parameters

  • domainId path, requiredUUID of the tenant-scoped domain.
  • Idempotency-Key header, requiredA fresh UUID for this logical mutation. Reuse it only to retry the exact same operation and normalized body.

Documented responses

  • 200Verification succeeded.
  • 202The TXT challenge is not visible yet. Retry after the indicated delay.
  • 400Malformed JSON, a missing Idempotency-Key, or an invalid trusted client-IP header.
  • 401The Bearer token is missing, invalid, expired, or revoked.
  • 403The key lacks the required scope or its CIDR restriction rejects the trusted client IP.
  • 404The tenant-scoped pending verification does not exist or is not visible.
  • 409The resource state conflicts with the requested mutation, or the Idempotency-Key was reused with different input.
  • 410The current verification challenge expired.
  • 413The JSON body exceeds the endpoint's documented byte limit.
  • 414The request URL exceeds 8,192 characters.
  • 422A path, query, or strict JSON field is invalid.
  • 429The organization rate limit, monthly API-unit quota (`api_quota_exceeded`), or an operation cooldown was reached.
POST/domains/{domainId}/verification

Replace verification challenge

Expires the previous challenge and reveals a replacement for a domain that is still pending.

Required scope
domains:write
Idempotency key
Required
Monthly usage
1 unit

Parameters

  • domainId path, requiredUUID of the tenant-scoped domain.
  • Idempotency-Key header, requiredA fresh UUID for this logical mutation. Reuse it only to retry the exact same operation and normalized body.

Documented responses

  • 201Replacement DNS ownership challenge.
  • 400Malformed JSON, a missing Idempotency-Key, or an invalid trusted client-IP header.
  • 401The Bearer token is missing, invalid, expired, or revoked.
  • 403The key lacks the required scope or its CIDR restriction rejects the trusted client IP.
  • 404The tenant-scoped domain does not exist or is not visible.
  • 409The resource state conflicts with the requested mutation, or the Idempotency-Key was reused with different input.
  • 413The JSON body exceeds the endpoint's documented byte limit.
  • 414The request URL exceeds 8,192 characters.
  • 422A path, query, or strict JSON field is invalid.
  • 429The organization rate limit, monthly API-unit quota (`api_quota_exceeded`), or an operation cooldown was reached.
POST/domains/{domainId}/report-address/rotate

Rotate report address

Activates a new aggregate-report address and keeps the previous address in its documented grace period.

Required scope
domains:write
Idempotency key
Required
Monthly usage
1 unit

Parameters

  • domainId path, requiredUUID of the tenant-scoped domain.
  • Idempotency-Key header, requiredA fresh UUID for this logical mutation. Reuse it only to retry the exact same operation and normalized body.

Documented responses

  • 200Replacement report address and grace-period metadata.
  • 400Malformed JSON, a missing Idempotency-Key, or an invalid trusted client-IP header.
  • 401The Bearer token is missing, invalid, expired, or revoked.
  • 403The key lacks the required scope or its CIDR restriction rejects the trusted client IP.
  • 404The tenant-scoped domain does not exist or is not visible.
  • 409The resource state conflicts with the requested mutation, or the Idempotency-Key was reused with different input.
  • 413The JSON body exceeds the endpoint's documented byte limit.
  • 414The request URL exceeds 8,192 characters.
  • 422A path, query, or strict JSON field is invalid.
  • 429The organization rate limit, monthly API-unit quota (`api_quota_exceeded`), or an operation cooldown was reached.
POST/domains/{domainId}/report-address/{addressId}/revoke

Revoke previous report address

Urgently revokes a previous report address after an explicit hint confirmation; buffered delivery may be lost.

Required scope
domains:write
Idempotency key
Required
Monthly usage
1 unit

Parameters

  • domainId path, requiredUUID of the tenant-scoped domain.
  • addressId path, requiredUUID of the tenant-scoped previous report address.
  • Idempotency-Key header, requiredA fresh UUID for this logical mutation. Reuse it only to retry the exact same operation and normalized body.

Request body

Strong confirmation and audited reason. Unknown fields are rejected. Content type: application/json.

{
  "confirmation": "REVOKE a1b2c3d4e5f6",
  "reason": "Address exposed in a public repository"
}

Documented responses

  • 200Revoked previous report address.
  • 400Malformed JSON, a missing Idempotency-Key, or an invalid trusted client-IP header.
  • 401The Bearer token is missing, invalid, expired, or revoked.
  • 403The key lacks the required scope or its CIDR restriction rejects the trusted client IP.
  • 404The tenant-scoped previous report address does not exist or is not visible.
  • 409The resource state conflicts with the requested mutation, or the Idempotency-Key was reused with different input.
  • 410The previous report address already expired.
  • 413The JSON body exceeds the endpoint's documented byte limit.
  • 414The request URL exceeds 8,192 characters.
  • 422A path, query, or strict JSON field is invalid.
  • 429The organization rate limit, monthly API-unit quota (`api_quota_exceeded`), or an operation cooldown was reached.

Checks and evidence

5 operations

GET/checks

List check runs

Lists check runs by domain, protocol, status, and a bounded UTC time range.

Required scope
checks:read
Idempotency key
Not used
Monthly usage
1 unit

Parameters

  • limit query, optionalNumber of items to return.
  • cursor query, optionalOpaque cursor from the previous page.
  • domainId query, optionalFilter by domain UUID.
  • protocol query, optionalFilter by protocol.
  • status query, optionalFilter by check state.
  • from query, optionalInclusive UTC queuedAt lower bound. Must be supplied with to.
  • to query, optionalExclusive UTC queuedAt upper bound. Must be supplied with from; maximum range is 366 days.

Documented responses

  • 200A retained check-run page.
  • 400Malformed JSON, a missing Idempotency-Key, or an invalid trusted client-IP header.
  • 401The Bearer token is missing, invalid, expired, or revoked.
  • 403The key lacks the required scope or its CIDR restriction rejects the trusted client IP.
  • 413The JSON body exceeds the endpoint's documented byte limit.
  • 414The request URL exceeds 8,192 characters.
  • 422A path, query, or strict JSON field is invalid.
  • 429The organization rate limit, monthly API-unit quota (`api_quota_exceeded`), or an operation cooldown was reached.
POST/checks

Run a domain check

Queues every enabled protocol for one verified domain while preserving plan cooldowns and durable scheduling.

Required scope
checks:run
Idempotency key
Required
Monthly usage
25 units

Parameters

  • Idempotency-Key header, requiredA fresh UUID for this logical mutation. Reuse it only to retry the exact same operation and normalized body.

Request body

Verified domain to check. Unknown fields are rejected. Content type: application/json.

{
  "domainId": "f203b128-18f7-4293-99ab-a277934918d8"
}

Documented responses

  • 202Enabled protocols were queued, or an equivalent run was already queued.
  • 400Malformed JSON, a missing Idempotency-Key, or an invalid trusted client-IP header.
  • 401The Bearer token is missing, invalid, expired, or revoked.
  • 403The key lacks the required scope or its CIDR restriction rejects the trusted client IP.
  • 404The tenant-scoped domain does not exist or is not visible.
  • 409The resource state conflicts with the requested mutation, or the Idempotency-Key was reused with different input.
  • 413The JSON body exceeds the endpoint's documented byte limit.
  • 414The request URL exceeds 8,192 characters.
  • 422A path, query, or strict JSON field is invalid.
  • 429The organization rate limit, monthly API-unit quota (`api_quota_exceeded`), or an operation cooldown was reached.
GET/checks/{checkRunId}

Get check run

Returns one check run with its findings and bounded protocol observations.

Required scope
checks:read
Idempotency key
Not used
Monthly usage
1 unit

Parameters

  • checkRunId path, requiredUUID of the tenant-scoped check run.

Documented responses

  • 200Check run with bounded findings and protocol observations.
  • 400Malformed JSON, a missing Idempotency-Key, or an invalid trusted client-IP header.
  • 401The Bearer token is missing, invalid, expired, or revoked.
  • 403The key lacks the required scope or its CIDR restriction rejects the trusted client IP.
  • 404The tenant-scoped check run does not exist or is not visible.
  • 413The JSON body exceeds the endpoint's documented byte limit.
  • 414The request URL exceeds 8,192 characters.
  • 422A path, query, or strict JSON field is invalid.
  • 429The organization rate limit, monthly API-unit quota (`api_quota_exceeded`), or an operation cooldown was reached.
GET/findings

List findings

Lists evidence-backed findings by domain, check run, outcome, or severity.

Required scope
checks:read
Idempotency key
Not used
Monthly usage
1 unit

Parameters

  • limit query, optionalNumber of items to return.
  • cursor query, optionalOpaque cursor from the previous page.
  • domainId query, optionalFilter by domain UUID.
  • checkRunId query, optionalFilter by check-run UUID.
  • outcome query, optionalFilter by finding outcome.
  • severity query, optionalFilter by finding severity.

Documented responses

  • 200A retained finding page.
  • 400Malformed JSON, a missing Idempotency-Key, or an invalid trusted client-IP header.
  • 401The Bearer token is missing, invalid, expired, or revoked.
  • 403The key lacks the required scope or its CIDR restriction rejects the trusted client IP.
  • 413The JSON body exceeds the endpoint's documented byte limit.
  • 414The request URL exceeds 8,192 characters.
  • 422A path, query, or strict JSON field is invalid.
  • 429The organization rate limit, monthly API-unit quota (`api_quota_exceeded`), or an operation cooldown was reached.
GET/findings/{findingId}

Get finding

Returns one finding with its observation, protocol rule, impact, and remediation guidance.

Required scope
checks:read
Idempotency key
Not used
Monthly usage
1 unit

Parameters

  • findingId path, requiredUUID of the tenant-scoped finding.

Documented responses

  • 200Finding evidence and remediation guidance.
  • 400Malformed JSON, a missing Idempotency-Key, or an invalid trusted client-IP header.
  • 401The Bearer token is missing, invalid, expired, or revoked.
  • 403The key lacks the required scope or its CIDR restriction rejects the trusted client IP.
  • 404The tenant-scoped finding does not exist or is not visible.
  • 413The JSON body exceeds the endpoint's documented byte limit.
  • 414The request URL exceeds 8,192 characters.
  • 422A path, query, or strict JSON field is invalid.
  • 429The organization rate limit, monthly API-unit quota (`api_quota_exceeded`), or an operation cooldown was reached.

Incidents

3 operations

GET/incidents

List incidents

Lists incidents with tenant-safe domain, status, and severity filters and opaque cursor pagination.

Required scope
incidents:read
Idempotency key
Not used
Monthly usage
1 unit

Parameters

  • limit query, optionalNumber of items to return.
  • cursor query, optionalOpaque cursor from the previous page.
  • domainId query, optionalFilter by domain UUID.
  • severity query, optionalFilter by current severity.
  • status query, optionalFilter by incident state.

Documented responses

  • 200A tenant-scoped incident page.
  • 400Malformed JSON, a missing Idempotency-Key, or an invalid trusted client-IP header.
  • 401The Bearer token is missing, invalid, expired, or revoked.
  • 403The key lacks the required scope or its CIDR restriction rejects the trusted client IP.
  • 413The JSON body exceeds the endpoint's documented byte limit.
  • 414The request URL exceeds 8,192 characters.
  • 422A path, query, or strict JSON field is invalid.
  • 429The organization rate limit, monthly API-unit quota (`api_quota_exceeded`), or an operation cooldown was reached.
GET/incidents/{incidentId}

Get incident

Returns an incident, its event history, and the latest evidence-backed finding.

Required scope
incidents:read
Idempotency key
Not used
Monthly usage
1 unit

Parameters

  • incidentId path, requiredUUID of the tenant-scoped incident.

Documented responses

  • 200Incident, bounded event history, and latest finding.
  • 400Malformed JSON, a missing Idempotency-Key, or an invalid trusted client-IP header.
  • 401The Bearer token is missing, invalid, expired, or revoked.
  • 403The key lacks the required scope or its CIDR restriction rejects the trusted client IP.
  • 404The tenant-scoped incident does not exist or is not visible.
  • 413The JSON body exceeds the endpoint's documented byte limit.
  • 414The request URL exceeds 8,192 characters.
  • 422A path, query, or strict JSON field is invalid.
  • 429The organization rate limit, monthly API-unit quota (`api_quota_exceeded`), or an operation cooldown was reached.
PATCH/incidents/{incidentId}

Update incident state

Acknowledges, annotates, snoozes, resolves, or reopens an incident with transition validation.

Required scope
incidents:write
Idempotency key
Required
Monthly usage
1 unit

Parameters

  • incidentId path, requiredUUID of the tenant-scoped incident.
  • Idempotency-Key header, requiredA fresh UUID for this logical mutation. Reuse it only to retry the exact same operation and normalized body.

Request body

Strict incident transition input. Unknown fields are rejected. Content type: application/json.

{
  "action": "acknowledge",
  "note": "Investigating DNS provider change"
}

Documented responses

  • 200Updated incident state.
  • 400Malformed JSON, a missing Idempotency-Key, or an invalid trusted client-IP header.
  • 401The Bearer token is missing, invalid, expired, or revoked.
  • 403The key lacks the required scope or its CIDR restriction rejects the trusted client IP.
  • 404The tenant-scoped incident does not exist or is not visible.
  • 409The resource state conflicts with the requested mutation, or the Idempotency-Key was reused with different input.
  • 413The JSON body exceeds the endpoint's documented byte limit.
  • 414The request URL exceeds 8,192 characters.
  • 422A path, query, or strict JSON field is invalid.
  • 429The organization rate limit, monthly API-unit quota (`api_quota_exceeded`), or an operation cooldown was reached.

Reports

6 operations

GET/reports/dmarc

Query DMARC analytics

Returns bounded DMARC summary or record analytics as JSON, or formula-safe detailed CSV.

Required scope
reports:read
Idempotency key
Not used
Monthly usage
5 units

Parameters

  • from query, requiredInclusive UTC periodStart lower bound.
  • to query, requiredExclusive UTC periodStart upper bound; maximum range is 366 days.
  • domain query, optionalFilter by normalized domain name.
  • domainId query, optionalFilter by domain UUID; mutually exclusive with domain.
  • view query, optionalSummary or detailed rows.
  • format query, optionalJSON, or CSV for a detailed view only.
  • limit query, optionalDetailed JSON rows per page.
  • cursor query, optionalOpaque cursor for a detailed JSON view.
  • topLimit query, optionalRows in each summary ranking.
  • exportLimit query, optionalMaximum detailed CSV rows.

Documented responses

  • 200Analytics in the selected JSON or CSV representation.
  • 400Malformed JSON, a missing Idempotency-Key, or an invalid trusted client-IP header.
  • 401The Bearer token is missing, invalid, expired, or revoked.
  • 403The key lacks the required scope or its CIDR restriction rejects the trusted client IP.
  • 413The JSON body exceeds the endpoint's documented byte limit.
  • 414The request URL exceeds 8,192 characters.
  • 422A path, query, or strict JSON field is invalid.
  • 429The organization rate limit, monthly API-unit quota (`api_quota_exceeded`), or an operation cooldown was reached.
GET/reports/tls

Query TLS report analytics

Returns bounded TLS-RPT summary or failure analytics as JSON, or formula-safe detailed CSV.

Required scope
reports:read
Idempotency key
Not used
Monthly usage
5 units

Parameters

  • from query, requiredInclusive UTC periodStart lower bound.
  • to query, requiredExclusive UTC periodStart upper bound; maximum range is 366 days.
  • domain query, optionalFilter by normalized domain name.
  • domainId query, optionalFilter by domain UUID; mutually exclusive with domain.
  • view query, optionalSummary or detailed rows.
  • format query, optionalJSON, or CSV for a detailed view only.
  • limit query, optionalDetailed JSON rows per page.
  • cursor query, optionalOpaque cursor for a detailed JSON view.
  • topLimit query, optionalRows in each summary ranking.
  • exportLimit query, optionalMaximum detailed CSV rows.

Documented responses

  • 200Analytics in the selected JSON or CSV representation.
  • 400Malformed JSON, a missing Idempotency-Key, or an invalid trusted client-IP header.
  • 401The Bearer token is missing, invalid, expired, or revoked.
  • 403The key lacks the required scope or its CIDR restriction rejects the trusted client IP.
  • 413The JSON body exceeds the endpoint's documented byte limit.
  • 414The request URL exceeds 8,192 characters.
  • 422A path, query, or strict JSON field is invalid.
  • 429The organization rate limit, monthly API-unit quota (`api_quota_exceeded`), or an operation cooldown was reached.
GET/sending-sources

List sending sources

Lists tenant-scoped sending sources with review state, active DMARC evidence metrics, bounded ranges, filters, and opaque cursor pagination.

Required scope
reports:read
Idempotency key
Not used
Monthly usage
1 unit

Parameters

  • limit query, optionalNumber of items to return.
  • cursor query, optionalOpaque cursor from the previous page.
  • from query, optionalInclusive periodStart lower bound. Supply it with to; omitted ranges default to the last 30 days.
  • to query, optionalExclusive periodStart upper bound. Supply it with from; maximum range is 366 days.
  • domainId query, optionalFilter by domain UUID.
  • authorization query, optionalFilter by operator review state.
  • health query, optionalFilter by active-evidence alignment health.
  • kind query, optionalFilter by source kind.
  • query query, optionalCase-insensitive search across source, name, provider, and domain.

Documented responses

  • 200A tenant-scoped sender inventory page with active-evidence metrics.
  • 400Malformed JSON, a missing Idempotency-Key, or an invalid trusted client-IP header.
  • 401The Bearer token is missing, invalid, expired, or revoked.
  • 402The requested evidence predates the current plan's history entitlement.
  • 403The key lacks the required scope or its CIDR restriction rejects the trusted client IP.
  • 413The JSON body exceeds the endpoint's documented byte limit.
  • 414The request URL exceeds 8,192 characters.
  • 422A path, query, or strict JSON field is invalid.
  • 429The organization rate limit, monthly API-unit quota (`api_quota_exceeded`), or an operation cooldown was reached.
GET/sending-sources/export

Export sending sources

Exports the filtered sender inventory as a bounded, formula-safe CSV file.

Required scope
reports:read
Idempotency key
Not used
Monthly usage
1 unit

Parameters

  • from query, optionalInclusive periodStart lower bound. Supply it with to; omitted ranges default to the last 30 days.
  • to query, optionalExclusive periodStart upper bound. Supply it with from; maximum range is 366 days.
  • domainId query, optionalFilter by domain UUID.
  • authorization query, optionalFilter by operator review state.
  • health query, optionalFilter by active-evidence alignment health.
  • kind query, optionalFilter by source kind.
  • query query, optionalCase-insensitive search across source, name, provider, and domain.

Documented responses

  • 200Filtered sender inventory CSV export.
  • 400Malformed JSON, a missing Idempotency-Key, or an invalid trusted client-IP header.
  • 401The Bearer token is missing, invalid, expired, or revoked.
  • 402The requested evidence predates the current plan's history entitlement.
  • 403The key lacks the required scope or its CIDR restriction rejects the trusted client IP.
  • 413The JSON body exceeds the endpoint's documented byte limit.
  • 414The request URL exceeds 8,192 characters.
  • 422A path, query, or strict JSON field is invalid.
  • 429The organization rate limit, monthly API-unit quota (`api_quota_exceeded`), or an operation cooldown was reached.
GET/sending-sources/{sourceId}

Get sending source

Returns one tenant-scoped sending source with durable evidence, authentication domains, and review history.

Required scope
reports:read
Idempotency key
Not used
Monthly usage
1 unit

Parameters

  • sourceId path, requiredUUID of the tenant-scoped sending source.
  • from query, optionalInclusive periodStart lower bound. Supply it with to; omitted ranges default to the last 30 days.
  • to query, optionalExclusive periodStart upper bound. Supply it with from; maximum range is 366 days.

Documented responses

  • 200Sending source, durable evidence, authentication domains, and review history.
  • 400Malformed JSON, a missing Idempotency-Key, or an invalid trusted client-IP header.
  • 401The Bearer token is missing, invalid, expired, or revoked.
  • 402The requested evidence predates the current plan's history entitlement.
  • 403The key lacks the required scope or its CIDR restriction rejects the trusted client IP.
  • 404The tenant-scoped sending source does not exist or is not visible.
  • 413The JSON body exceeds the endpoint's documented byte limit.
  • 414The request URL exceeds 8,192 characters.
  • 422A path, query, or strict JSON field is invalid.
  • 429The organization rate limit, monthly API-unit quota (`api_quota_exceeded`), or an operation cooldown was reached.
PATCH/sending-sources/{sourceId}

Review sending source

Reviews authorization and operator metadata with revision-based concurrency and idempotent audit history.

Required scope
reports:write
Idempotency key
Required
Monthly usage
1 unit

Parameters

  • sourceId path, requiredUUID of the tenant-scoped sending source.
  • from query, optionalInclusive periodStart lower bound. Supply it with to; omitted ranges default to the last 30 days.
  • to query, optionalExclusive periodStart upper bound. Supply it with from; maximum range is 366 days.
  • Idempotency-Key header, requiredA fresh UUID for this logical mutation. Reuse it only to retry the exact same operation and normalized body.

Request body

Strict source review input with the revision last read by the client. Unknown fields are rejected. Content type: application/json.

{
  "authorization": "authorized",
  "expectedRevision": 3,
  "name": "Transactional mail",
  "provider": "Example ESP"
}

Documented responses

  • 200Applied or safely replayed source review.
  • 400Malformed JSON, a missing Idempotency-Key, or an invalid trusted client-IP header.
  • 401The Bearer token is missing, invalid, expired, or revoked.
  • 402The requested evidence predates the current plan's history entitlement.
  • 403The key lacks the required scope or its CIDR restriction rejects the trusted client IP.
  • 404The tenant-scoped sending source does not exist or is not visible.
  • 409The resource state conflicts with the requested mutation, or the Idempotency-Key was reused with different input.
  • 413The JSON body exceeds the endpoint's documented byte limit.
  • 414The request URL exceeds 8,192 characters.
  • 422A path, query, or strict JSON field is invalid.
  • 429The organization rate limit, monthly API-unit quota (`api_quota_exceeded`), or an operation cooldown was reached.

Webhooks

6 operations

GET/webhooks

List webhooks

Lists signed-webhook endpoints without ever exposing their signing secrets.

Required scope
webhooks:read
Idempotency key
Not used
Monthly usage
1 unit

Parameters

  • limit query, optionalNumber of items to return.
  • cursor query, optionalOpaque cursor from the previous page.
  • enabled query, optionalFilter by enabled state.

Documented responses

  • 200A webhook endpoint page with no signing secrets.
  • 400Malformed JSON, a missing Idempotency-Key, or an invalid trusted client-IP header.
  • 401The Bearer token is missing, invalid, expired, or revoked.
  • 403The key lacks the required scope or its CIDR restriction rejects the trusted client IP.
  • 413The JSON body exceeds the endpoint's documented byte limit.
  • 414The request URL exceeds 8,192 characters.
  • 422A path, query, or strict JSON field is invalid.
  • 429The organization rate limit, monthly API-unit quota (`api_quota_exceeded`), or an operation cooldown was reached.
POST/webhooks

Create webhook

Creates an entitled HTTPS webhook endpoint and reveals the signing secret exactly once.

Required scope
webhooks:write
Idempotency key
Required
Monthly usage
1 unit

Parameters

  • Idempotency-Key header, requiredA fresh UUID for this logical mutation. Reuse it only to retry the exact same operation and normalized body.

Request body

Strict signed-webhook endpoint input. Unknown fields are rejected. Content type: application/json.

{
  "eventTypes": [
    "incident.confirmed",
    "incident.recovered"
  ],
  "name": "Incident automation",
  "url": "https://hooks.example.com/maildns"
}

Documented responses

  • 201Created endpoint, alert channel, and one-time signing secret.
  • 400Malformed JSON, a missing Idempotency-Key, or an invalid trusted client-IP header.
  • 401The Bearer token is missing, invalid, expired, or revoked.
  • 402Signed webhooks are not included in the current plan.
  • 403The key lacks the required scope or its CIDR restriction rejects the trusted client IP.
  • 409The resource state conflicts with the requested mutation, or the Idempotency-Key was reused with different input.
  • 413The JSON body exceeds the endpoint's documented byte limit.
  • 414The request URL exceeds 8,192 characters.
  • 422A path, query, or strict JSON field is invalid.
  • 429The organization rate limit, monthly API-unit quota (`api_quota_exceeded`), or an operation cooldown was reached.
GET/webhooks/{endpointId}

Get webhook

Returns a webhook endpoint plus its 50 most recent delivery outcomes, without its secret.

Required scope
webhooks:read
Idempotency key
Not used
Monthly usage
1 unit

Parameters

  • endpointId path, requiredUUID of the tenant-scoped webhook endpoint.

Documented responses

  • 200Webhook endpoint and its 50 most recent delivery outcomes.
  • 400Malformed JSON, a missing Idempotency-Key, or an invalid trusted client-IP header.
  • 401The Bearer token is missing, invalid, expired, or revoked.
  • 403The key lacks the required scope or its CIDR restriction rejects the trusted client IP.
  • 404The tenant-scoped webhook endpoint does not exist or is not visible.
  • 413The JSON body exceeds the endpoint's documented byte limit.
  • 414The request URL exceeds 8,192 characters.
  • 422A path, query, or strict JSON field is invalid.
  • 429The organization rate limit, monthly API-unit quota (`api_quota_exceeded`), or an operation cooldown was reached.
PATCH/webhooks/{endpointId}

Update webhook

Changes webhook configuration; changing the destination URL clears its previous verification.

Required scope
webhooks:write
Idempotency key
Required
Monthly usage
1 unit

Parameters

  • endpointId path, requiredUUID of the tenant-scoped webhook endpoint.
  • Idempotency-Key header, requiredA fresh UUID for this logical mutation. Reuse it only to retry the exact same operation and normalized body.

Request body

At least one webhook change. Unknown fields are rejected. Content type: application/json.

{
  "enabled": true,
  "name": "Primary incident automation"
}

Documented responses

  • 200Updated webhook endpoint.
  • 400Malformed JSON, a missing Idempotency-Key, or an invalid trusted client-IP header.
  • 401The Bearer token is missing, invalid, expired, or revoked.
  • 402Signed webhooks are not included in the current plan.
  • 403The key lacks the required scope or its CIDR restriction rejects the trusted client IP.
  • 404The tenant-scoped webhook endpoint does not exist or is not visible.
  • 409The resource state conflicts with the requested mutation, or the Idempotency-Key was reused with different input.
  • 413The JSON body exceeds the endpoint's documented byte limit.
  • 414The request URL exceeds 8,192 characters.
  • 422A path, query, or strict JSON field is invalid.
  • 429The organization rate limit, monthly API-unit quota (`api_quota_exceeded`), or an operation cooldown was reached.
DELETE/webhooks/{endpointId}

Delete webhook

Soft-deletes a webhook endpoint and its corresponding alert channel.

Required scope
webhooks:write
Idempotency key
Required
Monthly usage
1 unit

Parameters

  • endpointId path, requiredUUID of the tenant-scoped webhook endpoint.
  • Idempotency-Key header, requiredA fresh UUID for this logical mutation. Reuse it only to retry the exact same operation and normalized body.

Documented responses

  • 200Soft-deletion confirmation.
  • 400Malformed JSON, a missing Idempotency-Key, or an invalid trusted client-IP header.
  • 401The Bearer token is missing, invalid, expired, or revoked.
  • 403The key lacks the required scope or its CIDR restriction rejects the trusted client IP.
  • 404The tenant-scoped webhook endpoint does not exist or is not visible.
  • 409The resource state conflicts with the requested mutation, or the Idempotency-Key was reused with different input.
  • 413The JSON body exceeds the endpoint's documented byte limit.
  • 414The request URL exceeds 8,192 characters.
  • 422A path, query, or strict JSON field is invalid.
  • 429The organization rate limit, monthly API-unit quota (`api_quota_exceeded`), or an operation cooldown was reached.
POST/webhooks/{endpointId}/secret/rotate

Rotate webhook secret

Invalidates the previous signing secret and reveals its replacement exactly once.

Required scope
webhooks:write
Idempotency key
Required
Monthly usage
1 unit

Parameters

  • endpointId path, requiredUUID of the tenant-scoped webhook endpoint.
  • Idempotency-Key header, requiredA fresh UUID for this logical mutation. Reuse it only to retry the exact same operation and normalized body.

Documented responses

  • 200Replacement signing secret and invalidation confirmation.
  • 400Malformed JSON, a missing Idempotency-Key, or an invalid trusted client-IP header.
  • 401The Bearer token is missing, invalid, expired, or revoked.
  • 402Signed webhooks are not included in the current plan.
  • 403The key lacks the required scope or its CIDR restriction rejects the trusted client IP.
  • 404The tenant-scoped webhook endpoint does not exist or is not visible.
  • 409The resource state conflicts with the requested mutation, or the Idempotency-Key was reused with different input.
  • 413The JSON body exceeds the endpoint's documented byte limit.
  • 414The request URL exceeds 8,192 characters.
  • 422A path, query, or strict JSON field is invalid.
  • 429The organization rate limit, monthly API-unit quota (`api_quota_exceeded`), or an operation cooldown was reached.