The ShieldMarc API
The ShieldMarc API gives your own tools the domains, Security Grades, issues and report figures your dashboard shows, as JSON over HTTPS. It is included on every plan, the free Starter plan too. It is in beta, so we may still change it.
What can I do with the API?
You can read your organisation's data with any key, and make three kinds of change with a read and write key.
- Read. Your domains with their Security Grade, DMARC policy, SPF record and checks; one domain in the detail its page shows; a verified domain's DMARC report figures, failure reports and TLS reports; and the issues raised on your domains.
- Change. Switch a check on or off, pause or resume a check's alerts, and dismiss, resolve, reopen or recheck an issue.
- Not in the API. It cannot add or remove domains, and it has nothing for Dynamic SPF, team members, alert recipients, exports or billing. Those stay in the dashboard.
A key reads and changes what your plan gives you in the dashboard, and nothing more. A check your plan does not include cannot be switched on through the API either.
How do I get an API key?
The organisation's owner, or an admin who sees every domain, makes a key in Settings, API keys. A key belongs to the organisation and acts for all of its domains.
- Read only, or read and write. You choose when you make the key. A read only key can call every
GETendpoint and cannot change anything. - Shown once. The key is shown when it is made and not again. We keep a hash of it and its first 12 characters, not the key, so we cannot show it to you later. Keep it as you would a password: anyone holding it can use it.
- Up to 20 working keys. Revoke a key in Settings at any time. It stops working at once.
- Expiry. A new key expires after 90 days unless you choose 30 days, 1 year or no expiry.
- Unused keys stop. A key that goes 90 days without use stops working, whatever its expiry. Owners, and admins who see every domain, are emailed 7 days before any key stops.
- A key stops with its maker. A key is revoked when the person who made it is removed from the organisation, leaves it, is made a viewer, is limited to some domain groups or deletes their account. The dashboard says how many keys will stop before that change is confirmed.
How do I make a request?
Send the key as a Bearer token in the Authorization header to an address under https://shieldmarc.com/api/v1. A key is not read from the address or the body. A key starts smk_. In these examples it is held in an environment variable, SHIELDMARC_API_KEY, which keeps it out of your shell history and your scripts.
curl https://shieldmarc.com/api/v1/domains \
-H "Authorization: Bearer $SHIELDMARC_API_KEY"The answer is JSON. Dates are ISO 8601 in UTC, and a check that is off is null.
{
"domains": [
{
"domain": "example.com",
"verified": true,
"parentDomain": null,
"group": "Acme",
"status": { "kind": "blocking_on", "label": "Refusing fakes", "reason": "DMARC is at reject" },
"grade": "A+",
"dmarc": { "policy": "reject", "record": "v=DMARC1; p=reject; rua=mailto:reports@example.com" },
"spfRecord": "v=spf1 include:spf.protection.outlook.com -all",
"openIssues": 3,
"checks": {
"certificate": { "status": "healthy", "lastCheckedAt": "2026-11-16T09:00:00.000Z" },
"dns": { "status": "ok", "lastCheckedAt": "2026-11-16T09:00:00.000Z" },
"uptime": null,
"domainExpiry": { "status": "healthy", "lastCheckedAt": "2026-11-16T09:00:00.000Z" },
"mtaSts": null,
"tlsRpt": null,
"dnssec": { "status": "not_configured", "lastCheckedAt": null },
"dkim": null,
"caa": { "status": "healthy", "lastCheckedAt": "2026-11-16T09:00:00.000Z" },
"lookalike": { "status": "warning", "lastCheckedAt": "2026-11-16T09:00:00.000Z" }
},
"lastCheckedAt": "2026-11-16T09:30:00.000Z"
}
],
"total": 1,
"limit": 50,
"offset": 0,
"hasMore": false
}The two lists take limit (1 to 200, 50 unless you say) and offset, and answer with total and hasMore. This reads every page of your domains in Python, with the requests library:
import os
import requests
key = os.environ["SHIELDMARC_API_KEY"]
offset = 0
while True:
r = requests.get(
"https://shieldmarc.com/api/v1/domains",
headers={"Authorization": f"Bearer {key}"},
params={"limit": 200, "offset": offset},
timeout=30,
)
r.raise_for_status()
page = r.json()
for d in page["domains"]:
print(d["domain"], d["grade"], d["openIssues"])
if not page["hasMore"]:
break
offset += page["limit"]And in JavaScript, saved as a .mjs file and run with Node.js 18 or later:
const { SHIELDMARC_API_KEY: key } = process.env;
let offset = 0;
for (;;) {
const res = await fetch(`https://shieldmarc.com/api/v1/domains?limit=200&offset=${offset}`, {
headers: { Authorization: `Bearer ${key}` },
});
const page = await res.json();
if (!res.ok) throw new Error(`${res.status} ${page.code}`);
for (const d of page.domains) console.log(d.domain, d.grade, d.openIssues);
if (!page.hasMore) break;
offset += page.limit;
}A machine-readable description of every endpoint is at /api/v1/openapi.json, in OpenAPI 3.1. Tools that import OpenAPI can use it to set up every endpoint for you.
Which endpoints are there?
There are ten: seven that read, and three that change something and need a read and write key. Each has its own allowance of requests a minute for each key.
GET /api/v1/account
The organisation the key belongs to and its plan, the key's name and access, and how many domains the organisation has and has verified.
300 a minute per key
GET /api/v1/domains
Your domains, each with its status, Security Grade, DMARC policy and record, SPF record, checks and number of open issues. Read from what the checks last stored: the call makes no DNS lookup.
300 a minute per key
GET /api/v1/domains/{domain}
One domain as its page shows it: its status, the Security Grade with what holds it back, what to do next, its checks and recent changes. Like opening that page, this can run a fresh check of the domain.
50 a minute per key
GET /api/v1/domains/{domain}/email
DMARC report figures: how much mail passed, each service that sends as the domain and what it needs, and whether the domain is ready for a stronger policy.
100 a minute per key
GET /api/v1/domains/{domain}/failure-reports
The newest DMARC failure reports for the domain, at most 20. Fields such as the subject come from the reporter, as sent.
100 a minute per key
GET /api/v1/domains/{domain}/tls-reports
TLS-RPT figures: how many connections to your mail servers were encrypted, and why the others failed.
100 a minute per key
GET /api/v1/issues
The issues raised on your domains, most severe first.
300 a minute per key
PATCH /api/v1/domains/{domain}/checks/{check}
Switch one of a domain's checks on or off, or pause or resume its alerts. Switching a check off keeps its history and settings for when it is switched back on. Needs a read and write key.
100 a minute per key
PATCH /api/v1/issues/{id}
Dismiss, resolve or reopen an issue, with an optional note. Needs a read and write key.
100 a minute per key
POST /api/v1/issues/{id}/recheck
Check an issue again now. If the check passes, the issue's status becomes verified. Needs a read and write key.
50 a minute per key
- One domain. Its
checksare keyed as the domains list keys them, with the facts the domain's page shows, such as the days left on a certificate. Each Security Grade factor has anid, the one an issue'scheckgives, so a failing factor can be matched to its issue. The rest of the answer is in the page's own words. - Report figures need a verified domain. The email, failure-reports and tls-reports endpoints answer for a domain you have verified, or a name beneath one. Each takes
days, from 1 to 180, and uses 30 unless you say. - The issues list. It shows open issues unless you ask for
statusasdismissed,resolved,verifiedorall. Adddomainfor one domain's issues. - Changing a check. The check in the address is one of
certificate,dns,uptime,domain-expiry,mta-sts,tls-rpt,dnssec,dkim,caaorlookalike. The body carriesenabled,alertsor both, each true or false. - Changing an issue. The body carries
statusasdismissed,resolvedoropen, anote, or both. A recheck takes no body.
This pauses the alerts of one check:
curl -X PATCH https://shieldmarc.com/api/v1/domains/example.com/checks/dns \
-H "Authorization: Bearer $SHIELDMARC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"alerts": false}'Every change made with a key is recorded in your organisation's audit log under the key's name.
What does an error look like?
An error is a JSON object with a message in words and a code that stays the same. Build on the code, not on the message, which we may reword.
{
"error": "This API key is read only. Use a key with read and write access to make changes.",
"code": "API_KEY_READ_ONLY"
}| Status | Code | What it means |
|---|---|---|
| 400 | INVALID_BODY | The body is not what the endpoint takes, or is not JSON. The message says what it expects. |
| 400 | INVALID_STATUS | The status asked for on the issues list is not one it has. |
| 400 | INVALID_DOMAIN | The domain asked for on the issues list is not a domain name. |
| 401 | API_KEY_MISSING | No key was sent in the Authorization header. |
| 401 | API_KEY_INVALID | The key does not work. It may have been revoked, have expired or have gone unused for too long, or it was mistyped. |
| 403 | API_KEY_READ_ONLY | The endpoint makes a change, and the key is read only. |
| 403 | NOT_ON_PLAN | Your plan does not include the change, such as switching on a check it leaves out or one past its limit. The answer also carries "upgrade": true. |
| 403 | DOMAIN_NOT_VERIFIED | Report figures need a domain you have verified. Verify it on the Domains page. |
| 404 | DOMAIN_NOT_FOUND | Your organisation does not hold that domain. |
| 404 | ISSUE_NOT_FOUND | Your organisation has no issue with that id. |
| 404 | UNKNOWN_CHECK | The check named in the address is not one of the ten. |
| 409 | CHECK_OFF | The check is off for the domain, so its alerts cannot be changed. Switch it on first. |
| 413 | BODY_TOO_LARGE | The body is larger than the endpoint takes. |
| 429 | RATE_LIMITED | Too many requests. Wait for the seconds the Retry-After header gives, then send it again. |
| 503 | READ_FAILED | We could not read the data just now. Try again shortly. |
| 503 | COULD_NOT_CHECK | A recheck could not be settled, and nothing changed. Try again shortly. |
| 400 | INVALID_REQUEST | The change was refused for a reason the message gives. |
| 403 | FORBIDDEN | The change is not allowed, for a reason the message gives. |
| 404 | NOT_FOUND | Something the change needs was not found, as the message says. |
| 409 | CONFLICT | The change does not fit the domain's current state, as the message says. |
| 5xx | SERVER_ERROR | Something failed on our side. Try again shortly, and tell us through support if it goes on. |
The last five codes come with a change the dashboard itself refused, or with a failure on our side, and the message says what happened. A domain or an issue that belongs to another organisation is answered exactly as one that does not exist.
How many requests can I make?
Each key has its own allowance on each endpoint, from 50 to 300 requests a minute, as the endpoints table gives. All of an organisation's keys together can make three times one key's allowance. A request over the limit is answered 429 with the code RATE_LIMITED and a Retry-After header giving the seconds to wait.
Requests with no key, or with one we did not issue, are counted against the address they come from and are limited to a few a minute.
What does beta mean?
Beta means the API works and is supported, and that we may still change what an endpoint takes or answers while we learn how it is used. The version is in the address, /api/v1. If you build on the API, or need something it does not do, tell us through support.
What has changed?
Each change to what an endpoint takes or answers, newest first.
- 19 November 2026
- Every error now carries a code, among them RATE_LIMITED, NOT_ON_PLAN and BODY_TOO_LARGE. A body that is not JSON is INVALID_BODY. The domains and issues lists answer a failed read with 503, as the other endpoints do, not 500. One domain's answer changed shape: its checks are an object keyed as the domains list keys them, not lists of names, and each Security Grade factor, passing ones included, is an object with an id.
- 18 November 2026
- Released in beta, on every plan.