> ## Documentation Index
> Fetch the complete documentation index at: https://docs.notifique.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> Adicione, consulte e remova uma identidade da lista de não contatar em poucos minutos.

<Tip>
  Do **cadastro na lista ao primeiro bloqueio** em poucos passos. A API Key precisa dos escopos `suppressions:read` e `suppressions:write`.
</Tip>

## Em poucas palavras

* **Adicione** e-mail, telefone, Telegram ou Instagram na lista global de não contatar.
* **Consulte** entradas com filtros por tipo, motivo e busca.
* **Remova** por ID ou por identidade quando o cliente voltar a aceitar mensagens.

Contexto: [Introdução](/suppressions-api/como-funciona/introducao). Escopos: [Escopos da API Key](/suppressions-api/como-funciona/escopos-da-api-key).

## Antes de começar

| Item                               | Obrigatório                                        |
| ---------------------------------- | -------------------------------------------------- |
| Chave com **`suppressions:write`** | Sim, para adicionar ou remover                     |
| Chave com **`suppressions:read`**  | Sim, para listar e consultar                       |
| Auth                               | `Authorization: Bearer sk_live_...` ou `x-api-key` |

Base URL: `https://api.notifique.dev`.

***

## 1. Adicionar na lista

Telefone bloqueia **SMS, WhatsApp, RCS e voz** de uma vez — como colocar o número no caderno da portaria.

```http theme={null}
POST /v1/suppressions
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx
```

```json theme={null}
{
  "type": "phone",
  "value": "+55 (11) 99999-0000",
  "reason": "manual",
  "note": "Cliente pediu para não ser contatado"
}
```

Resposta esperada: **201** (nova entrada) ou **200** (já existia, idempotente). A API normaliza o telefone para E.164 antes de salvar.

<Note>
  A inclusão é **idempotente**: se a identidade já estiver ativa, a API devolve a entrada existente sem duplicar.
</Note>

### E-mail, Telegram ou Instagram

```json theme={null}
{
  "type": "email",
  "value": "User@Example.com",
  "reason": "complaint",
  "note": "Marcou como spam"
}
```

Detalhes de formatação: [Normalização por tipo](/suppressions-api/como-funciona/normalizacao).

***

## 2. Listar e consultar

**Listar** com filtros opcionais:

```http theme={null}
GET /v1/suppressions?type=phone&limit=20&page=1
Authorization: Bearer sk_live_xxxxx
```

Parâmetros úteis: `type`, `reason`, `origin`, `channel`, `search`.

**Consultar uma entrada** pelo ID retornado no POST:

```http theme={null}
GET /v1/suppressions/{id}
Authorization: Bearer sk_live_xxxxx
```

***

## 3. Remover da lista

Por ID:

```http theme={null}
DELETE /v1/suppressions/{id}
Authorization: Bearer sk_live_xxxxx
```

Por identidade (sem precisar do ID):

```http theme={null}
DELETE /v1/suppressions/by-identity
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx
```

```json theme={null}
{
  "type": "email",
  "value": "cliente@example.com"
}
```

<Warning>
  Remover **reativa o envio imediatamente**. Se o endereço voltar a gerar bounce, complaint ou `STOP`, pode ser suprimido de novo automaticamente.
</Warning>

***

## 4. Importar em lote

Na API, envie até **100** itens por chamada:

```http theme={null}
POST /v1/suppressions/batch/add
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx
```

```json theme={null}
{
  "entries": [
    { "type": "phone", "value": "5511999990000", "reason": "manual" },
    { "type": "email", "value": "bounce@example.com", "reason": "bounce" }
  ]
}
```

Cada item retorna status individual: adicionada, já existente ou inválida.

No **painel** (**Audiência → Supressões**), importe CSV/XLSX com cabeçalhos `type,value,reason` — até 1.000 linhas, em lotes de 100. A coluna `channel` no CSV é contexto de importação no painel; na API v1 o bloqueio segue o `type` (telefone bloqueia sms/whatsapp/rcs/voice).

Para remover em lote: `POST /v1/suppressions/batch/remove` com `ids` e/ou `identities`.

***

## Próximos passos

* [Normalização](/suppressions-api/como-funciona/normalizacao): como a API trata cada tipo
* [Eventos dos webhooks](/suppressions-api/como-funciona/eventos-do-webhooks): saiba quando alguém entra ou sai da lista
* [Troubleshooting](/suppressions-api/como-funciona/troubleshooting): códigos comuns