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.

POSThttps://g.sendcorex.com/v1/feedbackcommand: list_feedback
i

Requiere el scope feedback:read en tu API key.

i

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.

i

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

  • cursorstringopcional

    El next_cursor de la llamada anterior. La primera vez, empieza sin él (o con since).

    p. ej. "ZjowMDAwMDAwMDgzOjE3NjA2ODMxMjQwMzE6OWI3ZTRjMjE"

  • sincestringopcional

    RFC 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[]opcional

    Solo 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"]

  • limitnumberopcional

    Eventos 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

  • events

    Los eventos de esta llamada, del más antiguo al más reciente. Cada uno tiene los campos de abajo.

  • next_cursor

    Envíalo como cursor en la siguiente llamada. Cuando no llegó nada nuevo, es el mismo cursor que enviaste.

  • has_more

    true cuando ya hay más eventos esperando: vuelve a llamar enseguida en lugar de esperar a tu siguiente consulta.

  • events[].email_id

    El ID del email (un UUID): el id que recibiste al enviarlo, y el mismo id que en Logs y en los webhooks.

  • events[].kind

    Qué pasó: bounce_hard, bounce_soft, blocked, complaint o dropped. Consulta Tipos más abajo.

  • events[].source

    De 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[].recipient

    La dirección a la que se envió el email.

  • events[].from

    La dirección del remitente.

  • events[].campaign_id

    La campaña, cuando el email pertenece a una.

  • events[].smtp_code / events[].enhanced_code

    El código que respondió el servidor de destino, por ejemplo 550 y 5.1.1. Solo en bounces y bloqueos.

  • events[].diagnostic

    La respuesta completa del servidor de destino, o el motivo indicado en un reporte de abuso.

  • events[].reporting_mta

    Quién lo reportó: el servidor que envió el mensaje de bounce, la dirección del feedback loop, o web para la página de reporte.

  • events[].at

    Cuándo ocurrió. ISO 8601, UTC.

Tipos

  • bounce_hard

    La 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_soft

    Un 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.

  • blocked

    El 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ó.

  • complaint

    El destinatario marcó el email como spam (feedback loop) o lo reportó como abuso. Deja de enviar a esta dirección.

  • dropped

    Sendcorex nunca lo envió: cuenta bloqueada, sin créditos o dirección inválida.

Orígenes

  • smtp

    La respuesta del servidor de destino mientras hacíamos la entrega.

  • dsn

    Un mensaje de bounce que llegó más tarde al Return-Path, después de que el servidor aceptara el email al principio.

  • expired

    El email seguía en la cola después de 5 días y se abandonó.

  • retries_exhausted

    El servidor de destino lo siguió aplazando y se usaron todos los reintentos.

  • outgoing

    Detenido antes del envío (es lo que llevan los eventos dropped).

  • fbl_microsoft / fbl_yahoo / fbl_other

    Un reporte de spam del feedback loop del proveedor (Outlook/Hotmail, Yahoo/AOL, otros).

  • abuse_mailbox

    Alguien escribió a la dirección de abuso del header X-Report-Abuse del email.

  • abuse_web

    Alguien 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);
i

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.

i

¿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.

  • 401INVALID_API_KEY

    La API key no existe, fue revocada o se desactivó en el dashboard.

  • 429RATE_LIMITED

    Má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.

  • CMDMISSING_SCOPE

    La API key no tiene `feedback:read`.

  • CMDINVALID_ARGS

    Un argumento no es válido: tipo desconocido, `since` que no es RFC 3339, limit fuera de rango, falta `email_id`…

  • CMDINVALID_CURSOR

    El cursor está mal formado o viene de otra cuenta. Empieza de nuevo sin cursor (o con `since`).

  • CMDINTERNAL

    Error del servidor. El detalle solo se escribe en el log del servidor.