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 (?recipient=@acme.com lista todo lo de ese dominio). La contrapartida: consultar por ana@ejemplo.com también devuelve a mariana@ejemplo.com.mx. 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%2Btag@ejemplo.com. 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": "bob@example.com",
    "reason": "hard_bounce",
    "scope": null,
    "restricted_at": "2026-05-10T09:00:00Z",
    "expires_at": null,
    "deleted_at": null
  },
  {
    "id": 9,
    "recipient": "carla@example.com",
    "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
}
}