# Use from AI agents

These docs are written to be read by people and by machines. Everything an agent needs is available as plain text.

## Machine-readable docs

| Resource | URL | Use it for |
| --- | --- | --- |
| `llms.txt` | [`/llms.txt`](https://docs.salchimail.com/llms.txt) | An index of the docs with one line per page |
| `llms-full.txt` | [`/llms-full.txt`](https://docs.salchimail.com/llms-full.txt) | Every guide and the API reference in a single file |
| Markdown pages | Add `.md` to any page URL, for example [`/quickstart.md`](https://docs.salchimail.com/quickstart.md) | Reading one page without HTML |
| API reference in Markdown | [`/reference.md`](https://docs.salchimail.com/reference.md) | Every operation, schema and example |
| OpenAPI 3.1 | [`/openapi.json`](https://docs.salchimail.com/openapi.json) · [`/openapi.yaml`](https://docs.salchimail.com/openapi.yaml) | Generating clients and tool definitions |

All of them are served with `Access-Control-Allow-Origin: *`.

## MCP server

**Coming soon.** A remote MCP server at `mcp.salchimail.com` will let an agent verify addresses, run batches and read usage with your API key. This page will link to it when it is available.

## Agent skill

**Coming soon.** A skill that teaches a coding assistant how to integrate SalchiMail. This page will link to it when it is available.

Until both exist, point your agent at [`/llms.txt`](https://docs.salchimail.com/llms.txt) or at the OpenAPI contract: it is enough to call the API correctly.

## Rules to give your agent

If you write the instructions yourself, include these:

- The API key is a secret. Read it from an environment variable, send it only to `https://api.salchimail.com` and never print it.
- Build and test with a `sk_test_` key: results are simulated and no credits are used ([Test mode](https://docs.salchimail.com/test-mode.md)).
- Never treat `unknown` as `invalid` ([Verdicts and reason codes](https://docs.salchimail.com/verdicts.md)).
- For more than a few addresses, create a batch instead of looping over `POST /verify` ([Clean a list in batches](https://docs.salchimail.com/batches.md)).
- Send an `Idempotency-Key` on every `POST`, and reuse it on retries ([Idempotency](https://docs.salchimail.com/idempotency.md)).
- Branch on `verdict`, `reason_code` and the error `code`. Never parse `reason` or `message`.
- A verification never sends email. Do not tell users that a message was sent to the address.
