Listar desuscripciones

GET/v1/mail-unsubscribes

Descripción

Lista paginada de desuscripciones, filtrada por la fecha de desuscripción y ordenada por unsubscribed_at descendente.

Es un log de eventos: una fila por correo, que conserva la primera desuscripción y se completa con el motivo o el comentario si llegan después. Para saber si una dirección está suprimida ahora consulta mail-restrictions, que es el estado y no está acotado por la retención.

Autenticación

Authorizationbearer tokenheaderobligatorio

API key con scope mail:read. Formato: Bearer FD.<key_id>.<token>.

X-Instance-Slugstringheaderobligatorio

Request

Query params:

start_datestring (date, `YYYY-MM-DD`) | null

Fecha local de inicio.

end_datestring (date, `YYYY-MM-DD`) | null

Fecha local de fin.

tzstring (zona IANA) | null

Zona para interpretar las fechas. Sin valor: zona de la instancia, o UTC.

pageinteger

Página, 1-indexed. Default: 1.

page_sizeinteger

Tamaño de página, 1–100. Default: 20.

mail_idstring | null

Filtra por mail ID.

msg_idstring | null

Filtra por message ID.

sender_idinteger | null

Filtra por id del remitente.

recipientstring | null

Filtra por email del destinatario - coincidencia parcial, insensible a mayúsculas. Ver Filtros de texto.

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.

mail_idstringobligatorio

Identificador del mail.

msg_idstring | null

Identificador del mensaje lógico.

tostring | null

Email del destinatario.

senderstring | null

Email del remitente.

unsubscribed_atstring (date-time) | null

Fecha y hora de la desuscripción.

typestring | null

Motivo declarado, ver vocabulario.

commentstring | null

Comentario dejado por el destinatario, si aplica.

sent_atstring (date-time) | null

Fecha y hora de entrega del mail original.

Vocabulario de type

Lo elige el destinatario en el formulario de baja, salvo one_click, que no pasa por formulario.

Valor	Significado
unspecified	Se dio de baja sin declarar motivo.
no_longer_interested	Ya no quiere recibir estos correos.
never_subscribed	Declara que nunca se suscribió a la lista.
inappropriate	Considera que el contenido es inapropiado.
spam_report	Declara que el correo es spam y debería reportarse.
other	Otro motivo; suele venir acompañado de comment.
one_click	Baja automática por un clic, sin formulario (RFC 8058). La dispara el cliente de correo del destinatario, no una persona.

Notas

• El vocabulario de type es abierto. Pueden aparecer valores nuevos sin aviso previo; trátalos con un caso por defecto en lugar de un switch exhaustivo. Un valor nuevo no es un cambio incompatible.
• never_subscribed y spam_report son declaraciones del destinatario, no un veredicto de la plataforma: significan lo que la persona eligió en el formulario. Una queja formal ante el proveedor de correo es otra cosa y vive en mail-complaints.
• La ventana consultable está acotada por la retención del correo asociado: una desuscripción cuyo correo ya salió de la ventana deja de aparecer en este endpoint, pero su restricción sigue vigente y visible en mail-restrictions.
• El filtro recipient es de coincidencia parcial, así que sirve para higiene por dominio (?recipient=@acme.com lista todo lo de ese dominio). El reverso: consultar por ana@ejemplo.com también devuelve a mariana@ejemplo.com.mx, así que para decidir sobre una dirección puntual hay que comparar la dirección devuelta, no confiar en que haya resultados.
• Una dirección con + debe ir percent-encodeada como %2B. En una query string el + se decodifica como espacio, así que enviarlo tal cual busca usuario tag@ejemplo.com, no matchea nada y la respuesta es un 200 con lista vacía - falla en silencio. Correcto: ?recipient=usuario%2Btag@ejemplo.com. Ver Filtros de texto.

Request

curl -X GET "https://$API_HOST/v1/mail-unsubscribes?start_date=2026-07-01&end_date=2026-07-31" \
-H "Authorization: Bearer $API_KEY" \
-H "X-Instance-Slug: $SLUG"

Response

{
"data": [
  {
    "mail_id": "0190...",
    "msg_id": "0190...",
    "to": "alice@example.com",
    "sender": "newsletter@example.com",
    "unsubscribed_at": "2026-05-10T09:00:00Z",
    "type": "no_longer_interested",
    "comment": null,
    "sent_at": "2026-05-08T14:22:33Z"
  }
],
"pagination": {
  "page": 1,
  "page_size": 20,
  "has_more": false,
  "total_items": 1,
  "total_pages": 1
}
}