Saltar al contenido principal

Listar quejas de correo

GET/v1/mail-complaints

Descripción​

Lista paginada de reportes de queja (spam), filtrada por la fecha de la queja.

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.
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 mail original.

Vocabulario de type​

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

ValorSignificado
unknownEl proveedor no informó una categoría.
adult_contentContenido sexualmente explícito o para adultos.
violent_or_illegalContenido violento, ilegal u ofensivo.
spamCorreo no deseado.
phishing_or_malwareSuplantación de identidad, malware o virus.
fraudInformación engañosa o fraudulenta.
intellectual_propertyInfracción de propiedad intelectual.
otherOtra categoría informada por el proveedor.
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.
  • Una queja no suprime la dirección por sí sola. No genera una fila en mail-restrictions, salvo que el destinatario marque además la baja en el mismo formulario, en cuyo caso sí queda restringido.
  • Los resultados se ordenan por complained_at descendente.
  • 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-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": "alice@example.com",
    "sender": "newsletter@example.com",
    "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
}
}