Logs: Lectura

Listar logs

Tus logs de entrega, del más reciente al más antiguo, hasta 50 por página. Filtra por estado, destinatario, asunto, dominio, remitente y fecha, en cualquier combinación.

POSThttps://g.sendcorex.com/v1/logscommand: list_logs
i

Requiere el scope logs:read en tu API key.

i

Los filtros se combinan con AND. Sin after, obtienes los últimos 60 días, que es el tiempo que se guardan los logs.

i

Los emails de warm-up nunca aparecen aquí, y el cuerpo del email nunca forma parte de una lista. Usa Get Logs con include_content para leer uno.

Argumentos

  • statusstring | string[]opcional

    delivered, bounced, spam, rate_limited o not_sent, o una lista de ellos. Sin él, obtienes los cinco.

    p. ej. "bounced"

  • recipientstringopcional

    Una dirección de email completa. Se ignoran las mayúsculas y los espacios alrededor.

    p. ej. "ana@acme.com"

  • subjectstringopcional

    Palabras del asunto. Palabras completas, y todas deben estar: order shipped encuentra "Your order #1042 has shipped", ord no. Se ignoran los acentos y las mayúsculas.

    p. ej. "order shipped"

  • searchstringopcional

    Texto libre, para un cuadro de búsqueda. Con una @ es un destinatario; si no, son palabras del asunto.

    p. ej. "ana@acme.com"

  • domainstringopcional

    El dominio del destinatario, exacto.

    p. ej. "gmail.com"

  • fromstringopcional

    La dirección del remitente, exacta.

    p. ej. "noreply@yourdomain.com"

  • afterstring | numberopcional

    Solo logs enviados en este momento o después. ISO 8601, YYYY-MM-DD (medianoche UTC) o epoch en milisegundos. Por defecto, hace 60 días.

    p. ej. "2026-10-01"

  • beforestring | numberopcional

    Solo logs enviados antes de este momento. Mismos formatos.

    p. ej. "2026-10-17T00:00:00Z"

  • limitnumberopcional

    Tamaño de página, de 1 a 50. Por defecto, 50.

    p. ej. 50

  • cursorstringopcional

    El next_cursor de la página anterior. Envíalo con los mismos filtros.

Inicio rápido

import axios from 'axios';

const response = await axios.post(
  'https://g.sendcorex.com/v1/logs',
  {
    commands: [
      {
        command: "list_logs",
        args: {
          status: "bounced",
          after: "2026-10-01",
          limit: 50
        }
      }
    ]
  },
  { 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_logs",
      "id": "0",
      "type": "SUCCESS",
      "took_ms": 18,
      "data": {
        "logs": [
          {
            "id": "9b7e4c21-0d3a-4e8f-a6b1-5c2d7e9f1a30",
            "to": "old.address@gmail.com",
            "from": "noreply@yourdomain.com",
            "domain": "gmail.com",
            "from_domain": "yourdomain.com",
            "subject": "Your order #1042 has shipped",
            "status": "bounced",
            "status_code": 6,
            "response": "550 5.1.1 The email account that you tried to reach does not exist.",
            "message": null,
            "blocked": false,
            "block_reason": null,
            "retries": 0,
            "tracking_id": "7CK-JDL-Z2M-20261017",
            "sent_at": "2026-10-17T05:58:44.031Z",
            "updated_at": "2026-10-17T05:58:45.600Z"
          }
        ],
        "count": 1,
        "has_more": true,
        "next_cursor": "MDAwMDAwMDA4MzowOjgyMzkzMTU5OTg3OTU6M2YyYTFi",
        "partial": false,
        "total": 1240,
        "total_exact": true
      }
    }
  ]
}

Campos de la respuesta

  • logs

    Los logs de esta página, del más reciente al más antiguo. Cada uno tiene los campos de abajo.

  • count

    Cuántos logs hay en esta página.

  • has_more / next_cursor

    Mientras has_more sea true, envía next_cursor como cursor con los mismos filtros.

  • partial

    true cuando la búsqueda alcanzó su límite de tiempo antes de llenar la página. La página puede tener menos logs, incluso cero, y next_cursor continúa desde donde se detuvo.

  • total / total_exact

    Cuántos logs coinciden con los filtros, solo en la primera página (la solicitud sin cursor). En las páginas siguientes ambos son null, así que guarda el primer valor. total solo trae un número cuando es exacto (total_exact: true). Con total: null y total_exact: false hay demasiados para contar; con ambos null la búsqueda no se puede contar (por ejemplo, un asunto sin palabras indexables). En ambos casos, sigue paginando con has_more.

  • logs[].id

    El ID del email (un UUID). Es el id que recibes al enviar y lo que pasas a Get Logs.

  • logs[].to / logs[].domain

    El destinatario y el dominio del destinatario.

  • logs[].from_domain

    El dominio del remitente (la parte después de la @ en from).

  • logs[].from

    La dirección del remitente.

  • logs[].subject

    La línea de asunto.

  • logs[].status

    delivered, bounced, spam, rate_limited o not_sent. status_code es lo mismo como número.

  • logs[].response

    Lo que respondió el servidor de destino, por ejemplo 250 2.0.0 OK o el motivo del bounce 550.

  • logs[].message

    Detalle adicional de Sendcorex sobre la entrega, cuando lo hay.

  • logs[].blocked / logs[].block_reason

    true cuando Sendcorex no envió a este destinatario (suprimido o restringido), y por qué.

  • logs[].retries

    Cuántas veces se reintentó la entrega.

  • logs[].tracking_id

    El id interno de la entrega. Los webhooks de bounce y de queja llevan el mismo valor.

  • logs[].sent_at / logs[].updated_at

    Cuándo se envió el email y cuándo cambió su estado por última vez. ISO 8601, UTC.

Estados

  • delivered

    El servidor de destino aceptó el email.

  • bounced

    El servidor de destino lo rechazó definitivamente: la dirección no existe, el dominio no acepta correo…

  • spam

    El servidor de destino lo rechazó como spam.

  • rate_limited

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

  • not_sent

    No enviado por un motivo de tu cuenta (por ejemplo, sin créditos, cuenta bloqueada o restringida, dominio del remitente en Spamhaus o sin DKIM, o From inválido). No es un rebote. El motivo exacto está en response.

i

Los emails que aún esperan un reintento todavía no están aquí: aparecen cuando llegan a uno de estos cinco estados.

Paginación

Sigue mientras has_more sea true. No te detengas en una página corta o vacía: cuando partial es true, a la búsqueda se le acabó el tiempo en esa llamada, no los logs.

Node.js

const logs = [];
let cursor;

do {
  const [result] = await call({
    command: 'list_logs',
    args: { status: 'bounced', after: '2026-10-01', ...(cursor ? { cursor } : {}) },
  });
  logs.push(...result.data.logs);
  cursor = result.data.has_more ? result.data.next_cursor : null;
} while (cursor);
i

call es cualquier helper que envía { commands: [...] } por POST a /v1/logs y devuelve results, como en Run Commands.

!

Un cursor solo funciona con los filtros de los que vino. Cambia un filtro y obtendrás INVALID_CURSOR: empieza de nuevo sin cursor.

Seguir los nuevos bounces

Para reaccionar a los bounces (o a cualquier otra cosa) en cuanto ocurren, haz polling con after igual al sent_at más reciente que hayas visto. after incluye ese momento, así que el último log vuelve una vez más: omite los ids que ya tienes.

Node.js

const seen = new Set();
let since = new Date(Date.now() - 3600_000).toISOString(); // start with the last hour

setInterval(async () => {
  let cursor;
  do {
    const [result] = await call({
      command: 'list_logs',
      args: { status: 'bounced', after: since, ...(cursor ? { cursor } : {}) },
    });
    for (const log of result.data.logs) {
      if (seen.has(log.id)) continue;
      seen.add(log.id);
      if (log.sent_at > since) since = log.sent_at;
      await removeFromMyList(log.to, log.response); // your code
    }
    cursor = result.data.has_more ? result.data.next_cursor : null;
  } while (cursor);
}, 10_000);
i

Las lecturas idénticas dentro de 1,5 segundos comparten un resultado, así que varios workers consultando lo mismo no añaden carga. Si necesitas el evento en el momento en que ocurre, usa el webhook bounced.

Más ejemplos

Cuerpo de la solicitud

{
  "commands": [
    {
      "command": "list_logs",
      "id": "ana",
      "args": {
        "recipient": "ana@acme.com"
      }
    },
    {
      "command": "list_logs",
      "id": "shipped",
      "args": {
        "subject": "order shipped",
        "status": "delivered",
        "after": "2026-10-10"
      }
    },
    {
      "command": "list_logs",
      "id": "gmail_spam",
      "args": {
        "domain": "gmail.com",
        "status": [
          "spam",
          "bounced"
        ]
      }
    },
    {
      "command": "list_logs",
      "id": "one_day",
      "args": {
        "after": "2026-10-16",
        "before": "2026-10-17",
        "limit": 20
      }
    }
  ]
}

El log

List Logs y Get Logs devuelven la misma estructura.

Log

{
  "id": "3f2a1b4c-8e9d-4f7a-b2c3-1a2b3c4d5e6f",
  "to": "ana@acme.com",
  "from": "noreply@yourdomain.com",
  "domain": "acme.com",
  "from_domain": "yourdomain.com",
  "subject": "Your order #1042 has shipped",
  "status": "delivered",
  "status_code": 2,
  "response": "250 2.0.0 OK 1760684401 a1si123456",
  "message": null,
  "blocked": false,
  "block_reason": null,
  "retries": 0,
  "tracking_id": "7CK-JDL-Y1L-20261017",
  "sent_at": "2026-10-17T06:00:01.204Z",
  "updated_at": "2026-10-17T06:00:02.913Z"
}

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 `logs:read`.

  • CMDINVALID_ARGS

    Un argumento no es válido: estado desconocido, destinatario que no es un email completo, limit fuera de rango, id que no es un UUID, after posterior a before…

  • CMDINVALID_CURSOR

    El cursor está mal formado, o viene de otra búsqueda u otra cuenta. Empieza de nuevo sin cursor.

  • CMDINTERNAL

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