The MailGuardHQ REST API

Start here

The one call that needs nothing from you: run the same thirteen checks the home page runs, on any domain, with no account and no credential.

curl -s https://api.mailguardhq.com/v1/checks \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2b9e-4a77-4f1c-9f0e-2c1d8b5a3e77" \
  -d '{"domain":"yourcompany.com"}'

Everything else needs a token. A free account is enough to mint one - sign up, verify your address, and mint it from your organisation. Free carries one token at a time, a maximum lifetime of 30 days, and never dns:write; the paid plans raise both numbers.

Conventions

One error shape, everywhere

Every failure on every endpoint returns the same body. Branch on code, never on message - the code is stable, the message is written for a human and may be reworded. action says what to do about it, and correlationId is the value to quote if you need to ask us what happened: it appears on the same request in our logs.

{
  "error": {
    "code": "wrong_audience",
    "message": "This token was issued for the \"mcp\" surface and cannot be used here.",
    "action": "Mint a token for the surface you are calling.",
    "correlationId": "0HN7A2C4E9F1K",
    "details": [ { "field": "scopes", "issue": "..." } ]
  }
}

Never a 200 with an error inside it, and never a stack trace, a SQL fragment or an upstream vendor payload. Across an organisation boundary the answer is 404 rather than 403, because a 403 would confirm the resource exists.

Every collection is paginated

Including ones that look small today. Send page and pageSize; the default page size is 100 and there is an explicit maximum. The envelope is the same for every collection:

{
  "items": [ ... ],
  "page": 1,
  "pageSize": 100,
  "totalCount": 243,
  "totalPages": 3,
  "hasMore": true
}

Idempotency on writes

Every non-GET accepts an Idempotency-Key header - any unique value, a UUID is fine. Repeat a call with the same key and the original response is replayed instead of the work happening twice. A client that times out cannot tell whether its write landed, and without this its retry acts twice.

The same key with a different body is a client bug rather than a retry, and is answered 409 - replaying a response that does not correspond to what was asked would be the more dangerous silent behaviour.

Rate limits

Three allowances, because three surfaces have different risks: the anonymous check, the signup and sign-in routes, and authenticated traffic per credential and per plan. Over the line you get 429 and a Retry-After header saying when to come back. Requests made from the interactive console are ordinary requests and meet the same limiter.

Versioning

The version is in the path: /v1/.... A shipped version is never mutated in place. Additive changes - a new optional field, a new endpoint, a new value you can ignore - stay inside the current version; anything you could break on gets a new one, and the old one keeps working and keeps being tested until its published sunset date.

v1 is current and nothing is deprecated, so no Deprecation or Sunset headers are being emitted yet.

Trying it interactively