IA no Couryo

O Couryo tem recursos de IA para escrever, revisar e personalizar e-mails, pela API (/v1/ai/...), pelo painel e pelo MCP. 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).

Créditos#

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

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. Se a IA falhar, a resposta é 503 ai_unavailable e nada é cobrado.

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:

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 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.

{ "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:

{
  "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):

{
  "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 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 pelas ferramentas ai_write, ai_review e ai_credits, com os mesmos escopos da chave.