The REST API reference

What this screen is for

REST API is the reference for calling MailGuardHQ from your own code. Everything the product does is an API call - the web app is just another caller with no back door of its own - so anything you can do on the site, you can do from a script.

It is a reference rather than a tutorial: it states the rules that apply to every call, then lists every endpoint. The one call you can make with no account at all is at the top.

What each part of the page does

Start here

A complete, copy-pasteable first call. It runs the same thirteen checks the free check on the home page runs, and needs no credential.

Authentication

The two kinds of credential, the scope vocabulary, and the four ceilings that decide what a call may actually do. Read this before minting a token, not after a call is refused.

Conventions

The rules that hold for every endpoint: one error shape, paging, idempotency on writes, rate limits, and what we promise about breaking changes.

Every endpoint

The full list, grouped. It is generated from the API contract, so it cannot list a route the API does not serve.

Trying it interactively

The Swagger console, and why it is gated. It is a real request generator aimed at the live API, so it is not open to anonymous visitors.

What to do next

1. Run the anonymous check call. It proves your setup works before any credential is involved.
2. Create a free account and mint a token, naming only the scopes you need - a token that cannot do a thing cannot do it by accident either.
3. Generate a client from the OpenAPI document rather than hand-writing one. It is the same document the API is built from, so a generated client cannot drift from it.
4. Send an Idempotency-Key on every write. A request that times out has still possibly happened, and the key is what makes the retry safe.

What this screen does not do