# OpenAPI and Postman

> Source: https://developers.anymail.watch/openapi/

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`](/openapi.yaml) |
| Postman collection v2.1 | [`/anymail.postman_collection.json`](/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`:

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

Or a Python client with `openapi-python-client`:

```bash
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`](/llms.txt) lists every page with a one-line description.
- [`/llms-full.txt`](/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`](/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](/mcp-server/).

## Related

- [Overview](/)
- [Changelog](/changelog/)
- [MCP server](/mcp-server/)