# Direcciones bloqueadas API

> Consulta y gestiona las direcciones a las que Emailit no enviará emails.

URL base: `https://api.emailit.com/v2`. Autentícate con `Authorization: Bearer <API key>`.

## Crear un bloqueo — POST /suppressions

> Añade una dirección a la lista de direcciones bloqueadas, de forma permanente o hasta la fecha que elijas, para que Emailit deje de enviarle emails.

# Crear un bloqueo

Añade una dirección a la lista de direcciones bloqueadas de tu espacio de trabajo. Los emails enviados por la API y por SMTP a una dirección con un bloqueo `recipient` reciben el estado `suppressed` en lugar de enviarse, y las campañas omiten las direcciones bloqueadas. Requiere una clave de API con el permiso `full`.

`POST /suppressions`

## Cuerpo de la petición

- `email` (string, obligatorio): La dirección que se bloquea. Emailit la guarda en minúsculas.

- `type` (string): El tipo de bloqueo. Por defecto, `recipient`. Emailit usa `recipient`, `bounce`, `complaint` y `unsubscribe`. Solo los bloqueos `recipient` detienen los emails enviados por la API y por SMTP. Las campañas omiten todas las direcciones con un bloqueo activo de cualquier tipo. Una dirección puede tener un bloqueo de cada tipo.

- `reason` (string): Una nota de texto libre, por ejemplo `manual` o `Asked to stop receiving invoices`.

- `keep_until` (string | number | null): Cuándo caduca el bloqueo. Acepta una marca de tiempo ISO 8601 (`2026-12-31T00:00:00Z`), una marca de tiempo Unix en segundos (`1798675200`) o lenguaje natural, como `in 30 days` o `tomorrow at 9am`. Omítelo o envía `null` para crear un bloqueo permanente. Pasado ese momento, el bloqueo deja de impedir los envíos. Sigue en la lista hasta que lo elimines.

## Devuelve

Devuelve `201 Created` con el objeto de bloqueo. Emailit también envía un evento de webhook [`suppression.created`](/es/docs/webhooks/events/suppression/created/).

| Código | Cuándo |
| --- | --- |
| `400` | `email` no es una dirección válida o `keep_until` no se puede analizar (el cuerpo incluye una cadena `error`), o falta `email` (error de validación estándar). |
| `409` | La dirección ya tiene un bloqueo de este tipo. El cuerpo incluye el bloqueo existente en `existing`. |

**Petición** `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
  }
}
```

---
Fuente: https://emailit.com/es/docs/api-reference/suppressions/create/

## Obtener un bloqueo — GET /suppressions/{id}

> Obtén un bloqueo por su ID o por la dirección de email bloqueada, con su tipo, su motivo y su fecha de caducidad.

# Obtener un bloqueo

Devuelve un bloqueo, buscado por su ID o por la dirección de email. Requiere una clave de API con el permiso `full`.

`GET /suppressions/:id`

## Parámetros de ruta

- `id` (string, obligatorio): El ID del bloqueo (`sup_…`) o la dirección bloqueada. Codifica la dirección para URL, por ejemplo `ada%40example.com`. Una dirección puede tener un bloqueo de cada tipo. Si buscas por dirección, Emailit devuelve uno de ellos; usa el ID para obtener un tipo concreto.

## Devuelve

Devuelve `200 OK` con el objeto de bloqueo. Un bloqueo cuyo `keep_until` ya ha pasado deja de impedir los envíos.

Devuelve `400` si `id` no es un ID `sup_` ni una dirección de email válida, y `404` si ningún bloqueo coincide.

**Petición** `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"
}
```

---
Fuente: https://emailit.com/es/docs/api-reference/suppressions/get/

## Actualizar un bloqueo — POST /suppressions/{id}

> Cambia la dirección, el tipo, el motivo o la caducidad de un bloqueo, buscado por su ID o por la dirección bloqueada.

# Actualizar un bloqueo

Actualiza un bloqueo. Envía solo los campos que quieras cambiar; tienes que enviar al menos uno. Requiere una clave de API con el permiso `full`.

`POST /suppressions/:id`

## Parámetros de ruta

- `id` (string, obligatorio): El ID del bloqueo (`sup_…`) o la dirección bloqueada, codificada para URL (`ada%40example.com`). Si una dirección tiene bloqueos de varios tipos, usa el ID.

## Cuerpo de la petición

- `email` (string): La nueva dirección. Se guarda en minúsculas.

- `type` (string): El nuevo tipo: `recipient`, `bounce`, `complaint` o `unsubscribe`. Solo los bloqueos `recipient` detienen los envíos por la API y por SMTP.

- `reason` (string): El nuevo motivo, en texto libre.

- `keep_until` (string | number | null): La nueva fecha de caducidad, en los mismos formatos que al [crear](/es/docs/api-reference/suppressions/create/) el bloqueo: ISO 8601, una marca de tiempo Unix en segundos o lenguaje natural, como `in 30 days`. Envía `null` para que el bloqueo sea permanente.

## Devuelve

Devuelve `200 OK` con el bloqueo actualizado. Emailit también envía un evento de webhook [`suppression.updated`](/es/docs/webhooks/events/suppression/updated/).

| Código | Cuándo |
| --- | --- |
| `400` | El cuerpo no incluye ninguno de los campos anteriores, `email` no es válido o `keep_until` no se puede analizar. |
| `404` | Ningún bloqueo coincide con `id`. |
| `409` | Ya existe otro bloqueo para la nueva dirección y el nuevo tipo. |

**Petición** `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"
}
```

---
Fuente: https://emailit.com/es/docs/api-reference/suppressions/update/

## Listar direcciones bloqueadas — GET /suppressions

> Obtén las direcciones bloqueadas de tu espacio de trabajo con búsqueda, filtros, ordenación y paginación por páginas.

# Listar direcciones bloqueadas

Devuelve los bloqueos de tu espacio de trabajo, del más reciente al más antiguo. El listado incluye los bloqueos que Emailit añade automáticamente tras rebotes y quejas, y los bloqueos caducados cuyo `keep_until` ya ha pasado. Requiere una clave de API con el permiso `full`.

`GET /suppressions`

## Parámetros de consulta

- `page` (integer): El número de página, empezando por `1`. Por defecto, `1`.

- `limit` (integer): Bloqueos por página, de `1` a `100`. Por defecto, `10`.

- `search` (string): Búsqueda en la dirección o en el motivo, sin distinguir mayúsculas y minúsculas. `q` funciona como alias.

- `match` (string): `all` (por defecto) exige que coincidan todos los filtros `key.condition`. `or` exige que coincida cualquiera de ellos. Consulta [Filtrado](/es/docs/api-reference/filtering/).

- `sort` (string): La clave de ordenación: `email`, `reason`, `type` o `created_at` (por defecto).

- `order` (string): La dirección de la ordenación: `asc` o `desc` (por defecto).

## Filtros

Claves de filtro y de ordenación: consulta [Filtrado](https://emailit.com/es/docs/api-reference/filtering/).

En este endpoint, `order` solo acepta `asc` o `desc`. Pasa la clave de ordenación en `sort`, por ejemplo `sort=email&order=asc`.

## Devuelve

Devuelve `200 OK` con los bloqueos en `data`, además de `next_page_url` y `previous_page_url` (`null` si no hay página siguiente o anterior). Las URL de las páginas conservan tu búsqueda, tus filtros y tu orden.

**Petición** `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"
}
```

---
Fuente: https://emailit.com/es/docs/api-reference/suppressions/list/

## Eliminar un bloqueo — DELETE /suppressions/{id}

> Elimina un bloqueo por su ID o por la dirección bloqueada para que Emailit pueda volver a enviar a esa dirección.

# Eliminar un bloqueo

Elimina un bloqueo para que la dirección pueda volver a recibir emails. Requiere una clave de API con el permiso `full`.

`DELETE /suppressions/:id`

## Parámetros de ruta

- `id` (string, obligatorio): El ID del bloqueo (`sup_…`) o la dirección bloqueada, codificada para URL (`ada%40example.com`). Una petición por dirección elimina un solo bloqueo. Si la dirección tiene bloqueos de varios tipos, elimínalos uno a uno por su ID o repite la petición hasta que devuelva `404`.

## Devuelve

Devuelve `200 OK` con el `id` y el `email` del bloqueo eliminado y `deleted: true`. Emailit también envía un evento de webhook [`suppression.deleted`](/es/docs/webhooks/events/suppression/deleted/).

Devuelve `400` si `id` no es un ID `sup_` ni una dirección de email válida, y `404` si ningún bloqueo coincide.

**Petición** `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"
}
```

---
Fuente: https://emailit.com/es/docs/api-reference/suppressions/delete/