Reference Markdown

OpenAPI and Postman

The REST API is described in an OpenAPI 3.1 document. A Postman collection is generated from it on every build of this site, so the two never disagree.

File URL
OpenAPI 3.1 (YAML) /openapi.yaml
Postman collection v2.1 /anymail.postman_collection.json

The document covers every endpoint of /api/v1: paths, parameters, request bodies with an example, response schemas, the bearerAuth and oauth2 security schemes with the read and write scopes, and the shared X-Workspace and Idempotency-Key headers. A check on every build compares it with the routes of the application, in both directions, and validates it against the OpenAPI 3.1 schema.

Postman#

  1. In Postman, select Import and paste the collection URL https://developers.anymail.watch/anymail.postman_collection.json.
  2. Open the collection, then Variables. Set token to your API token. baseUrl is already https://app.anymail.watch/api/v1.
  3. Requests are grouped by resource. Path parameters such as :id are in the Params tab. Optional query parameters and headers are listed but turned off.

The collection uses Bearer authentication at the collection level, so every request carries the token.

Generate a client#

Any OpenAPI 3.1 generator can read the document. For example, TypeScript types with openapi-typescript:

npx openapi-typescript https://developers.anymail.watch/openapi.yaml -o anymail.d.ts

Or a Python client with openapi-python-client:

pipx run openapi-python-client generate --url https://developers.anymail.watch/openapi.yaml

The pages of this site give the details that a schema cannot hold: the exact error messages, the order of checks and the meaning of each status.

For LLMs and agents#

  • /llms.txt lists every page with a one-line description.
  • /llms-full.txt holds the text of every page in one file.
  • Every page is also plain Markdown at its path with .md, for example /campaigns.md. The Markdown link at the top of each page points there.

An agent that should act on anymail can use the MCP server.