Listar restricciones de envío

GET/v1/mail-restrictions

Para desarrolladores

Descripción

Devuelve una lista paginada de restricciones de envío: las direcciones a las que la plataforma no envía ningún correo, o no envía los de un tipo (ver Alcance de una restricción). Ordenada por restricted_at descendente.

Esta es la lista completa de direcciones restringidas, indexada por dirección de correo: no está acotada por la ventana de retención, así que una restricción de hace un año sigue siendo consultable. Para responder "¿esta dirección está restringida?", este es el endpoint. La diferencia con GET /v1/mail-unsubscribes se explica en Estado y evento.

Una oposición o un bloqueo temporal se registran desde la Ficha de contacto del panel o con POST /v1/mail-restrictions. Ninguna restricción se levanta por la API.

Guía relacionada

Consultar las desuscripciones — Consulte las desuscripciones, que restringen la dirección que se da de baja.

Autenticación

Authorizationbearer tokenheaderobligatorio: API key con scope mail:read. Formato: Bearer <API_KEY>.
X-Instance-Slugstringheaderobligatorio: Identificador de su instancia. Ver Autenticación.

Request

Query params:

pageinteger: Número de página; la primera es la 1. Default: 1.
page_sizeinteger: Tamaño de página, 1–100. Default: 20.
recipientstring | null: Filtra por el email del destinatario, con coincidencia parcial y sin distinguir mayúsculas (ver Filtros de texto).
reasonstring | null: Filtra por motivo (ver vocabulario). Un valor fuera del vocabulario devuelve 422.
activeboolean | null: true: solo restricciones vigentes. false: solo restricciones levantadas. Si se omite, devuelve todas.

Response

200 OKDevuelve una página de resultados: data con los elementos y pagination para pedir la siguiente. Cada elemento tiene los campos que siguen.

idintegersiempre presente: Identificador de la restricción.
recipientstringsiempre presente: Email del destinatario restringido.
reasonstring | null: Motivo, ver vocabulario.
scopearray de string | null: Qué envíos bloquea la restricción: masivo, transaccional o ambos. null bloquea todo envío. Ver Alcance de una restricción.
restricted_atstring (date-time) | null: Fecha y hora en que se aplicó la restricción.
expires_atstring (date-time) | null: Fin previsto de un bloqueo temporal (reason: block). Al pasar esa fecha, la restricción se levanta automáticamente y pasa a exponer deleted_at. null en cualquier otro motivo, y en un bloqueo sin fecha de término.
deleted_atstring (date-time) | null: Fecha y hora en que se levantó la restricción. null si sigue vigente.

Errores

Código	Cuándo
403	La API key no tiene el scope `mail:read`, o la IP del cliente no está en la lista permitida.
422	`reason` fuera del vocabulario (`validation_error`; el detalle por campo viene en `errors[]` con `code: "enum"`, ver errores por campo).

Vocabulario de reason

Valor	Significado
`unspecified`	Sin motivo registrado. Parte del vocabulario; hoy no se emite.
`unsubscribe`	El destinatario se desuscribió.
`soft_bounce`	Acumuló rebotes transitorios hasta cruzar el umbral configurado.
`hard_bounce`	Rebote permanente: la dirección no existe o rechaza de forma definitiva.
`objection`	El contacto se opuso a recibir correos. La oposición se registra desde su ficha en el panel o con `POST /v1/mail-restrictions`. Bloquea los envíos que indica `scope`. No la levanta el enlace para volver a suscribirse.
`block`	Bloqueo temporal de todos los envíos mientras se resuelve una solicitud del contacto. Se registra desde el panel o por la API, y se levanta desde el panel o al llegar `expires_at`.

Alcance de una restricción

scope dice a qué envíos alcanza la restricción:

["masivo"] — bloquea los envíos de remitentes masivos; los transaccionales siguen saliendo.
["transaccional"] — bloquea los envíos de remitentes transaccionales; los masivos siguen saliendo.
["masivo", "transaccional"] o null — bloquea todo envío a la dirección.

Un envío a una dirección restringida para su tipo no sale, y en la actividad de envíos queda descartado.

Estado y evento

Son dos cosas distintas y se consultan por endpoints distintos:

	`GET /v1/mail-restrictions`	`GET /v1/mail-unsubscribes`
Qué es	El estado de restricción de una dirección	El log de eventos de desuscripción
Indexado por	Dirección de correo	Correo (`mail_id`): una fila por correo, no por evento
Mutable	Sí: se levanta cuando el destinatario vuelve a suscribirse, o al levantar o vencer un bloqueo temporal	Solo se le agregan datos: se conserva la primera desuscripción del correo y se completan el motivo o el comentario si llegan después
Ventana	Completa, sin corte de retención	Acotada por la retención del correo asociado

Una desuscripción genera las dos cosas: la fila del evento y la restricción correspondiente (reason: "unsubscribe"). Si el destinatario vuelve a suscribirse, esa restricción se levanta y pasa a exponer deleted_at. El evento original no se toca. Una oposición (reason: "objection") no se levanta al volver a suscribirse.

Consecuencia práctica: para saber si una dirección está restringida, consulte este endpoint, no el de desuscripciones. Una queja (GET /v1/mail-complaints), en cambio, no genera restricción por sí sola.

Notas

El vocabulario de reason es abierto. Pueden aparecer valores nuevos sin aviso previo. Una integración que acepta valores que no conoce sigue funcionando sin ajustes.
El filtro recipient es de coincidencia parcial, así que sirve para consultar por dominio ([email protected] lista todo lo de ese dominio). La contrapartida: consultar por [email protected] también devuelve a [email protected]. Por eso, para decidir si una dirección puntual está restringida, compare la dirección devuelta: que haya resultados no basta.
Una dirección con + debe ir codificada como %2B. Si no, la respuesta es un 200 con lista vacía, que se lee como si la dirección no estuviera restringida. Correcto: ?recipient=usuario%[email protected]. Ver Filtros de texto.

Request

curl -X GET "https://$API_HOST/v1/mail-restrictions?active=true&reason=hard_bounce" \
-H "Authorization: Bearer $API_KEY" \
-H "X-Instance-Slug: $SLUG"

Response

{
"data": [
  {
    "id": 5,
    "recipient": "[email protected]",
    "reason": "hard_bounce",
    "scope": null,
    "restricted_at": "2026-05-10T09:00:00Z",
    "expires_at": null,
    "deleted_at": null
  },
  {
    "id": 9,
    "recipient": "[email protected]",
    "reason": "objection",
    "scope": [
      "masivo"
    ],
    "restricted_at": "2026-10-15T14:20:00Z",
    "expires_at": null,
    "deleted_at": null
  }
],
"pagination": {
  "page": 1,
  "page_size": 20,
  "has_more": false,
  "total_items": 2,
  "total_pages": 1
}
}

Descripción​

Guía relacionada​

Autenticación​

Request​

Response​

Errores​

Vocabulario de reason​

Alcance de una restricción​

Estado y evento​

Descripción

Guía relacionada

Autenticación

Request

Response

Errores

Vocabulario de reason

Alcance de una restricción

Estado y evento