Skip to main content
Beta

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.

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.

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.

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"
}
StatusCodeWhat it means
400INVALID_BODYThe body is not what the endpoint takes, or is not JSON. The message says what it expects.
400INVALID_STATUSThe status asked for on the issues list is not one it has.
400INVALID_DOMAINThe domain asked for on the issues list is not a domain name.
401API_KEY_MISSINGNo key was sent in the Authorization header.
401API_KEY_INVALIDThe key does not work. It may have been revoked, have expired or have gone unused for too long, or it was mistyped.
403API_KEY_READ_ONLYThe endpoint makes a change, and the key is read only.
403NOT_ON_PLANYour 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.
403DOMAIN_NOT_VERIFIEDReport figures need a domain you have verified. Verify it on the Domains page.
404DOMAIN_NOT_FOUNDYour organisation does not hold that domain.
404ISSUE_NOT_FOUNDYour organisation has no issue with that id.
404UNKNOWN_CHECKThe check named in the address is not one of the ten.
409CHECK_OFFThe check is off for the domain, so its alerts cannot be changed. Switch it on first.
413BODY_TOO_LARGEThe body is larger than the endpoint takes.
429RATE_LIMITEDToo many requests. Wait for the seconds the Retry-After header gives, then send it again.
503READ_FAILEDWe could not read the data just now. Try again shortly.
503COULD_NOT_CHECKA recheck could not be settled, and nothing changed. Try again shortly.
400INVALID_REQUESTThe change was refused for a reason the message gives.
403FORBIDDENThe change is not allowed, for a reason the message gives.
404NOT_FOUNDSomething the change needs was not found, as the message says.
409CONFLICTThe change does not fit the domain's current state, as the message says.
5xxSERVER_ERRORSomething 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.

We use optional analytics cookies (Google Analytics) to understand how visitors use the site. Essential cookies are always on. Privacy policy