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 sin una atribución fiable a una Brand se añaden automáticamente, y tú también puedes añadir direcciones. Una queja atribuida a una Brand registra una preferencia para esa Brand. 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.
Las cancelaciones de suscripción y las quejas limitadas a una Brand registran la preferencia declarada del destinatario en la pestaña Preferences. Consulta Enlaces de cancelación de suscripción para ver cómo funciona.
Gestiona la lista en Email > Suppressions, a través de la API de supresiones o con bird email suppressions.

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.
Nota: reason: unsubscribe está obsoleto en la API de supresiones. Las nuevas cancelaciones de suscripción registran una preferencia en lugar de una supresión. El filtro obsoleto ?reason=unsubscribe sigue devolviendo registros de supresión heredados con origin: unsubscribe_link o origin: unsubscribe_event hasta que esos registros se eliminen.
Cómo se añaden direcciones automáticamente
Añadimos supresiones en respuesta a señales del destinatario, así que un rebote duro o una queja sin atribuir no requiere ninguna acción por 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 sin atribución fiable a una Brand (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.
Una queja atribuida de forma fiable añade un estado protegido de baja de marketing a la preferencia de correo de la Brand del mensaje. La preferencia efectiva tiene origin: complaint y status: revoked; coverage puede seguir siendo all cuando una baja independiente ya bloquea todo el tráfico. Bloquea el correo de marketing de esa Brand sin dar de baja al destinatario de otras Brands. Esto también se aplica a un espacio de trabajo con una sola Brand. Las supresiones por rebote duro y las manuales siguen aplicándose a todo el espacio de trabajo, y las supresiones por queja existentes del espacio de trabajo conservan su alcance.
En Email > Suppressions > Preferences, el enlace Spam complaint abre el correo de origen si tienes permiso para leer mensajes. La API de preferencias devuelve su complaint_message_id; el ID se conserva después de eliminar la protección por queja, aunque es posible que el mensaje ya no esté disponible según tu política de retención.
Para registrar un nuevo consentimiento, usa Record opt-in o crea una preferencia individual con status: granted, el mismo brand_id y un consented_at explícito posterior a la queja. Usa source para describir dónde se obtuvo el consentimiento. Las importaciones, las solicitudes masivas y la eliminación no pueden quitar esta protección. Revisa applied y los campos status y coverage de la preferencia devuelta antes de suponer que la entrega puede reanudarse. Un consentimiento posterior a la queja puede ser anterior a una baja independiente, y en ese caso esa baja sigue vigente. Eliminar la queja de una Brand no elimina las supresiones por rebote duro, las manuales ni las supresiones por queja existentes del espacio de trabajo.
Si tu integración replica las bajas, consume los eventos de preferencias además de email_suppression.created. Las quejas limitadas a una Brand no crean un evento de supresión del espacio de trabajo. Las eliminaciones de supresiones no tienen webhook para clientes; para detectarlas, concilia periódicamente la lista de supresión completa recorriendo todas sus páginas. Consulta Eventos de correo electrónico para ver el contrato de eventos y la guía de migración para la conciliación y el manejo de reintentos.
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, oemail.bouncedconbounce_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.rejectedy 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 propio sistema se entere de los nuevos bloqueos:
{
"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=.
Cada SDK expone estas operaciones como métodos tipados en su recurso suppressions.
Añadir una dirección
const suppression = await bird.suppressions.add({ email: "user@example.com" });
console.log(suppression.id);suppression = client.suppressions.add(email="user@example.com")
print(suppression.id)suppression, err := client.Suppressions.Add(context.Background(), bird.SuppressionsAddParams{
Email: "user@example.com",
})
if err != nil {
log.Fatal(err)
}
fmt.Println(suppression.Id)$suppression = $bird->suppressions->add(
(new SuppressionCreate())->setEmail('user@example.com'),
);
echo $suppression->getId();bird email suppressions add --email user@example.comcurl -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" }'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:
{
"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
Estas llamadas devuelven la primera página. En Go, el tercer argumento vacío inicia la paginación; pasa el NextCursor de la página anterior para leer la siguiente.
const page = await bird.suppressions.list({ limit: 25 });
console.log(page.data.length);page = client.suppressions.list(limit=25)
print(len(page.data))page, err := client.Suppressions.ListPage(context.Background(), bird.SuppressionsListParams{Limit: 25}, "")
if err != nil {
log.Fatal(err)
}
fmt.Println(len(page.Data))$page = $bird->suppressions->list(['limit' => 25])->fetch();
echo count($page->data);bird email suppressions list --limit 25curl "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 antigua, y se puede filtrar por reason. Para comprobar una dirección, pásala como parámetro de consulta email:
const page = await bird.suppressions.list({ email: "user@example.com" });
console.log(page.data.length);page = client.suppressions.list(email="user@example.com")
print(len(page.data))page, err := client.Suppressions.ListPage(context.Background(), bird.SuppressionsListParams{
Email: "user@example.com",
}, "")
if err != nil {
log.Fatal(err)
}
fmt.Println(len(page.Data))$page = $bird->suppressions->list(['email' => 'user@example.com'])->fetch();
echo count($page->data);bird email suppressions list --email user@example.comcurl "https://us1.platform.bird.com/v1/email/suppressions?email=user@example.com" \
-H "Authorization: Bearer $BIRD_API_KEY"El filtro email coincide por prefijo sin distinguir mayúsculas de minúsculas: user@example.com también coincide con user@example.com.au. Compara cada dirección devuelta con la dirección completa que solicitaste, y recorre next_cursor en todas las páginas antes de decidir si existe un registro coincidente. Varios registros pueden aplicarse a una misma dirección. Quienes llaman desde MCP pueden usar email_suppressions_check para esta búsqueda por dirección exacta.
Una vez que tienes un ID de supresión, GET /v1/email/suppressions/{suppression_id} devuelve ese único registro: suppressions.get en los SDK, o bird email suppressions get <id> en el CLI.
Eliminar una dirección
await bird.suppressions.remove("sup_01ky7qckqrf06r38g49b9kxdbc");client.suppressions.remove("sup_01ky7qckqrf06r38g49b9kxdbc")if err := client.Suppressions.Remove(context.Background(), "sup_01ky7qckqrf06r38g49b9kxdbc"); err != nil {
log.Fatal(err)
}$bird->suppressions->remove('sup_01ky7qckqrf06r38g49b9kxdbc');bird email suppressions remove sup_01ky7qckqrf06r38g49b9kxdbc --yescurl -X DELETE https://us1.platform.bird.com/v1/email/suppressions/sup_01ky7qckqrf06r38g49b9kxdbc \
-H "Authorization: Bearer $BIRD_API_KEY"Un motivo no se puede eliminar de esta forma. Un registro complaint solo se elimina para un usuario del dashboard con sesión iniciada; una clave API recibe 422 SuppressionNotRemovableByAPIKey. Los registros hard_bounce y manual se pueden eliminar de cualquier forma.
Devuelve 204 No Content y elimina permanentemente ese registro. Los demás registros de la misma dirección se mantienen, y el envío sigue bloqueado mientras algún registro restante bloquee la categoría del mensaje. Para eliminar registros por dirección, pagina la búsqueda ?email=, selecciona solo las coincidencias con la dirección completa y borra cada registro deseado por ID. Piénsalo bien antes de eliminar un registro hard_bounce, porque una dirección que sigue sin existir rebota en el siguiente envío y se vuelve 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 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 sigue aceptando 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 pocos minutos y nunca detiene un envío que ya esté en curso.
Pruebas con el sandbox
El sandbox de pruebas permite probar 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 entregarse. 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, por lo que las mismas direcciones de prueba siguen siendo reutilizables entre ejecuciones.
Próximos pasos
- Categorías:
transactionalfrente amarketing, 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 solicitudes de baja registran una preferencia declarada en lugar de una supresión
- Eventos y webhooks: el payload de
email.rejectedy los eventos del ciclo de vida que generan supresiones automáticas - Sandbox de pruebas: direcciones especiales para simular cada resultado de entrega
- Referencia de API: supresiones: 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 de este tema.