# Eventos e linha do tempo

> Cada etapa de um e-mail no Couryo, com horário, servidor de destino, código SMTP, resposta original e explicação em linguagem simples.

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

Todo e-mail tem uma linha do tempo. Cada evento traz o horário, o servidor de destino, o código SMTP, **a resposta original do servidor** e uma explicação em linguagem simples, no idioma da sua conta.

## Ver a linha do tempo

```bash title="cURL"
curl https://api.couryo.com/v1/emails/msg_9w2k7c1x0d4e5f6g \
  -H "Authorization: Bearer $COURYO_API_KEY"
```

```json title="Resposta"
{
  "id": "msg_9w2k7c1x0d4e5f6g",
  "from": "Loja Exemplo <pedidos@exemplo.com.br>",
  "to": ["ana@exemplo.com.br"],
  "subject": "Seu pedido 1042 foi confirmado",
  "stream": "transactional",
  "status": "delivered",
  "tags": { "tipo": "pedido" },
  "metadata": { "pedido_id": "1042" },
  "created_at": "2026-10-07T18:30:00Z",
  "events": [
    { "id": "evt_1a", "type": "accepted", "at": "2026-10-07T18:30:00Z" },
    { "id": "evt_1b", "type": "queued", "at": "2026-10-07T18:30:00Z" },
    { "id": "evt_1c", "type": "sent", "at": "2026-10-07T18:30:01Z", "recipient": "ana@exemplo.com.br" },
    {
      "id": "evt_1d",
      "type": "delivered",
      "at": "2026-10-07T18:30:02Z",
      "recipient": "ana@exemplo.com.br",
      "mx": "gmail-smtp-in.l.google.com",
      "provider": "gmail",
      "smtp_code": "250 2.0.0",
      "smtp_response": "250 2.0.0 OK 1791484202 a1b2c3d4e5f6 - gsmtp",
      "explanation": "O Gmail aceitou a mensagem."
    }
  ]
}
```

## Tipos de evento

| Evento | O que significa |
|---|---|
| `accepted` | a API recebeu e validou o pedido |
| `queued` | o e-mail está na fila (ou aguardando o `scheduled_at`) |
| `sent` | saiu do Couryo para o servidor de destino |
| `delivered` | o servidor de destino aceitou a mensagem |
| `deferred` | o destino pediu para tentar mais tarde (código `4xx`); o Couryo tenta de novo sozinho |
| `bounced` | o destino recusou de vez (código `5xx`) |
| `complained` | o destinatário marcou como spam |
| `opened` | o e-mail foi aberto (só no fluxo `marketing`; impreciso, porque alguns clientes de e-mail abrem tudo sozinhos) |
| `clicked` | um link foi clicado (só no fluxo `marketing`) |
| `suppressed` | não enviado porque o endereço está na [lista de supressão](https://couryo.com/docs/suppressions.md) |
| `failed` | não foi enviado: o conteúdo foi barrado pela checagem de entrada (phishing, link em lista de bloqueio) ou o envio falhou; o motivo vem no evento |

> "Entregue" quer dizer que o servidor de destino aceitou. Se foi para a caixa de entrada ou para o spam, nenhum provedor informa por mensagem. Por isso o painel mostra a entrega separada por provedor; o acompanhamento de reputação pelo agente de entregabilidade vem em breve.

## Status do e-mail

O campo `status` resume a linha do tempo: `queued`, `sent`, `delivered`, `deferred`, `bounced`, `complained`, `failed`, `suppressed` ou `captured` (chave de teste, não entregue).

## Provedores

O campo `provider` agrupa o destino: `gmail`, `microsoft`, `yahoo`, `uol`, `bol`, `terra`, `locaweb` ou `other`. O painel mostra a entrega separada por provedor.

## Devoluções: permanente, temporária e bloqueio

- **Permanente** (`5.1.x`, usuário ou domínio inexistente): o endereço vai na hora para a lista de supressão.
- **Temporária** (`4.x.x`): o Couryo tenta de novo sozinho. Se o mesmo endereço voltar em 3 dias diferentes (numa janela de 14 dias), ele é suprimido.
- **Bloqueio por política** (`5.7.x`, mensagens com "blocked" ou "spam"): o problema não é do destinatário. O endereço não é suprimido e a devolução não conta na sua taxa de devolução.

## Listar eventos

`GET /v1/events` (escopo `read`) lista os eventos de todos os e-mails do projeto, do mais novo para o mais antigo, cada um com o `email_id`. Útil para quem perdeu webhooks ou prefere buscar de tempos em tempos. Filtros: `type` (por exemplo, `bounced`) e `email_id`.

```bash title="cURL"
curl "https://api.couryo.com/v1/events?type=bounced&limit=50" \
  -H "Authorization: Bearer $COURYO_API_KEY"
```

```json title="Resposta"
{ "data": [{ "id": "evt_7d3k9s0a2m5n8b1c", "email_id": "msg_9w2k7c1x0d4e5f6g", "type": "bounced", "at": "2026-10-07T18:31:04Z", "recipient": "maria@empresa.com.br", "smtp_code": "550 5.1.1" }], "has_more": true }
```

Para a próxima página, passe `starting_after` com o `id` do último item.

## Por quanto tempo

A linha do tempo fica disponível pelo prazo de logs do seu plano: 7 dias no Grátis, 30 dias no Pro e 90 dias no Escala.