API access

The UglyDMARC public API lets you manage domains, pull DMARC report data, and administer users and keys programmatically — authenticated with a scoped Bearer API key.

Requirements

API access is included on plans that list it (see Pricing). You create and manage keys from the app under Settings → API keys, or via the /v1/api-keys endpoints below using a key that holds the api-keys:write scope.

Base URL & versioning

All endpoints are served under a single version prefix:

https://api.uglydmarc.com/v1

A public health check is available at /health (no authentication).

Authentication

Every request (except /health) must send your API key as a Bearer token:

# keys look like: spf_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Authorization: Bearer spf_live_8f3a...d21c

Each key belongs to a single account and carries a fixed set of scopes (below). A missing or invalid/expired key returns 401; a valid key lacking the required scope returns 403.

Store keys securely

The full key value is shown once, at creation. Keep it in a secret manager — never commit it to source control or ship it in client-side code. If a key leaks, revoke it (DELETE /v1/api-keys/{id}) and issue a new one.

Scopes

Grant a key only the scopes it needs.

Scope	Grants
`domains:read`	List and read domains, their config, and DAG status
`domains:write`	Create, update, and delete domains
`domains:dag`	Trigger a DAG (SPF flattening) rebuild for a domain
`reports:read`	Read DMARC report data for a domain
`users:read`	List and read users
`users:write`	Invite users, change roles, remove users
`api-keys:read`	List API keys
`api-keys:write`	Create and revoke API keys

Endpoints

All paths are relative to https://api.uglydmarc.com/v1.

Method & path	Scope	Description
`GET /account`	—	The account this key belongs to
`GET /domains`	`domains:read`	List your domains
`POST /domains`	`domains:write`	Add a domain
`GET /domains/{id}`	`domains:read`	Get a domain
`PUT /domains/{id}`	`domains:write`	Update a domain
`DELETE /domains/{id}`	`domains:write`	Remove a domain
`GET /domains/{id}/dag`	`domains:read`	Get the flattened SPF DAG / status for a domain
`POST /domains/{id}/dag/rebuild`	`domains:dag`	Trigger a DAG rebuild (re-flatten the sender tree)
`GET /domains/{id}/reports`	`reports:read`	DMARC report data for a domain
`GET /users`	`users:read`	List users
`POST /users/invite`	`users:write`	Invite a user
`GET /users/{id}`	`users:read`	Get a user
`PUT /users/{id}/roles`	`users:write`	Replace a user's roles
`DELETE /users/{id}`	`users:write`	Remove a user
`GET /api-keys`	`api-keys:read`	List API keys
`POST /api-keys`	`api-keys:write`	Create an API key
`DELETE /api-keys/{id}`	`api-keys:write`	Revoke an API key

Examples

List the domains on your account:

curl https://api.uglydmarc.com/v1/domains \
  -H "Authorization: Bearer spf_live_8f3a...d21c"

Pull DMARC report data for a domain:

curl https://api.uglydmarc.com/v1/domains/{id}/reports \
  -H "Authorization: Bearer spf_live_8f3a...d21c"

Add a domain:

curl -X POST https://api.uglydmarc.com/v1/domains \
  -H "Authorization: Bearer spf_live_8f3a...d21c" \
  -H "Content-Type: application/json" \
  -d '{"fqdn": "acme.com"}'

Force a re-flatten of a domain's SPF tree (e.g. after adding a vendor):

curl -X POST https://api.uglydmarc.com/v1/domains/{id}/dag/rebuild \
  -H "Authorization: Bearer spf_live_8f3a...d21c"

Errors

Errors return JSON with an error message and the appropriate status:

Status	Meaning
`401 Unauthorized`	Missing/malformed `Authorization` header, or invalid/expired key
`403 Forbidden`	The key is valid but lacks the required scope
`404 Not Found`	The resource doesn't exist or isn't on your account
`400 Bad Request`	Malformed request body or parameters

Tip

Scope keys narrowly — e.g. a reporting integration only needs domains:read + reports:read. Rotate keys periodically and revoke any you're not actively using.