Email Authentication API

Included with Email Authentication Enterprise.

1. What This Feature Does

The Email Authentication API lets another system read your Email Authentication data: your domains and the state of their records, DMARC aggregate and failure reports, TLS reports, your DMARC policy, your authorised senders, and your alerts. Use it to feed a SIEM, a BI tool, a data warehouse or a client dashboard.

The API is read-only. Changes are made in the dashboard.

2. When You Should Use It

• You want DMARC pass rates and sending sources in your own reporting.
• You want CertaDNS alerts in a SIEM or ticketing system that polls for events.
• You manage domains for clients and want a key that sees only one client's domains.

3. When You Should Not Use It

• You want events pushed to you. Use Integrations (webhook, Splunk, Sentinel) instead of polling.
• You want to change records or policy. The API cannot; use the dashboard.

4. Prerequisites

• The Email Authentication Enterprise tier.
• Two-factor authentication turned on for your account — a key with Email Authentication access cannot be created without it.
• An API key with Email Authentication (read) access.

5. Create a Key

1. Open Account > API Keys and click Create.
2. Name the key after the system that will use it.
3. Under Access, tick Email Authentication (read). Tick Failure report subjects only if the system needs message subjects and full mail-from addresses.
4. Under Domains, select the domains the key may see, or none for every domain on the account.
5. Choose when it Expires — one year by default.
6. Copy the key. It is shown once.

Access and domains cannot be changed after the key is created; create a new key instead. A key made for Email Authentication cannot update Dynamic DNS hostnames, and a Dynamic DNS key cannot read Email Authentication data.

6. Make a Request

Send the key as a Bearer token, and a user agent that names your integration:

curl -A "acme-siem/1.0" -H "Authorization: Bearer ak_XXXXXXXX" \
  "https://www.certadns.com/api/v1/email-auth/domains"

• Responses are JSON. Times are ISO 8601, UTC.
• days sets how far back a report query looks (default 30). It is limited to your plan's history: three years on Enterprise.
• Lists that can be long return data and next_cursor. Pass cursor=<next_cursor> for the next page; limit is up to 100.
• Every response carries X-Request-Id. Quote it if you contact support.
• Errors are {"error": {"code": "...", "message": "..."}}.

7. Endpoints

All are GET, under https://www.certadns.com/api/v1/email-auth. The full description, with every field, is an OpenAPI document at https://www.certadns.com/api/v1/openapi.json — import it into Postman or Insomnia, or generate a client from it.

Failure reports

Every key gets the reporter, arrival time, source IP and country, the authentication results, the DKIM domain and selector, the mail-from domain and the recipient domain. Only a key with Failure report subjects also gets the message subject and the full mail-from address. Message IDs are never returned.

Events

Types: dmarc.report.received, tls.report.received, dmarc.policy.changed, alert.raised and alert.resolved, each with id, occurred_at, domain, severity, title and data — the same shape integrations push. Events are recorded whatever the account's alert settings are.

8. Limits

• 60 requests a minute per key. Responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; over the limit, the answer is 429 with Retry-After.
• Up to five active keys per account.
• A key stops working when it expires, when it is deleted, when the account leaves the Enterprise tier, or when the account is disabled.

9. Common Issues and Explanations

401 "The API key is not valid or has expired."

Check the whole key was copied, including ak_, and that it has not expired or been deleted in Account > API Keys.

403 "This key does not have the email_auth:read scope."

The key was created for Dynamic DNS. Create a key with Email Authentication (read) access.

403 "API access needs the Email Authentication Enterprise tier."

The account is no longer on Enterprise. Keys resume working if it returns.

404 "No Email Authentication domain by that name on this key."

The domain is not on the account, is not in Email Authentication, or the key was limited to other domains.

"Turn on two-factor authentication before creating an Email Authentication API key."

Turn on two-factor authentication under Settings > Security, then create the key.

10. Related Features

• API Keys — creating, listing and deleting keys.
• DMARC Reporting — the same data in the dashboard.
• Two-Factor Authentication — required to create these keys.

11. Updates and Behavior Changes

• 1 October 2026. The Email Authentication API is available, read-only, at /api/v1/email-auth.
• 1 October 2026. The OpenAPI document is published at /api/v1/openapi.json.
• 1 October 2026, later. /events reads the event log — report arrivals and policy changes as well as alerts, whatever the alert settings — and takes type=. Events can also be pushed: see Integrations.