# IA no Couryo

> Revisão antes de enviar (grátis), escrever e-mails e templates, variações de assunto, sequências, personalização a cada envio com {{#ai}} e pesquisa de empresa por domínio, com créditos de IA.

Fonte: https://couryo.com/docs/ai

O Couryo tem recursos de IA para escrever, revisar e personalizar e-mails, pela API (`/v1/ai/...`), pelo painel e pelo [MCP](https://couryo.com/docs/mcp.md). Duas regras valem para tudo:

- **A IA nunca impede um e-mail de sair.** Sem créditos, com erro ou passando do tempo, o e-mail vai com o conteúdo padrão e a linha do tempo registra o motivo.
- **Pesquisa só sobre empresas.** Nada de montar perfil de pessoa (veja [Pesquisa de empresa](#pesquisa-de-empresa)).

## Créditos

Cada recurso usa créditos de IA. A revisão antes do envio é grátis.

| Recurso | Rota | Créditos |
|---|---|---|
| Revisão antes de enviar | `POST /v1/ai/review` | grátis, até 200 por dia por conta |
| Escrever e-mail ou template | `POST /v1/ai/write` | 10 |
| 5 variações de assunto | `POST /v1/ai/subjects` | 3 |
| Gerar uma sequência | `POST /v1/ai/sequence` | 30 |
| Personalizar a cada envio | `personalize` em `POST /v1/emails` | 1 por destinatário |
| Pesquisa de empresa | `POST /v1/ai/research` | 60 |

**Créditos incluídos por mês:** Grátis 100, Pro 2.000, Escala 10.000 e Empresa 10.000 (ou o valor do contrato). Eles renovam a cada ciclo e **não acumulam**: o que sobra do mês vence quando o novo ciclo começa. No plano anual, o ciclo dos créditos é mensal.

**Pacotes avulsos** (pagamento único, Pix ou cartão no Brasil, cartão fora): 5.000 créditos por R$ 49 / US$ 9, 25.000 por R$ 199 / US$ 39 e 100.000 por R$ 690 / US$ 129. Valem 12 meses e acumulam. Os créditos do mês são usados antes dos avulsos.

**Quando acabarem**, você escolhe em **Cobrança > Créditos de IA**: parar (padrão) ou comprar 5.000 automaticamente no cartão salvo. Se a compra automática falhar, o Couryo para e avisa por e-mail. Também avisamos por e-mail e com uma faixa no painel quando o ciclo chega a 80% e a 100%.

Sem créditos, as rotas pagas respondem `402` com o código [`ai_credits_exhausted`](https://couryo.com/docs/errors.md#ai_credits_exhausted). Se a IA falhar, a resposta é `503` [`ai_unavailable`](https://couryo.com/docs/errors.md#ai_unavailable) e **nada é cobrado**.

```bash
curl https://api.couryo.com/v1/ai/credits \
  -H "Authorization: Bearer ck_live_..."
```

A resposta traz o saldo (`balance`), os créditos do mês e os avulsos, as próximas expirações e o consumo do ciclo por recurso. Escopo: `read`.

## Revisão antes de enviar

`POST /v1/ai/review` (escopo `send`) junta regras fixas e uma leitura rápida da IA. Mande `subject`, `html` e/ou `text` e `stream`:

```bash
curl https://api.couryo.com/v1/ai/review \
  -H "Authorization: Bearer ck_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "subject": "Seu pedido chegou", "html": "<p>Olá!</p>", "stream": "marketing" }'
```

A resposta tem `score` (0 a 100), `summary` e `findings`, cada um com `code`, `severity` (`error`, `warning`, `info`), `message` e `source` (`rules` ou `ai`). O que ela olha:

- risco de spam: palavras vigiadas pelos filtros, assunto ou texto em maiúsculas, excesso de exclamação, e-mail quase só de imagem;
- links: encurtadores, links vazios ou mal formados e links sem HTTPS;
- acessibilidade: imagem sem texto alternativo e falta da versão em texto;
- descadastro: e-mail de marketing sem link visível de descadastro;
- tom e clareza, pela IA.

É grátis até 200 revisões por dia por conta; depois, `429 rate_limited` até o dia seguinte. A [checagem](https://couryo.com/docs/sending.md#checagem-antes-do-envio) `POST /v1/emails/check` continua sem limite.

## Escrever e-mail ou template

`POST /v1/ai/write` (10 créditos) recebe `brief` (o que o e-mail precisa dizer), `kind` (`email` ou `template`), `language` (`pt-BR` ou `en`) e `tone` (opcional). Devolve `subject`, `html` (responsivo, simples, estilos inline), `text` e `variables`, as variáveis `{{...}}` sugeridas. Com `kind: "template"`, os dados pessoais viram variáveis, prontos para salvar como [template](https://couryo.com/docs/templates.md).

```json
{ "brief": "boas-vindas para um SaaS financeiro, com o próximo passo para configurar a conta", "kind": "template", "language": "pt-BR", "tone": "próximo" }
```

`POST /v1/ai/subjects` (3 créditos) devolve 5 assuntos para teste A/B a partir de `brief`, `subject`, `html` ou `text`.

## Gerar uma sequência

`POST /v1/ai/sequence` (30 créditos) recebe `goal`, `steps` (1 a 7) e `language`, e devolve os passos no mesmo formato usado para criar sequências:

```json
{
  "steps": [
    { "wait": { "amount": 0, "unit": "minutes" }, "subject": "...", "html": "...", "text": "..." },
    { "wait": { "amount": 2, "unit": "days" }, "subject": "...", "html": "...", "text": "..." }
  ]
}
```

`wait` é a espera antes de cada passo (`minutes`, `hours` ou `days`).

## Personalização

Marque no conteúdo os trechos que podem mudar com `{{#ai}}texto padrão{{/ai}}` e mande `personalize` no `POST /v1/emails` (ou em cada item do lote):

```json
{
  "from": "Loja <pedidos@exemplo.com.br>",
  "to": "ana@exemplo.com.br",
  "subject": "{{#ai}}Seu pedido chegou{{/ai}}",
  "html": "<p>{{#ai}}Olá! Seu pedido chegou.{{/ai}}</p><p>Equipe Loja</p>",
  "variables": { "nome": "Ana", "cidade": "Curitiba", "ultimo_pedido": "tênis de corrida" },
  "personalize": { "instructions": "cite o nome, a cidade e o último pedido", "fields": ["nome", "cidade", "ultimo_pedido"] }
}
```

Na hora do envio, a IA reescreve **só** os trechos marcados, usando as `variables` (com `fields`, só esses campos vão para a IA). Custa 1 crédito por destinatário e tem um orçamento de 4 segundos.

- **Sem créditos, com erro, passando de 4 segundos ou com uma resposta que não passa na checagem** (formato, link novo, HTML ativo), o e-mail sai com o texto padrão, sem as marcas, e a linha do tempo ganha o evento `ai_fallback` com o motivo (`no_credits`, `timeout`, `error`, `invalid_output`). Nada é cobrado quando a IA não é aplicada.
- **Chave de teste** (`ck_test_`): a personalização roda sem cobrar, com limite diário.
- **Sem `personalize`**, as marcas `{{#ai}}` são removidas e o texto padrão vai como está.
- Com `personalize` e nenhum trecho marcado, a API responde `400 invalid_field` com `param` = `personalize`.

A IA usa só os dados que você manda no envio. Ela não busca nada sobre a pessoa.

## Pesquisa de empresa

`POST /v1/ai/research` (60 créditos) recebe o **domínio de uma empresa** (`exemplo.com.br`; um endereço de site também vale) e devolve um resumo público: o que a empresa faz, setor, porte aproximado, produtos e tom da marca, com as páginas usadas em `sources`. Serve para personalizar e-mails B2B.

**Por que não pesquisamos pessoas:** montar o perfil de uma pessoa física com dados raspados da web seria tratar dados pessoais sem base legal e sem transparência, o que a LGPD não permite, e exporia você e o Couryo. Por isso a rota aceita só domínio: endereços de e-mail, nomes de pessoas e domínios de provedores de e-mail (como gmail.com) são recusados com `400 invalid_field` (`param` = `domain`), sem cobrar nada. Para falar com cada pessoa, use a [personalização](#personalizacao) com os dados que você já tem.

## No painel e no MCP

Os mesmos recursos estão no painel (editor de templates, sequências e **Cobrança > Créditos de IA**) e no [MCP](https://couryo.com/docs/mcp.md) pelas ferramentas `ai_write`, `ai_review` e `ai_credits`, com os mesmos escopos da chave.