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 nueva cancelación de suscripción no añade un registro de supresión. Registra la preferencia declarada del destinatario en lugar de un dato de entregabilidad, por lo que aparece en la pestaña Preferences en su lugar. 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 API, 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.
Note: reason: unsubscribe is deprecated on the suppressions API. New unsubscribes record a preference instead of a suppression. The deprecated ?reason=unsubscribe filter still returns legacy suppression records with origin: unsubscribe_link or origin: unsubscribe_event until those records are removed.
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=.
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:
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
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 sin distinguir mayúsculas por prefijo: 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 cada página antes de decidir si existe un registro coincidente. Varias entradas pueden aplicarse a una misma dirección. Los llamadores de 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 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 pocos 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 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 supresiones, por lo 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 solicitudes de baja 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 especiales 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-outsSeguir la ruta de aprendizajeOperate messaging reliably
Obtener un resumen de implementación