# Supressão

> A lista de supressão do Couryo protege sua reputação. Motivos, fluxos, como consultar, adicionar e remover endereços pela API.

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

A lista de supressão guarda endereços para os quais o Couryo não envia mais. Ela protege sua reputação: insistir num endereço que não existe ou em quem reclamou derruba a entrega de todos os seus e-mails.

## Motivos

| `reason` | Quando entra | Vale para |
|---|---|---|
| `hard_bounce` | o endereço não existe (`5.1.x`) | todos os fluxos |
| `complaint` | o destinatário marcou como spam | todos os fluxos |
| `unsubscribe` | o destinatário se descadastrou | só o fluxo onde se descadastrou (em geral, `marketing`) |
| `manual` | você adicionou | o fluxo que você escolher |

Descadastro de marketing **nunca** bloqueia o transacional: quem saiu da newsletter continua recebendo o e-mail de troca de senha.

## O que acontece no envio

Se **alguns** destinatários estão suprimidos, o e-mail sai para os outros e a linha do tempo ganha um evento `suppressed` para cada endereço pulado. Se **todos** estão suprimidos, o envio é recusado com `422 recipient_suppressed`, e o campo `param` indica o primeiro (`to[0]`). No envio em lote, só o item afetado é recusado.

Devoluções temporárias (`4.x.x`) também levam à supressão quando o mesmo endereço volta em 3 dias diferentes.

## Consultar

```bash title="cURL"
curl "https://api.couryo.com/v1/suppressions?limit=25" \
  -H "Authorization: Bearer $COURYO_API_KEY"
```

```json title="Resposta"
{
  "data": [
    { "email": "maria@empresa.com.br", "reason": "hard_bounce", "stream": "all", "created_at": "2026-10-07T18:31:04Z" }
  ],
  "has_more": false
}
```

## Adicionar

```bash title="cURL"
curl https://api.couryo.com/v1/suppressions \
  -H "Authorization: Bearer $COURYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "nao-enviar@exemplo.com.br", "stream": "marketing" }'
```

## Remover

```bash title="cURL"
curl -X DELETE https://api.couryo.com/v1/suppressions/maria@empresa.com.br \
  -H "Authorization: Bearer $COURYO_API_KEY"
```

O endereço sai de todos os fluxos (`204`). Remova só quando tiver certeza de que o problema foi resolvido (por exemplo, a pessoa confirmou que o endereço voltou a funcionar).

## Escopos e filtros

- Listar exige escopo `read`; adicionar e remover, `admin`.
- A listagem aceita `q` (parte do endereço), `reason` e `limit` (padrão 100), com `starting_after` para a próxima página.
- Adicionar entra sempre com o motivo `manual`; `stream` pode ser `transactional`, `marketing` ou `all` (padrão). Um endereço que já está na lista devolve `409 already_suppressed`.