Receber e-mails (inbound)

O Couryo recebe os e-mails que chegam num domínio de recebimento seu, como reply.suaempresa.com.br, e entrega cada um no seu sistema pelo webhook email.received. As respostas aos seus e-mails, os pedidos de suporte e as reclamações chegam já ligados ao e-mail que você enviou e, se quiser, classificados por IA.

Disponível nos planos Pro, Escala e Empresa. No Grátis, as rotas respondem 403 com o código inbound_not_available e upgrade_options.

1. Adicionar o domínio de recebimento#

Use um subdomínio de um domínio já verificado no projeto (recomendado) ou o próprio domínio verificado. Com um subdomínio, o MX do domínio principal continua indo para as suas caixas de e-mail (Google Workspace, Microsoft 365...).

curl https://api.couryo.com/v1/inbound-domains \
  -H "Authorization: Bearer $COURYO_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "reply.exemplo.com.br" }'

A resposta traz o registro para publicar no seu DNS:

{
  "id": "ind_8k2m4q6s0w1y3a5c",
  "name": "reply.exemplo.com.br",
  "status": "pending",
  "records": [
    { "purpose": "inbound", "type": "MX", "name": "reply.exemplo.com.br", "value": "inbound-smtp.couryo.com", "priority": 10, "status": "pending" }
  ],
  "created_at": "2026-10-08T18:30:00Z"
}

Crie o MX com prioridade 10 no nome indicado e clique em Conferir agora no painel (em Recebidos) ou chame POST /v1/inbound-domains/{id}/verify. O status vira verified quando o MX aponta para o Couryo; conferimos sozinhos a cada 10 minutos nas primeiras 72 horas e, depois, uma vez por dia.

2. Pedir as respostas no domínio de recebimento#

Para as respostas chegarem ao Couryo, use um endereço do domínio de recebimento no reply_to dos seus envios:

{ "from": "Loja <pedidos@exemplo.com.br>", "reply_to": "atendimento@reply.exemplo.com.br", "to": "maria@cliente.com.br", "subject": "Seu pedido saiu", "html": "..." }

Qualquer endereço do domínio de recebimento é aceito: atendimento@, vendas@, pedido-4821@...

3. Receber pelo webhook#

Crie um webhook com o evento email.received. A chamada tem a mesma assinatura (Standard Webhooks) e o mesmo reenvio dos outros eventos; o webhook-id é o ID do e-mail recebido (inb_...).

{
  "type": "email.received",
  "timestamp": "2026-10-08T18:31:04Z",
  "data": {
    "id": "inb_3f9k1m5q7s2u4w6y",
    "project_id": "prj_...",
    "domain": "reply.exemplo.com.br",
    "from": "maria@cliente.com.br",
    "from_name": "Maria Souza",
    "to": ["atendimento@reply.exemplo.com.br"],
    "cc": [],
    "reply_to": [],
    "subject": "Re: Seu pedido saiu",
    "text": "Oi! Chegou certinho, obrigada.",
    "html": "<p>Oi! Chegou certinho, obrigada.</p>",
    "headers": { "message_id": "CAF...@mail.gmail.com", "in_reply_to": "msg_7h2kq9w4x1abcdef@exemplo.com.br", "references": ["msg_7h2kq9w4x1abcdef@exemplo.com.br"], "date": "2026-10-08T18:31:00Z", "auto_submitted": null, "list_id": null },
    "attachments": [{ "filename": "foto.jpg", "content_type": "image/jpeg", "size": 48213, "content_id": null, "inline": false }],
    "size": 71234,
    "verdicts": { "spam": "pass", "virus": "pass", "spf": "pass", "dkim": "pass", "dmarc": "pass" },
    "auto_reply": false,
    "in_reply_to_email_id": "msg_7h2kq9w4x1abcdef",
    "ai_status": "done",
    "ai": { "category": "reply", "summary": "Cliente confirma que recebeu o pedido.", "priority": "normal" },
    "actions": [],
    "received_at": "2026-10-08T18:31:02Z"
  }
}

Listar pela API#

GET /v1/inbound lista os recebidos, do mais novo para o mais antigo, com paginação por cursor e os filtros category, status (received ou dropped) e q (parte do remetente ou do assunto). GET /v1/inbound/{id} traz um. Escopo read.

No painel, Recebidos é a caixa de entrada do projeto, com filtros por categoria, a visualização segura do HTML (conteúdo externo bloqueado) e os domínios de recebimento.

Triagem por IA#

Ligue em Recebidos > Triagem por IA ou pela API:

curl -X PATCH https://api.couryo.com/v1/inbound-settings \
  -H "Authorization: Bearer $COURYO_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "ai": true }'

Cada e-mail recebido ganha ai.category, um resumo de uma linha (ai.summary) e a prioridade (low, normal ou high). Custa 1 crédito de IA por e-mail. Sem créditos ou se a IA falhar, o e-mail chega igual, com ai_status no_credits ou failed e nada cobrado.

Descadastro pedido por texto: quando a categoria é unsubscribe, o remetente sai do fluxo marketing do projeto na hora (supressão com motivo unsubscribe, as sequências dele param) e a mensagem fica com actions: ["suppressed_marketing"]. Os e-mails transacionais (senha, cobrança) continuam.

Sequências: "respondeu"#

• A condição { "kind": "replied" } é verdadeira quando o contato respondeu a algum e-mail da inscrição; com step_id, a um e-mail específico. Veja Sequências.
• settings.exit_on_reply: true tira o contato da sequência assim que ele responde (motivo replied).
• "Fora do escritório" não conta como resposta, nem respostas automáticas e spam.

Regras#

• Spam e vírus marcados na chegada são descartados: o e-mail aparece com status: "dropped" e dropped_reason (spam ou virus), sem conteúdo e sem webhook.
• Tamanho: até 10 MB por mensagem; acima disso, dropped_reason: "too_large".
• Plano: se a conta voltar para o Grátis, os e-mails que chegarem são registrados com dropped_reason: "plan", sem conteúdo.
• Retenção: os recebidos ficam o mesmo tempo que os logs do plano (Pro 30 dias, Escala 90, Empresa 365).
• Privacidade: os endereços completos aparecem só para a sua conta (API, painel e o seu MCP).

Pelo MCP#

list_inbound e get_inbound (escopo read) no servidor MCP: o agente lê as respostas, os pedidos de suporte e as reclamações, com a triagem.