Listar quejas de correo

GET/v1/mail-complaints

Para desarrolladores

Descripción

Devuelve las quejas que los destinatarios presentaron sobre sus correos, paginadas, filtradas por la fecha de la queja y ordenadas por complained_at descendente.

Guía relacionada

• Seguimiento de correo y desuscripciones — Revise en el detalle de un correo si el destinatario envió una queja y con qué motivo.

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.

complained_atstring (date-time) | null

Fecha y hora de la queja.

typestring | null

Qué reportó el destinatario, ver vocabulario.

commentstring | null

Comentario asociado a la queja, si aplica.

sent_atstring (date-time) | null

Fecha y hora de entrega del correo original.

Vocabulario de type

Es la categoría que el destinatario elige en el formulario de queja.

Valor	Significado
unknown	El destinatario no eligió una categoría.
adult_content	Contenido sexualmente explícito o para adultos.
violent_or_illegal	Contenido violento, ilegal u ofensivo.
spam	Correo no deseado.
phishing_or_malware	Suplantación de identidad, malware o virus.
fraud	Información engañosa o fraudulenta.
intellectual_property	Infracción de propiedad intelectual.
other	Otra categoría, elegida por el destinatario.

Notas

• El vocabulario de type es abierto. Pueden aparecer valores nuevos sin aviso previo, y eso no requiere ajustes en las integraciones existentes.
• Una queja no restringe la dirección por sí sola. No genera una fila 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-complaints?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]",
    "complained_at": "2026-05-10T09:00:00Z",
    "type": "spam",
    "comment": null,
    "sent_at": "2026-05-08T14:22:33Z"
  }
],
"pagination": {
  "page": 1,
  "page_size": 20,
  "has_more": false,
  "total_items": 1,
  "total_pages": 1
}
}