Bounces & Complaints: Lectura
Listar feedback
Cada bounce, bloqueo y queja de tu cuenta, del más antiguo al más reciente, para que puedas consultar con un cursor y no perder ninguno.
https://g.sendcorex.com/v1/feedbackcommand: list_feedbackRequiere el scope feedback:read en tu API key.
Guarda next_cursor y envíalo en la siguiente llamada. Siempre vuelve, incluso cuando no hubo nada nuevo, así que tu bucle nunca tiene que tratar una página vacía como caso especial.
Los eventos aparecen unos 10 segundos después de ocurrir. Ese pequeño retraso es lo que garantiza que no se salte nada entre dos consultas.
Argumentos
cursorstringopcionalEl
next_cursorde la llamada anterior. La primera vez, empieza sin él (o consince).p. ej.
"ZjowMDAwMDAwMDgzOjE3NjA2ODMxMjQwMzE6OWI3ZTRjMjE"sincestringopcionalRFC 3339. Desde dónde empezar cuando aún no tienes cursor. Se ignora si se envía
cursor. Sin ninguno de los dos, empiezas al inicio de los 90 días.p. ej.
"2026-10-01T00:00:00Z"kindsstring[]opcionalSolo estos tipos:
bounce_hard,bounce_soft,blocked,complaint,dropped. También funciona una cadena separada por comas. Sin él, obtienes todos.p. ej.
["bounce_hard", "complaint"]limitnumberopcionalEventos por llamada, de 1 a 1000. Por defecto, 100.
p. ej.
100
Inicio rápido
import axios from 'axios';
const response = await axios.post(
'https://g.sendcorex.com/v1/feedback',
{
commands: [
{
command: "list_feedback",
args: {
cursor: "ZjowMDAwMDAwMDgzOjE3NjA2ODMxMjQwMzE6OWI3ZTRjMjE",
kinds: [
"bounce_hard",
"complaint"
],
limit: 100
}
}
]
},
{ headers: { Authorization: process.env.SENDCOREX_API_KEY } },
);
const [result] = response.data.results;
if (result.type !== 'SUCCESS') throw new Error(`${result.code}: ${result.message}`);
console.log(result.data);Respuesta
{
"type": "SUCCESS",
"results": [
{
"command": "list_feedback",
"id": "0",
"type": "SUCCESS",
"took_ms": 18,
"data": {
"events": [
{
"email_id": "9b7e4c21-0d3a-4e8f-a6b1-5c2d7e9f1a30",
"kind": "bounce_hard",
"source": "smtp",
"recipient": "old.address@gmail.com",
"from": "noreply@yourdomain.com",
"smtp_code": 550,
"enhanced_code": "5.1.1",
"diagnostic": "550-5.1.1 The email account that you tried to reach does not exist.",
"at": "2026-10-17T05:58:44.031Z"
},
{
"email_id": "3f2a1b4c-8e9d-4f7a-b2c3-1a2b3c4d5e6f",
"kind": "complaint",
"source": "fbl_microsoft",
"recipient": "ana@outlook.com",
"from": "news@yourdomain.com",
"campaign_id": "c1d2e3f4-0a1b-4c2d-8e3f-4a5b6c7d8e9f",
"reporting_mta": "staff@hotmail.com",
"at": "2026-10-17T09:12:03.500Z"
},
{
"email_id": "5a6b7c8d-1e2f-4a3b-9c4d-5e6f7a8b9c0d",
"kind": "blocked",
"source": "smtp",
"recipient": "paulo@corp-example.com",
"from": "noreply@yourdomain.com",
"smtp_code": 554,
"enhanced_code": "5.7.1",
"diagnostic": "554 5.7.1 Service unavailable; client host blocked using zen.spamhaus.org",
"at": "2026-10-17T10:40:19.002Z"
}
],
"next_cursor": "ZjowMDAwMDAwMDgzOjE3NjA2ODMxMjQwMzE6OWI3ZTRjMjE",
"has_more": false
}
}
]
}Campos de la respuesta
eventsLos eventos de esta llamada, del más antiguo al más reciente. Cada uno tiene los campos de abajo.
next_cursorEnvíalo como
cursoren la siguiente llamada. Cuando no llegó nada nuevo, es el mismo cursor que enviaste.has_moretruecuando ya hay más eventos esperando: vuelve a llamar enseguida en lugar de esperar a tu siguiente consulta.events[].email_idEl ID del email (un UUID): el
idque recibiste al enviarlo, y el mismo id que en Logs y en los webhooks.events[].kindQué pasó:
bounce_hard,bounce_soft,blocked,complaintodropped. Consulta Tipos más abajo.events[].sourceDe dónde lo supimos: la respuesta SMTP, un mensaje de bounce, un feedback loop, un reporte de abuso… Consulta Orígenes más abajo.
events[].recipientLa dirección a la que se envió el email.
events[].fromLa dirección del remitente.
events[].campaign_idLa campaña, cuando el email pertenece a una.
events[].smtp_code / events[].enhanced_codeEl código que respondió el servidor de destino, por ejemplo
550y5.1.1. Solo en bounces y bloqueos.events[].diagnosticLa respuesta completa del servidor de destino, o el motivo indicado en un reporte de abuso.
events[].reporting_mtaQuién lo reportó: el servidor que envió el mensaje de bounce, la dirección del feedback loop, o
webpara la página de reporte.events[].atCuándo ocurrió. ISO 8601, UTC.
Tipos
bounce_hardLa dirección no existe o ya no acepta correo (5.1.x, la mayoría de los 5xx). Elimínala de tus listas: volver a enviar perjudica tu reputación.
bounce_softUn problema temporal que no se resolvió a tiempo: buzón lleno (5.2.2), un 4xx que agotó los reintentos, o el email expiró en la cola. Puedes intentarlo de nuevo más tarde.
blockedEl servidor de destino rechazó el propio mensaje: filtro de spam, política, blocklist o autenticación (5.7.x). La dirección está bien, así que no la elimines: corrige lo que se envió.
complaintEl destinatario marcó el email como spam (feedback loop) o lo reportó como abuso. Deja de enviar a esta dirección.
droppedSendcorex nunca lo envió: cuenta bloqueada, sin créditos o dirección inválida.
Orígenes
smtpLa respuesta del servidor de destino mientras hacíamos la entrega.
dsnUn mensaje de bounce que llegó más tarde al Return-Path, después de que el servidor aceptara el email al principio.
expiredEl email seguía en la cola después de 5 días y se abandonó.
retries_exhaustedEl servidor de destino lo siguió aplazando y se usaron todos los reintentos.
outgoingDetenido antes del envío (es lo que llevan los eventos
dropped).fbl_microsoft / fbl_yahoo / fbl_otherUn reporte de spam del feedback loop del proveedor (Outlook/Hotmail, Yahoo/AOL, otros).
abuse_mailboxAlguien escribió a la dirección de abuso del header
X-Report-Abusedel email.abuse_webAlguien usó la página de reporte enlazada en el header
X-Report-Abuse.
Polling
Guarda el cursor en algún lugar que sobreviva a un reinicio (una fila en la base de datos, un archivo). En cada ciclo, lee hasta que has_more sea false, procesa cada evento y guarda el nuevo cursor.
Node.js
let cursor = await loadCursor(); // null the first time
async function poll() {
let more = true;
while (more) {
const [result] = await call({
command: 'list_feedback',
args: cursor ? { cursor, limit: 500 } : { since: new Date(Date.now() - 86400_000).toISOString(), limit: 500 },
});
for (const e of result.data.events) {
if (e.kind === 'bounce_hard' || e.kind === 'complaint') await suppress(e.recipient, e.kind); // your code
}
cursor = result.data.next_cursor;
await saveCursor(cursor);
more = result.data.has_more;
}
}
setInterval(poll, 30_000);call es cualquier helper que envía { commands: [...] } por POST a /v1/feedback y devuelve results, como en Run Commands.
Elimina direcciones solo con bounce_hard y complaint. Un evento blocked significa que el servidor rechazó ese mensaje, no que la dirección sea mala.
¿Prefieres push? Los webhooks bounced y fbl_complaint traen los mismos eventos en el momento en que ocurren. El polling es la red de seguridad para cuando tu endpoint estuvo caído.
Filtrar por tipo
Con kinds, el cursor sigue avanzando más allá de los eventos que filtraste, así que un bucle filtrado cuesta lo mismo que uno sin filtrar.
Cuerpo de la solicitud
{
"commands": [
{
"command": "list_feedback",
"args": {
"since": "2026-10-01T00:00:00Z",
"kinds": [
"complaint"
]
}
}
]
}El evento
Evento
{
"email_id": "9b7e4c21-0d3a-4e8f-a6b1-5c2d7e9f1a30",
"kind": "bounce_hard",
"source": "smtp",
"recipient": "old.address@gmail.com",
"from": "noreply@yourdomain.com",
"smtp_code": 550,
"enhanced_code": "5.1.1",
"diagnostic": "550-5.1.1 The email account that you tried to reach does not exist.",
"at": "2026-10-17T05:58:44.031Z"
}Errores
Los errores a nivel HTTP devuelven type, code y message. Los errores marcados con CMD vuelven dentro del resultado del comando, con HTTP 200.
- 401
INVALID_API_KEYLa API key no existe, fue revocada o se desactivó en el dashboard.
- 429
RATE_LIMITEDMás de 15 solicitudes/s o 15 simultáneas para la misma IP + API key. Espera el número de segundos indicado en Retry-After.
- CMD
MISSING_SCOPELa API key no tiene `feedback:read`.
- CMD
INVALID_ARGSUn argumento no es válido: tipo desconocido, `since` que no es RFC 3339, limit fuera de rango, falta `email_id`…
- CMD
INVALID_CURSOREl cursor está mal formado o viene de otra cuenta. Empieza de nuevo sin cursor (o con `since`).
- CMD
INTERNALError del servidor. El detalle solo se escribe en el log del servidor.