Listar desuscripciones

GET/v1/mail-unsubscribes

Para desarrolladores

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á restringida ahora, consulte GET /v1/mail-restrictions: devuelve el estado actual y no está acotado por la retención.

Guía relacionada

• Seguimiento de correo y desuscripciones — Consulte las bajas de su cuenta y el motivo que indicó cada destinatario.

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:

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

Número de página; la primera es la 1. 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 el message_id que devuelve POST /v1/mails/send.

sender_idinteger | null

Filtra por id del remitente.

recipientstring | null

Filtra por el email del destinatario, con coincidencia parcial y sin distinguir 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_idstringsiempre presente

Identificador del correo.

msg_idstring | null

Identificador del mensaje. Lo comparten todos los destinatarios de una misma llamada a POST /v1/mails/send.

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 correo 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 inicia el cliente de correo del destinatario, no una persona.

Notas

• El vocabulario de type es abierto. Pueden aparecer valores nuevos sin aviso previo, y eso no requiere ajustes en las integraciones existentes.
• 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 que el destinatario envía con el formulario de queja es otra cosa y se consulta en GET /v1/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 GET /v1/mail-restrictions.
• 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 sobre una dirección puntual, compare la dirección devuelta: que haya resultados no basta.
• Una dirección con + debe ir codificada como %2B (?recipient=usuario%[email protected]); de lo contrario la búsqueda no devuelve resultados. 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": "[email protected]",
    "sender": "[email protected]",
    "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
}
}