Listar restricciones de envío

GET/v1/mail-restrictions

Para desarrolladores

Descripción

Devuelve una lista paginada de restricciones de envío: las direcciones que la plataforma no vuelve a contactar. 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.

Solo lectura: la API pública no expone alta ni baja de restricciones.

Guía relacionada

• Seguimiento de correo y 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.

scopestring | null

Siempre null.

restricted_atstring (date-time) | null

Fecha y hora en que se aplicó la restricción.

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.

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 al resuscribirse	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"). Al resuscribirse se levanta la restricción, que pasa a exponer deleted_at, y el evento original no se toca.

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, y eso no requiere ajustes en las integraciones existentes.
• 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",
    "deleted_at": null
  }
],
"pagination": {
  "page": 1,
  "page_size": 20,
  "has_more": false,
  "total_items": 1,
  "total_pages": 1
}
}