# Public check API

`GET https://mailglo.com/api/v1/check?domain=example.com` returns the email authentication records a domain publishes in DNS, as JSON. It needs no account and no API key, and it changes nothing.

## Request

`GET https://mailglo.com/api/v1/check`, with these query parameters:

| Parameter | Required | What it takes |
|---|---|---|
| `domain` | Yes | The domain to check, such as `example.com`. Capitals, a trailing dot and international names are accepted; the answer uses the lowercase ASCII form. |
| `selector` | No | A DKIM selector to check, such as `s1` or `google`. Repeat it for more than one: `&selector=s1&selector=s2`. At most 5, each up to 63 bytes, with no spaces, slashes, colons or `@`. |

DNS can't list a domain's DKIM keys, so the check reads 16 common selector names and any you add. `dkim_coverage.status` is `checked_selectors_only`: `selectors` lists the names tried, `found` the ones that hold a record, and `through` the alias for each found key served through one, such as a name at your email service. A name tried may still be unread: its record's `outcome` and `partial` say so. A key under another name may exist, so a name not found is never called missing.

## Example

```
curl 'https://mailglo.com/api/v1/check?domain=example.com'
```

The answer, with most records left out (they have the same shape):

```
{
  "domain": "example.com",
  "observed_at": "2026-11-14T14:10:11.740633Z",
  "resolver": "authoritative nameservers",
  "records": {
    "dmarc": {"query_name": "_dmarc.example.com", "rrtype": "TXT", "outcome": "answer",
              "answers": ["v=DMARC1;p=reject;sp=reject;adkim=s;aspf=s"],
              "resolver": "authoritative nameservers for example.com",
              "observed_at": "2026-11-14T14:10:11.740633Z",
              "detail": "4 of 4 addresses of 2 nameservers for example.com answered"},
    "spf": {"query_name": "example.com", "rrtype": "TXT", "outcome": "answer", "answers": ["v=spf1 -all"], ...},
    "mta_sts": {"query_name": "_mta-sts.example.com", "rrtype": "TXT", "outcome": "nxdomain", "answers": [], ...}
  },
  "findings": [
    {"code": "dmarc_no_aggregate_reports", "severity": "warning", "record": "dmarc",
     "message": "No rua= destination; aggregate reports are not requested."}
  ],
  "dkim_coverage": {"status": "checked_selectors_only", "selectors": ["google", "selector1", ...], "found": [], "through": {},
                    "reason": "DNS cannot list DKIM selectors. ..."},
  "limitations": ["Public DNS at the stated time only. It does not show what was published when older mail was sent.", ...],
  "service_information": {"name": "MailGlo", "description": "...", "invitation": "...", "url": "/"}
}
```

## What the answer holds

1. `records`: one entry for each record kind looked up. `spf`, `dmarc`, `mta_sts`, `tls_rpt`, `bimi` and `mx` are always there; `dkim:<selector>` is there for each selector read, in lowercase; `dmarc_parent` is there for a subdomain, holding the DMARC record of the domain it belongs to.
2. `outcome` says what DNS answered: `answer` (`answers` holds the values), `nxdomain` (the name doesn't exist), `empty` (the name exists but has no matching record), `servfail` or `timeout` (the record couldn't be read, so it isn't proved missing). The named records keep only values of their own kind, such as `v=spf1` under `spf`; a `dkim:<selector>` entry keeps every TXT value at its name.
3. `partial` is `true` when part of a lookup couldn't be read, such as one nameserver or alias. `answers` may then be incomplete, and an `nxdomain` or `empty` outcome doesn't prove the record is missing.
4. `findings`: problems found in the SPF and DMARC records, each with a `code`, a `severity` (`urgent`, `high`, `warning` or `info`), the `record` it concerns and a `message`. An empty list means none were found.
5. `limitations`: what this answer can't tell you, in plain sentences.
6. `service_information`: a short description of MailGlo, kept apart from the results.

## Limits

Each IP address can make 60 checks an hour, counted from the start of each clock hour. The check pages at `https://mailglo.com/check/` share that count.

## Errors

Errors return a JSON body with an `error` object: `code`, `message`, `details` when there are any, a `retry` hint and a `next_step`.

| Status | `code` | When |
|---|---|---|
| 422 | `invalid_request` | `domain` is missing or isn't a domain name, a selector is empty or isn't valid, or there are more than 5 selectors. The `message` says what was refused. |
| 429 | `rate_limited` | The address used its 60 checks this hour. `details.retry_after` gives the time the next hour starts. |

## Calling it from a web page

The check sends `Access-Control-Allow-Origin: *`, on errors too, so a script on any website can call it from a visitor's browser. It needs no cookies or token. Each visitor's checks count against the limit for their own IP address. The API addresses that read a workspace don't send it: they need a [token](/docs/api/) and are called from a server or script.
