# Receber e-mails (inbound)

> Como receber e-mails no Couryo por webhook. Domínio de recebimento com MX, o evento email.received, a caixa de entrada do painel, a triagem por IA (resposta, suporte, reclamação, descadastro, fora do escritório, spam) e a condição "respondeu" das sequências.

Fonte: https://couryo.com/docs/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`](https://couryo.com/docs/errors.md#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...).

```bash title="Adicionar reply.exemplo.com.br"
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:

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

```json
{ "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](https://couryo.com/docs/webhooks.md) 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_...`).

```json title="Corpo do email.received"
{
  "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"
  }
}
```

| Campo | O que é |
|---|---|
| `in_reply_to_email_id` | o e-mail que você enviou e que esta mensagem responde (pelos cabeçalhos `In-Reply-To` e `References`); `null` quando não é resposta a um envio do Couryo |
| `html` | já sem scripts, frames, formulários e atributos de evento |
| `attachments` | só os dados de cada anexo (nome, tipo, tamanho); **o conteúdo dos anexos não é guardado** |
| `verdicts` | as verificações de spam, vírus, SPF, DKIM e DMARC feitas na chegada (`pass`, `fail`, `gray`, `processing_failed`) |
| `auto_reply` | resposta automática pelos cabeçalhos (`Auto-Submitted`, `X-Autoreply`, `Precedence`) ou pelo assunto de "fora do escritório" |
| `ai` | a triagem por IA, quando ligada (abaixo) |
| `actions` | o que o Couryo fez por causa da mensagem: `suppressed_marketing` (pediu descadastro) e `sequence_exit` (saiu de uma sequência por ter respondido) |

## 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:

```bash
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](https://couryo.com/docs/ai.md) 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.

| Categoria | Quando |
|---|---|
| `reply` | uma pessoa respondendo, conversa normal |
| `support` | pede ajuda, relata um problema ou faz uma pergunta |
| `complaint` | cliente irritado, reclamação, ameaça cancelar |
| `unsubscribe` | pede para não receber mais, com qualquer palavra |
| `out_of_office` | resposta automática de ausência ou férias |
| `spam` | propaganda não pedida, golpe ou phishing |

**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](https://couryo.com/docs/sequences.md).
- `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](https://couryo.com/docs/mcp.md): o agente lê as respostas, os pedidos de suporte e as reclamações, com a triagem.