Supresiones

Tu espacio de trabajo tiene una lista de supresión: un conjunto de direcciones de correo electrónico a las que no entregamos mensajes. Los rebotes duros y las quejas de spam se añaden automáticamente, y tú también puedes agregar direcciones. Enviar repetidamente a direcciones que rebotan o reportan spam puede hacer que los proveedores de buzón bloqueen tu dominio, así que detenemos esos envíos antes de que salgan de la plataforma.

Una cancelación de suscripción no está en esta lista. Registra la preferencia declarada del destinatario en lugar de un dato de entregabilidad, así que aparece en la pestaña Preferences en su lugar. Consulta Enlaces de cancelación de suscripción para saber cómo funciona.

Gestiona la lista en Email > Suppressions, a través de la API de supresiones API, o con bird email suppressions.

La página Suppressions en el dashboard, con direcciones suprimidas junto a su motivo, origen y fecha de creación, y un botón Create suppression

Los tres motivos y qué bloquean

Cada registro tiene un reason que indica por qué la dirección está en la lista, y una política applies_to que controla qué categorías bloquea:

Motivo	applies_to	Categoría marketing	Categoría transaccional
hard_bounce	all	Bloqueada	Bloqueada
complaint	non_transactional	Bloqueada	Permitida
manual	all	Bloqueada	Bloqueada

La división se explica por lo que significa cada motivo:

hard_bounce: la dirección no existe. Enviar es inútil en cualquier categoría, así que bloquea todo.
complaint: una declaración sobre correo no deseado. Alguien que reportó tu newsletter como spam puede seguir necesitando un restablecimiento de contraseña o una confirmación de pedido, así que solo bloquea los envíos no transaccionales.
manual: una decisión deliberada tuya o de tu equipo. No la cuestionamos, así que una supresión manual bloquea todas las categorías, incluida la transaccional.

Una dirección puede tener un registro por motivo, así que un rebote duro y una queja anterior aparecen uno junto al otro como registros separados, y la entrega permanece bloqueada mientras quede algún registro de bloqueo. Aplicamos el principio de fallo cerrado ante cualquier valor que no reconozcamos: si un registro incluye un applies_to que tu integración nunca ha visto, trátalo como si bloqueara todas las categorías, que es como lo tratamos nosotros.

Note: reason: unsubscribe is deprecated on the suppressions API. Unsubscribes now record a preference instead of a suppression, so ?reason=unsubscribe matches nothing.

Cómo se añaden direcciones automáticamente

Añadimos supresiones en respuesta a señales del destinatario, así que un rebote o una queja no requiere ninguna acción de tu parte:

Desencadenante	Supresión resultante
Rebote duro (email.bounced)	reason: hard_bounce, origin: bounce_event, applies_to: all
Rebote duro fuera de banda (email.out_of_band_bounce)	reason: hard_bounce, origin: bounce_event, applies_to: all
Queja de spam (email.complained)	reason: complaint, origin: complaint_event, applies_to: non_transactional

Una cancelación de suscripción, ya sea a través del enlace en el cuerpo del mensaje o el botón de un clic, no aparece aquí: registra una preferencia en la pestaña Preferences en lugar de añadir una fila a esta lista.

Solo un rebote de clase hard genera supresión, y la tabla de clasificación muestra qué valores de bounce_class cuentan como duros. Dos resultados que parecen fallos dejan la dirección disponible para envío:

Rebotes suaves y aplazamientos (email.deferred, o email.bounced con bounce_type: "soft"): fallos transitorios como un buzón lleno. Reintentamos.
Rechazos del lado del envío: fallos de generación y rechazos de política son problemas con el envío, no con la dirección. Producen eventos email.rejected y ninguna supresión.

Las señales repetidas para una dirección que ya está suprimida por el mismo motivo no modifican el registro original, incluido su created_at. El registro conserva source_email_id y source_recipient_id, que vinculan una supresión automática con el mensaje y el destinatario exactos que la causaron. Esos dos campos responden a la pregunta de soporte "why did this person stop getting our email", y son null en las adiciones manuales.

Cada adición, automática o manual, dispara un evento email_suppression.created a tu endpoint de webhook con el suppression_id, la dirección suprimida email, el reason y el workspace_id, para que tu sistema pueda replicar la lista sin sondeo:

Ejemplo de código

{
  "type": "email_suppression.created",
  "timestamp": "2026-07-23T14:52:03.192524705Z",
  "data": {
    "email": "user@example.com",
    "reason": "manual",
    "suppression_id": "sup_01ky7qckqrf06r38g49b9kxdbc",
    "workspace_id": "ws_01ky7m21hjffh9s8kq76gyb1xf"
  }
}

Gestionar supresiones a través de la API

La API permite añadir, listar, consultar y eliminar registros individuales. Las direcciones se convierten a minúsculas antes de almacenarse y consultarse, y nunca aparecen en la ruta de la URL, porque la ruta queda en los logs de acceso y una dirección de correo es un dato personal. Para encontrar el registro de una dirección, filtra la lista con ?email=.

Los ejemplos de SDK acceden a las supresiones a través del método de solicitud directa de cada cliente, que lleva la misma autenticación, reintentos y manejo de URL base que una llamada tipada. La forma de la respuesta es la que tú declares.

Añadir una dirección

type Suppression = { id: string; email: string; reason: string };

const suppression = await bird.request<Suppression>({
  method: "POST",
  path: "/v1/email/suppressions",
  body: { email: "user@example.com" },
});

client.post("/v1/email/suppressions", body={"email": "user@example.com"})

var suppression struct {
	Id     string `json:"id"`
	Email  string `json:"email"`
	Reason string `json:"reason"`
}
if err := client.Post(context.Background(), "/v1/email/suppressions", map[string]any{
	"email": "user@example.com",
}, &suppression); err != nil {
	log.Fatal(err)
}

$suppression = $bird->post('/v1/email/suppressions', body: [
    'email' => 'user@example.com',
]);

curl -X POST https://us1.platform.bird.com/v1/email/suppressions \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "user@example.com" }'

En la CLI, bird email suppressions cubre list y remove; añadir una dirección se hace a través de API.

Las adiciones manuales obtienen reason: manual y applies_to: all, así que bloquean todas las categorías. La llamada es idempotente: una supresión nueva devuelve 201 Created, y una dirección que ya estaba suprimida manualmente devuelve 200 OK con el registro existente en lugar de un conflicto. En ambos casos el cuerpo es el objeto de supresión:

Ejemplo de código

{
  "applies_to": "all",
  "created_at": "2026-07-23T14:52:03.192524705Z",
  "email": "user@example.com",
  "id": "sup_01ky7qckqrf06r38g49b9kxdbc",
  "origin": "api_key",
  "reason": "manual",
  "scope": {
    "id": "ws_01ky7m21hjffh9s8kq76gyb1xf",
    "type": "workspace"
  }
}

El campo origin registra cómo se creó el registro. Las adiciones manuales obtienen api_key o user, dependiendo de si el llamante se autenticó con una clave API o una sesión del dashboard. Las adiciones automáticas obtienen bounce_event o complaint_event, dependiendo de qué señal las creó.

Listar y consultar

type Suppressions = { data: Array<{ id: string; email: string; reason: string }> };

const suppressions = await bird.request<Suppressions>({
  method: "GET",
  path: "/v1/email/suppressions?limit=25",
});
console.log(suppressions.data.length);

suppressions = client.get("/v1/email/suppressions?limit=25")
print(len(suppressions["data"]))

var out struct {
	Data []struct {
		Email  string `json:"email"`
		Reason string `json:"reason"`
	} `json:"data"`
}
if err := client.Get(context.Background(), "/v1/email/suppressions?limit=25", &out); err != nil {
	log.Fatal(err)
}
fmt.Println(len(out.Data))

$suppressions = $bird->get('/v1/email/suppressions', query: ['limit' => 25]);

bird email suppressions list --limit 25

curl "https://us1.platform.bird.com/v1/email/suppressions?limit=25" \
  -H "Authorization: Bearer $BIRD_API_KEY"

La lista usa paginación por cursor, de más reciente a más antiguo, y se puede filtrar por reason. Para comprobar una dirección, pásala como el parámetro de consulta email:

const suppressions = await bird.request({
  method: "GET",
  path: "/v1/email/suppressions?email=user@example.com",
});
console.log(suppressions.data.length);

suppressions = client.get("/v1/email/suppressions?email=user@example.com")
print(len(suppressions["data"]))

var out struct {
	Data []struct {
		Email  string `json:"email"`
		Reason string `json:"reason"`
	} `json:"data"`
}
if err := client.Get(context.Background(), "/v1/email/suppressions?email=user@example.com", &out); err != nil {
	log.Fatal(err)
}
fmt.Println(len(out.Data))

$suppressions = $bird->get('/v1/email/suppressions', query: ['email' => 'user@example.com']);

bird email suppressions list --email user@example.com

curl "https://us1.platform.bird.com/v1/email/suppressions?email=user@example.com" \
  -H "Authorization: Bearer $BIRD_API_KEY"

Un array data vacío significa que la dirección no está suprimida, y se devuelven varios registros cuando aplica más de un motivo. El filtro email busca por prefijo sin distinguir mayúsculas de minúsculas, así que una dirección completa devuelve los registros de esa dirección y un fragmento como alice devuelve todas las direcciones suprimidas que empiecen por él.

Eliminar una dirección

await bird.request({
  method: "DELETE",
  path: "/v1/email/suppressions/sup_01ky7qckqrf06r38g49b9kxdbc",
});

client.delete("/v1/email/suppressions/sup_01ky7qckqrf06r38g49b9kxdbc")

if err := client.Delete(context.Background(), "/v1/email/suppressions/sup_01ky7qckqrf06r38g49b9kxdbc", nil); err != nil {
	log.Fatal(err)
}

$bird->delete('/v1/email/suppressions/sup_01ky7qckqrf06r38g49b9kxdbc');

bird email suppressions remove sup_01ky7qckqrf06r38g49b9kxdbc --yes

curl -X DELETE https://us1.platform.bird.com/v1/email/suppressions/sup_01ky7qckqrf06r38g49b9kxdbc \
  -H "Authorization: Bearer $BIRD_API_KEY"

Devuelve 204 No Content. La eliminación es permanente: no conservamos nada y la dirección vuelve a ser válida para envío. Eliminar por dirección requiere dos llamadas, una consulta ?email= para obtener el ID y luego la eliminación; una dirección suprimida por varios motivos necesita que se elimine cada registro de bloqueo. Ten cuidado al eliminar un registro hard_bounce, porque una dirección que sigue sin existir rebotará en el próximo envío y se volverá a suprimir.

Qué ocurre cuando envías a una dirección suprimida

Rechazamos al destinatario donde puedes verlo. El destinatario recibe un recipient_id y aparece en la lista de destinatarios del mensaje con el estado rejected. Los eventos API y tus webhooks registran un evento email.rejected con rejection_reason: "recipient_suppressed". El resto de los destinatarios se entregan con normalidad.

El mensaje en sí se acepta con un 202, incluso cuando todos sus destinatarios están suprimidos. Resolvemos la supresión después de aceptar el envío, mientras procesamos el mensaje, así que una dirección que añadas ahora se aplica en unos minutos y nunca detiene un envío que ya esté en curso.

Pruebas con el sandbox

El sandbox de pruebas ejercita el manejo de supresiones de forma determinista. Enviar a suppressed@messagebird.dev se comporta como si la dirección estuviera en tu lista: el destinatario se rechaza con rejection_reason: "recipient_suppressed" y nunca llega a la entrega. Las direcciones de rebote y queja del sandbox (bounce@messagebird.dev, complaint@messagebird.dev) ejecutan sus resultados a través del pipeline real de eventos sin escribir nada en tu lista de supresión, así que las mismas direcciones de prueba siguen siendo reutilizables entre ejecuciones.

Próximos pasos

Categorías: transactional frente a marketing, y cómo la categoría interactúa con la política de supresión
Enlaces de cancelación de suscripción: cómo las cancelaciones registran una preferencia declarada en lugar de una supresión
Eventos y webhooks: el payload de email.rejected y los eventos del ciclo de vida que generan supresiones automáticas
Sandbox de pruebas: direcciones mágicas para simular cada resultado de entrega
Referencia de API: Suppressions: esquemas completos de solicitud y respuesta
Qué ocurre cuando alguien cancela su suscripción: un vídeo que sigue a un destinatario desde la página de cancelación de suscripción hasta un envío rechazado

Recursos relacionados

Continúa con la documentación, guías y ejemplos sobre este tema. Los recursos están en inglés.

Comprender el conceptoWhat is one-click unsubscribe, and how do I implement List-Unsubscribe?Explorar la funcionalidadEmail opt-outs Seguir la ruta de aprendizajeOperate messaging reliably

Obtener un resumen de implementación