# Developer guide

> Everything you need to send transactional email with Couryo, over the REST API or from your AI agent (MCP).

Source: https://couryo.com/en/docs

Couryo is a transactional and product email API. You send over the **REST API** (`https://api.couryo.com/v1`) or from your AI agent with the [MCP server](https://couryo.com/en/docs/mcp.md) (`https://mcp.couryo.com`), follow every message on a timeline that includes the receiving server's original response, and get events by webhook. [SMTP](https://couryo.com/en/docs/smtp.md) is coming soon.

## Where to start

- [Quickstart](https://couryo.com/en/docs/quickstart.md): your first email in 5 minutes.
- [Authentication and keys](https://couryo.com/en/docs/authentication.md): `ck_live_` and `ck_test_` keys, scopes and allowed IPs.
- [Sending email](https://couryo.com/en/docs/sending.md): idempotency, batch, scheduling, tags and attachments.
- [Domains and DNS](https://couryo.com/en/docs/domains.md): what each record does and how to verify.
- [Webhooks](https://couryo.com/en/docs/webhooks.md): events signed with Standard Webhooks.
- [Errors](https://couryo.com/en/docs/errors.md): every code, with cause and fix.

## API principles

- **REST and JSON**, dates in ISO 8601 UTC (`2026-10-07T18:30:00Z`).
- **Prefixed, random IDs**: `msg_` (email), `dom_` (domain), `key_` (key), `whk_` (webhook), `evt_` (event), always 16 characters after the prefix.
- **No fake success.** A `202` only comes back once the email is in the queue. If something prevents sending, you get an error with a stable code and an explanation.
- **Idempotency on every POST**, with the `Idempotency-Key` header.
- **Cursor pagination**: `?limit=25&starting_after=<id>` returns `{ "data": [...], "has_more": true }`.
- **Messages in English or Portuguese**, following the `Accept-Language` header (the default is `pt-BR`; send `Accept-Language: en` for English).

## Endpoints

| Method and path | What it does |
|---|---|
| `POST /v1/emails` | sends an email |
| `POST /v1/emails/batch` | sends up to 100 emails in one request |
| `GET /v1/emails` and `GET /v1/emails/{id}` | lists emails or returns one, with its timeline |
| `POST /v1/emails/check` | checks an email before sending, without sending it |
| `GET` and `POST /v1/domains` | lists and creates domains |
| `GET` and `DELETE /v1/domains/{id}`, `POST /v1/domains/{id}/verify` | reads, deletes and verifies a domain |
| `GET` and `POST /v1/webhooks`, `GET`, `PATCH` and `DELETE /v1/webhooks/{id}` | webhooks |
| `GET` and `POST /v1/suppressions`, `DELETE /v1/suppressions/{email}` | suppression list |
| `GET /v1/events` | events, for when you missed a webhook |
| `GET /openapi.json` | the API's OpenAPI 3.1 spec, no key needed |

## For AI agents

This whole guide is available as Markdown. Add `.md` to any URL (for example, [/en/docs/quickstart.md](https://couryo.com/en/docs/quickstart.md.md)) or use [llms.txt](https://couryo.com/en/llms.txt) and [llms-full.txt](https://couryo.com/en/llms-full.txt). Pricing is at [/pricing.md](https://couryo.com/pricing.md).