# Supressões API

> Consulte e gerencie os endereços para os quais o Emailit não envia e-mails.

URL base: `https://api.emailit.com/v2`. Autentique-se com `Authorization: Bearer <API key>`.

## Criar uma supressão — POST /suppressions

> Adicione um endereço à lista de supressão, permanentemente ou até uma data que você escolher, para que o Emailit pare de enviar para ele.

# Criar uma supressão

Adiciona um endereço à lista de supressão do seu workspace. Os e-mails de API e SMTP para um endereço com uma supressão `recipient` recebem o status `suppressed` em vez de serem enviados, e as campanhas ignoram os endereços suprimidos. Requer uma chave de API com escopo `full`.

`POST /suppressions`

## Corpo da requisição

- `email` (string, obrigatório): Endereço a suprimir. O Emailit o armazena em minúsculas.

- `type` (string): Tipo de supressão. Padrão: `recipient`. O Emailit usa `recipient`, `bounce`, `complaint` e `unsubscribe`. Apenas as supressões `recipient` bloqueiam os e-mails enviados pela API e por SMTP. As campanhas ignoram todos os endereços com uma supressão ativa de qualquer tipo. Um endereço pode ter uma supressão por tipo.

- `reason` (string): Observação em texto livre, por exemplo `manual` ou `Asked to stop receiving invoices`.

- `keep_until` (string | number | null): Quando a supressão expira. Aceita um timestamp ISO 8601 (`2026-12-31T00:00:00Z`), um timestamp Unix em segundos (`1798675200`) ou linguagem natural em inglês, como `in 30 days` ou `tomorrow at 9am`. Omita-o ou envie `null` para uma supressão permanente. Depois desse momento, a supressão deixa de bloquear os envios. Ela continua na lista até que você a exclua.

## Retorno

Retorna `201 Created` com o objeto de supressão. O Emailit também envia um evento de webhook [`suppression.created`](/pt/docs/webhooks/events/suppression/created/).

| Status | Quando |
| --- | --- |
| `400` | `email` não é um endereço válido ou `keep_until` não pode ser interpretado (o corpo tem uma string `error`), ou `email` está ausente (erro de validação padrão). |
| `409` | O endereço já tem uma supressão deste tipo. O corpo inclui a supressão existente em `existing`. |

**Requisição** `POST /suppressions`

**Node.js**

```javascript
import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const suppression = await emailit.suppressions.create({
    email: 'ada@example.com',
    reason: 'manual'
});
```

**Python**

```python
from emailit import EmailitClient
client = EmailitClient("your_api_key")

suppression = client.suppressions.create({
    "email": "ada@example.com",
    "reason": "manual"
})
```

**PHP**

```php
$emailit = Emailit::client('your_api_key');

$suppression = $emailit->suppressions()->create([
    'email' => 'ada@example.com',
    'reason' => 'manual'
]);
```

**Ruby**

```ruby
require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

suppression = client.suppressions.create(
    email: "ada@example.com",
    reason: "manual"
)
```

**Go**

```go
import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

suppression, err := client.Suppressions.Create(&emailit.CreateSuppressionRequest{
    Email: "ada@example.com",
    Reason: "manual",
})
```

**Rust**

```rust
use emailit::Emailit;
let emailit = Emailit::new("your_api_key");

let suppression = emailit.suppressions.create(
    emailit::types::CreateSuppressionParams::new("ada@example.com")
        .with_reason("manual")
).await?;
```

**Java**

```java
import com.emailit.*;
import com.emailit.params.*;
EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject suppression = emailit.suppressions().create(
    SuppressionCreateParams.builder()
        .setEmail("ada@example.com")
        .setReason("manual")
        .build()
);
```

**.NET**

```csharp
using Emailit;
var emailit = new EmailitClient("your_api_key");

var suppression = emailit.Suppressions.Create(new SuppressionCreateOptions {
    Email = "ada@example.com",
    Reason = "manual"
});
```

**Laravel**

```php
use Emailit\Laravel\Facades\Emailit;

$suppression = Emailit::suppressions()->create([
    'email' => 'ada@example.com',
    'reason' => 'manual'
]);
```

**cURL**

```bash
curl -X POST https://api.emailit.com/v2/suppressions \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ada@example.com",
    "reason": "manual"
  }'
```

**201**

```json
{
  "object": "suppression",
  "id": "sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e",
  "type": "recipient",
  "email": "ada@example.com",
  "reason": "manual",
  "created_at": "2026-10-01T09:30:12.481000+00:00",
  "keep_until": null
}
```

**400**

```json
{
  "error": "Invalid keep_until format. Accepts ISO 8601, Unix timestamp, or natural language like \"tomorrow at 9am\"."
}
```

**409**

```json
{
  "error": "Suppression already exists for this email and type",
  "existing": {
    "object": "suppression",
    "id": "sup_2xKz0Pq5Rm8Nw2Tb7YdLc4HsE1a",
    "type": "recipient",
    "email": "ada@example.com",
    "reason": "too many bounces",
    "created_at": "2026-09-12T16:04:51.207000+00:00",
    "keep_until": null
  }
}
```

---
Fonte: https://emailit.com/pt/docs/api-reference/suppressions/create/

## Obter uma supressão — GET /suppressions/{id}

> Obtenha uma supressão pelo ID ou pelo endereço de e-mail suprimido, incluindo o tipo, o motivo e a data de expiração.

# Obter uma supressão

Retorna uma supressão, buscada pelo ID ou pelo endereço de e-mail. Requer uma chave de API com escopo `full`.

`GET /suppressions/:id`

## Parâmetros de caminho

- `id` (string, obrigatório): ID da supressão (`sup_…`) ou o endereço suprimido. Codifique o endereço para URL, por exemplo `ada%40example.com`. Um endereço pode ter uma supressão por tipo. Quando você busca pelo endereço, o Emailit retorna uma delas; use o ID para obter um tipo específico.

## Retorno

Retorna `200 OK` com o objeto de supressão. Uma supressão cujo `keep_until` já passou não bloqueia mais os envios.

Retorna `400` se `id` não for nem um ID `sup_` nem um endereço de e-mail válido, e `404` se nenhuma supressão corresponder.

**Requisição** `GET /suppressions/{id}`

**Node.js**

```javascript
import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const suppression = await emailit.suppressions.get('sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e');
```

**Python**

```python
from emailit import EmailitClient
client = EmailitClient("your_api_key")

suppression = client.suppressions.get("sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e")
```

**PHP**

```php
$emailit = Emailit::client('your_api_key');

$suppression = $emailit->suppressions()->get('sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e');
```

**Ruby**

```ruby
require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

suppression = client.suppressions.get("sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e")
```

**Go**

```go
import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

suppression, err := client.Suppressions.Get("sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e")
```

**Rust**

```rust
use emailit::Emailit;
let emailit = Emailit::new("your_api_key");

let suppression = emailit.suppressions.get("sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e").await?;
```

**Java**

```java
import com.emailit.*;
import com.emailit.params.*;
EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject suppression = emailit.suppressions().get("sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e");
```

**.NET**

```csharp
using Emailit;
var emailit = new EmailitClient("your_api_key");

var suppression = emailit.Suppressions.Get("sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e");
```

**Laravel**

```php
use Emailit\Laravel\Facades\Emailit;

$suppression = Emailit::suppressions()->get('sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e');
```

**cURL**

```bash
curl https://api.emailit.com/v2/suppressions/sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e \
  -H "Authorization: Bearer your_api_key"
```

**200**

```json
{
  "object": "suppression",
  "id": "sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e",
  "type": "recipient",
  "email": "ada@example.com",
  "reason": "too many bounces",
  "created_at": "2026-10-01T09:30:12.481000+00:00",
  "keep_until": null
}
```

**400**

```json
{
  "error": "Invalid identifier. Must be a suppression ID (sup_xxx) or valid email address."
}
```

**404**

```json
{
  "error": "Suppression not found"
}
```

---
Fonte: https://emailit.com/pt/docs/api-reference/suppressions/get/

## Atualizar uma supressão — POST /suppressions/{id}

> Altere o endereço, o tipo, o motivo ou a data de expiração de uma supressão, buscada pelo ID ou pelo endereço suprimido.

# Atualizar uma supressão

Atualiza uma supressão. Envie apenas os campos que você quer alterar; pelo menos um é obrigatório. Requer uma chave de API com escopo `full`.

`POST /suppressions/:id`

## Parâmetros de caminho

- `id` (string, obrigatório): ID da supressão (`sup_…`) ou o endereço suprimido, codificado para URL (`ada%40example.com`). Quando um endereço tiver supressões de vários tipos, use o ID.

## Corpo da requisição

- `email` (string): Novo endereço. Armazenado em minúsculas.

- `type` (string): Novo tipo: `recipient`, `bounce`, `complaint` ou `unsubscribe`. Apenas as supressões `recipient` bloqueiam os envios pela API e por SMTP.

- `reason` (string): Novo motivo, em texto livre.

- `keep_until` (string | number | null): Nova data de expiração, nos mesmos formatos aceitos na [criação](/pt/docs/api-reference/suppressions/create/): ISO 8601, um timestamp Unix em segundos ou linguagem natural em inglês, como `in 30 days`. Envie `null` para tornar a supressão permanente.

## Retorno

Retorna `200 OK` com a supressão atualizada. O Emailit também envia um evento de webhook [`suppression.updated`](/pt/docs/webhooks/events/suppression/updated/).

| Status | Quando |
| --- | --- |
| `400` | O corpo não tem nenhum dos campos acima, `email` é inválido ou `keep_until` não pode ser interpretado. |
| `404` | Nenhuma supressão corresponde a `id`. |
| `409` | Já existe outra supressão para o novo endereço e tipo. |

**Requisição** `POST /suppressions/{id}`

**Node.js**

```javascript
import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const suppression = await emailit.suppressions.update('sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e', {
    reason: 'Asked to pause invoices until January'
});
```

**Python**

```python
from emailit import EmailitClient
client = EmailitClient("your_api_key")

suppression = client.suppressions.update("sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e", {
    "reason": "Asked to pause invoices until January"
})
```

**PHP**

```php
$emailit = Emailit::client('your_api_key');

$suppression = $emailit->suppressions()->update('sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e', [
    'reason' => 'Asked to pause invoices until January'
]);
```

**Ruby**

```ruby
require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

suppression = client.suppressions.update("sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e", reason: "Asked to pause invoices until January")
```

**Go**

```go
import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

suppression, err := client.Suppressions.Update("sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e", &emailit.UpdateSuppressionRequest{
    Reason: "Asked to pause invoices until January",
})
```

**Rust**

```rust
use emailit::Emailit;
let emailit = Emailit::new("your_api_key");

let suppression = emailit.suppressions.update(
    "sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e",
    emailit::types::UpdateSuppressionParams {
        reason: Some("Asked to pause invoices until January".into()),
        ..Default::default()
    }
).await?;
```

**Java**

```java
import com.emailit.*;
import com.emailit.params.*;
EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject suppression = emailit.suppressions().update("sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e",
    SuppressionUpdateParams.builder()
        .setReason("Asked to pause invoices until January")
        .build()
);
```

**.NET**

```csharp
using Emailit;
var emailit = new EmailitClient("your_api_key");

var suppression = emailit.Suppressions.Update("sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e",
    new SuppressionUpdateOptions { Reason = "Asked to pause invoices until January" });
```

**Laravel**

```php
use Emailit\Laravel\Facades\Emailit;

$suppression = Emailit::suppressions()->update('sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e', [
    'reason' => 'Asked to pause invoices until January'
]);
```

**cURL**

```bash
curl -X POST https://api.emailit.com/v2/suppressions/sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Asked to pause invoices until January"}'
```

**200**

```json
{
  "object": "suppression",
  "id": "sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e",
  "type": "recipient",
  "email": "ada@example.com",
  "reason": "Asked to pause invoices until January",
  "created_at": "2026-10-01T09:30:12.481000+00:00",
  "keep_until": "2027-01-01T00:00:00.000000+00:00"
}
```

**400**

```json
{
  "error": "No valid fields provided for update. Provide at least one of: email, type, reason, keep_until"
}
```

**404**

```json
{
  "error": "Suppression not found"
}
```

**409**

```json
{
  "error": "Another suppression already exists for this email and type combination"
}
```

---
Fonte: https://emailit.com/pt/docs/api-reference/suppressions/update/

## Listar supressões — GET /suppressions

> Liste os endereços suprimidos do seu workspace com busca, filtros, ordenação e paginação por páginas.

# Listar supressões

Retorna as supressões do seu workspace, das mais recentes para as mais antigas. A listagem inclui as supressões que o Emailit adiciona automaticamente após bounces e reclamações, e as supressões expiradas cujo `keep_until` já passou. Requer uma chave de API com escopo `full`.

`GET /suppressions`

## Parâmetros de consulta

- `page` (integer): Número da página, a partir de `1`. Padrão: `1`.

- `limit` (integer): Supressões por página, de `1` a `100`. Padrão: `10`.

- `search` (string): Busca sem diferenciar maiúsculas de minúsculas no endereço ou no motivo. `q` funciona como alias.

- `match` (string): `all` (padrão) exige que todos os filtros `key.condition` correspondam. `or` aceita qualquer um deles. Consulte [Filtragem](/pt/docs/api-reference/filtering/).

- `sort` (string): Chave de ordenação: `email`, `reason`, `type` ou `created_at` (padrão).

- `order` (string): Direção da ordenação: `asc` ou `desc` (padrão).

## Filtros

Chaves de filtro e de ordenação: consulte [Filtragem](https://emailit.com/pt/docs/api-reference/filtering/).

Neste endpoint, `order` só aceita `asc` ou `desc`. Passe a chave de ordenação em `sort`, por exemplo `sort=email&order=asc`.

## Retorno

Retorna `200 OK` com as supressões em `data`, além de `next_page_url` e `previous_page_url` (`null` quando não há página seguinte ou anterior). As URLs das páginas mantêm a sua busca, os seus filtros e a sua ordenação.

**Requisição** `GET /suppressions`

**Node.js**

```javascript
import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const suppressions = await emailit.suppressions.list();
```

**Python**

```python
from emailit import EmailitClient
client = EmailitClient("your_api_key")

suppressions = client.suppressions.list()
```

**PHP**

```php
$emailit = Emailit::client('your_api_key');

$suppressions = $emailit->suppressions()->list();
```

**Ruby**

```ruby
require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

suppressions = client.suppressions.list
```

**Go**

```go
import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

suppressions, err := client.Suppressions.List(nil)
```

**Rust**

```rust
use emailit::Emailit;
let emailit = Emailit::new("your_api_key");

let suppressions = emailit.suppressions.list(None).await?;
```

**Java**

```java
import com.emailit.*;
import com.emailit.params.*;
EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject suppressions = emailit.suppressions().list();
```

**.NET**

```csharp
using Emailit;
var emailit = new EmailitClient("your_api_key");

var suppressions = emailit.Suppressions.List();
```

**Laravel**

```php
use Emailit\Laravel\Facades\Emailit;

$suppressions = Emailit::suppressions()->list();
```

**cURL**

```bash
curl https://api.emailit.com/v2/suppressions \
  -H "Authorization: Bearer your_api_key"
```

**200**

```json
{
  "data": [
    {
      "object": "suppression",
      "id": "sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e",
      "type": "recipient",
      "email": "ada@example.com",
      "reason": "too many bounces",
      "created_at": "2026-10-01T09:30:12.481000+00:00",
      "keep_until": null
    },
    {
      "object": "suppression",
      "id": "sup_2xKz0Pq5Rm8Nw2Tb7YdLc4HsE1a",
      "type": "complaint",
      "email": "grace@example.com",
      "reason": "complaint",
      "created_at": "2026-09-28T13:17:40.912000+00:00",
      "keep_until": null
    }
  ],
  "next_page_url": "/v2/suppressions?limit=10&page=2",
  "previous_page_url": null
}
```

**401**

```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid API key"
}
```

---
Fonte: https://emailit.com/pt/docs/api-reference/suppressions/list/

## Excluir uma supressão — DELETE /suppressions/{id}

> Remova uma supressão pelo ID ou pelo endereço suprimido para que o Emailit possa enviar para esse endereço de novo.

# Excluir uma supressão

Exclui uma supressão para que o endereço possa receber e-mails de novo. Requer uma chave de API com escopo `full`.

`DELETE /suppressions/:id`

## Parâmetros de caminho

- `id` (string, obrigatório): ID da supressão (`sup_…`) ou o endereço suprimido, codificado para URL (`ada%40example.com`). Uma requisição por endereço exclui uma supressão. Se o endereço tiver supressões de vários tipos, exclua cada uma pelo ID ou repita a requisição até que ela retorne `404`.

## Retorno

Retorna `200 OK` com o `id` e o `email` da supressão excluída e `deleted: true`. O Emailit também envia um evento de webhook [`suppression.deleted`](/pt/docs/webhooks/events/suppression/deleted/).

Retorna `400` se `id` não for nem um ID `sup_` nem um endereço de e-mail válido, e `404` se nenhuma supressão corresponder.

**Requisição** `DELETE /suppressions/{id}`

**Node.js**

```javascript
import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

await emailit.suppressions.delete('sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e');
```

**Python**

```python
from emailit import EmailitClient
client = EmailitClient("your_api_key")

client.suppressions.delete("sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e")
```

**PHP**

```php
$emailit = Emailit::client('your_api_key');

$emailit->suppressions()->delete('sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e');
```

**Ruby**

```ruby
require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

client.suppressions.delete("sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e")
```

**Go**

```go
import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

err := client.Suppressions.Delete("sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e")
```

**Rust**

```rust
use emailit::Emailit;
let emailit = Emailit::new("your_api_key");

emailit.suppressions.delete("sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e").await?;
```

**Java**

```java
import com.emailit.*;
import com.emailit.params.*;
EmailitClient emailit = new EmailitClient("your_api_key");

emailit.suppressions().delete("sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e");
```

**.NET**

```csharp
using Emailit;
var emailit = new EmailitClient("your_api_key");

emailit.Suppressions.Delete("sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e");
```

**Laravel**

```php
use Emailit\Laravel\Facades\Emailit;

Emailit::suppressions()->delete('sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e');
```

**cURL**

```bash
curl -X DELETE https://api.emailit.com/v2/suppressions/sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e \
  -H "Authorization: Bearer your_api_key"
```

**200**

```json
{
  "object": "suppression",
  "id": "sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e",
  "email": "ada@example.com",
  "deleted": true
}
```

**400**

```json
{
  "error": "Invalid identifier. Must be a suppression ID (sup_xxx) or valid email address."
}
```

**404**

```json
{
  "error": "Suppression not found"
}
```

---
Fonte: https://emailit.com/pt/docs/api-reference/suppressions/delete/