# Guia do desenvolvedor

> Tudo para enviar e-mail transacional pelo Couryo, pela API REST ou pelo seu agente de IA (MCP).

Fonte: https://couryo.com/docs

O Couryo é uma API de e-mail transacional e de produto. Você envia pela **API REST** (`https://api.couryo.com/v1`) ou pelo seu agente de IA com o [servidor MCP](https://couryo.com/docs/mcp.md) (`https://mcp.couryo.com`), acompanha cada mensagem numa linha do tempo com a resposta original do servidor de destino e recebe os eventos por webhook. O [SMTP](https://couryo.com/docs/smtp.md) chega em breve.

## Por onde começar

- [Início rápido](https://couryo.com/docs/quickstart.md): o primeiro e-mail em 5 minutos.
- [Autenticação e chaves](https://couryo.com/docs/authentication.md): chaves `ck_live_` e `ck_test_`, escopos e IPs permitidos.
- [Enviar e-mail](https://couryo.com/docs/sending.md): idempotência, lote, agendamento, tags e anexos.
- [Domínios e DNS](https://couryo.com/docs/domains.md): o que cada registro faz e como verificar.
- [Webhooks](https://couryo.com/docs/webhooks.md): eventos assinados no padrão Standard Webhooks.
- [Erros](https://couryo.com/docs/errors.md): todos os códigos, com causa e correção.

## Princípios da API

- **REST com JSON**, datas em ISO 8601 UTC (`2026-10-07T18:30:00Z`).
- **IDs com prefixo** e aleatórios: `msg_` (e-mail), `dom_` (domínio), `key_` (chave), `whk_` (webhook), `evt_` (evento), sempre com 16 caracteres depois do prefixo.
- **Nunca há sucesso falso.** A resposta `202` só sai quando o e-mail entrou na fila. Se algo impede o envio, você recebe um erro com código estável e explicação.
- **Idempotência em todo POST**, com o cabeçalho `Idempotency-Key`.
- **Paginação por cursor**: `?limit=25&starting_after=<id>` devolve `{ "data": [...], "has_more": true }`.
- **Mensagens em português ou inglês**, conforme o cabeçalho `Accept-Language` (o padrão é `pt-BR`).

## Endpoints

| Método e caminho | O que faz |
|---|---|
| `POST /v1/emails` | envia um e-mail |
| `POST /v1/emails/batch` | envia até 100 e-mails numa chamada |
| `GET /v1/emails` e `GET /v1/emails/{id}` | lista e-mails ou traz um, com a linha do tempo |
| `POST /v1/emails/check` | checa um e-mail antes de enviar, sem enviar |
| `GET` e `POST /v1/domains` | lista e cria domínios |
| `GET` e `DELETE /v1/domains/{id}`, `POST /v1/domains/{id}/verify` | consulta, apaga e verifica um domínio |
| `GET` e `POST /v1/webhooks`, `GET`, `PATCH` e `DELETE /v1/webhooks/{id}` | webhooks |
| `GET` e `POST /v1/suppressions`, `DELETE /v1/suppressions/{email}` | lista de supressão |
| `GET /v1/events` | eventos, para quem perdeu um webhook |
| `GET /openapi.json` | a especificação OpenAPI 3.1 da API, sem chave |

## Para agentes de IA

Esta documentação inteira existe em Markdown. Acrescente `.md` a qualquer endereço (por exemplo, [/docs/quickstart.md](https://couryo.com/docs/quickstart.md.md)) ou use o [llms.txt](https://couryo.com/llms.txt) e o [llms-full.txt](https://couryo.com/llms-full.txt). Os preços estão em [/precos.md](https://couryo.com/precos.md).