Logs: Rutas

Run Commands

El punto de entrada único para los logs de entrega. Envía de 1 a 20 comandos en una solicitud y obtén un resultado por comando.

POSThttps://g.sendcorex.com/v1/logs
i

Es el mismo sobre que Contacts: cada lectura es un comando enviado a esta ruta. Las páginas debajo de esta documentan cada comando y sus argumentos.

i

Los errores se informan por comando. Un comando que falla no detiene a los demás, y el estado HTTP sigue siendo 200.

Parámetros del cuerpo

  • commandsobject[]obligatorio

    De 1 a 20 comandos, ejecutados en orden. El cuerpo completo puede tener hasta 1 MB.

  • commands[].commandstringobligatorio

    list_logs o get_logs.

  • commands[].argsobjectopcional

    Los argumentos del comando. Cualquier valor puede ser un $ref al resultado de un comando anterior.

  • commands[].idstringopcional

    Tu propio identificador para el resultado. Por defecto, el índice ("0", "1"…). Obligatorio si quieres usar $ref.

Inicio rápido

import axios from 'axios';

const response = await axios.post(
  'https://g.sendcorex.com/v1/logs',
  {
    commands: [
      {
        command: "list_logs",
        id: "bounces",
        args: {
          status: "bounced",
          limit: 20
        }
      },
      {
        command: "get_logs",
        id: "one",
        args: {
          id: "3f2a1b4c-8e9d-4f7a-b2c3-1a2b3c4d5e6f"
        }
      }
    ]
  },
  { headers: { Authorization: process.env.SENDCOREX_API_KEY } },
);

for (const result of response.data.results) {
  if (result.type !== 'SUCCESS') console.error(result.id, result.code, result.message);
  else console.log(result.id, result.data);
}

Respuesta

{
  "type": "SUCCESS",
  "results": [
    {
      "command": "list_logs",
      "id": "bounces",
      "type": "SUCCESS",
      "took_ms": 21,
      "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": false,
        "next_cursor": null,
        "partial": false
      }
    },
    {
      "command": "get_logs",
      "id": "one",
      "type": "SUCCESS",
      "took_ms": 9,
      "data": {
        "logs": [
          {
            "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"
          }
        ],
        "not_found": []
      }
    }
  ]
}

Campos de la respuesta

  • type

    Siempre SUCCESS cuando la solicitud en sí fue aceptada.

  • results[].command

    El comando que produjo este resultado.

  • results[].id

    El id que enviaste, o el índice del comando.

  • results[].type

    SUCCESS o ERROR.

  • results[].took_ms

    Tiempo que tardó el comando dentro del servidor. El resto del tiempo de la solicitud es red.

  • results[].data

    La salida del comando. Solo está presente cuando type es SUCCESS.

  • results[].code / message

    El error. Solo está presente cuando type es ERROR.

Autenticación

Los logs usan la API key que creas en el dashboard, en Developers → API Keys, con el scope logs:read. Es el mismo tipo de key que se usa para enviar emails y gestionar contactos.

  • Authorization

    Envía Authorization: <api key> o Authorization: Bearer <api key>.

  • logs:read

    El único scope que necesitan los logs. Es de solo lectura: nada en esta ruta modifica datos.

  • Tokens de mailbox

    El token del webmail no funciona aquí. Se rechaza con WRONG_CREDENTIAL_TYPE.

  • IPs permitidas

    Si la key tiene una lista de IPs permitidas, las solicitudes desde otras IPs reciben 403 IP_NOT_ALLOWED.

  • Revocación

    Las keys se guardan en caché durante 60 segundos, así que una key revocada deja de funcionar en menos de un minuto. La fecha de expiración se comprueba en cada solicitud.

Usa un resultado anterior con $ref

Cualquier valor dentro de args puede ser {"$ref": "<id>", "path": "<path>"}. Se reemplaza por el valor encontrado en path en el resultado del comando con ese id. En path, * recorre una lista. Esta solicitud lista los últimos bounces y lee sus cuerpos, en un solo viaje de ida y vuelta.

Cuerpo de la solicitud

{
  "commands": [
    {
      "command": "list_logs",
      "id": "b",
      "args": {
        "status": "bounced",
        "limit": 10
      }
    },
    {
      "command": "get_logs",
      "args": {
        "ids": {
          "$ref": "b",
          "path": "logs/*/id"
        },
        "include_content": true
      }
    }
  ]
}

Qué hay en los logs

  • Cada envío

    Cada email que envías tiene un log, que se actualiza a medida que la entrega obtiene un resultado.

  • 60 días

    Los logs se guardan durante 60 días. Los más antiguos desaparecen y sus ids vuelven en not_found.

  • Sin warm-up

    Los emails enviados por el warm-up de bandeja nunca aparecen, así que el polling solo devuelve tu tráfico real.

  • Sin cuerpo por defecto

    Las listas nunca traen el HTML. Get Logs lo devuelve solo con include_content: true.

Rate limits y caché

Los límites se aplican por IP + API key. No hay cola: cuando te pasas, la solicitud se rechaza con HTTP 429 y un header Retry-After.

  • 15 solicitudes / segundo

    Pico de 15. Las respuestas servidas desde la caché también cuentan.

  • 15 simultáneas

    Como máximo 15 solicitudes procesándose al mismo tiempo. Recorrer muchas páginas en paralelo es la forma habitual de alcanzarlo: recórrelas una tras otra.

  • Caché de lectura: 1,5 s

    La misma lectura (mismo comando y args) dentro de 1,5 segundos devuelve el mismo resultado, y las lecturas idénticas en curso comparten una consulta. Hacer polling cada pocos segundos está bien.

Cursores

List Logs devuelve next_cursor mientras haya más. Es opaco: devuélvelo tal cual, con los mismos filtros.

next_cursor

{
  "has_more": true,
  "next_cursor": "MDAwMDAwMDA4MzowOjgyMzkzMTU5OTg3OTU6M2YyYTFi",
  "partial": false
}

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.

  • 400INVALID_JSON

    El cuerpo no es {"commands":[...]} o pesa más de 1 MB.

  • 400INVALID_ARGS

    La solicitud no tiene comandos o tiene más de 20.

  • 401MISSING_AUTH_HEADER

    No se envió ningún header Authorization.

  • 401INVALID_API_KEY

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

  • 401API_KEY_EXPIRED

    La API key superó la fecha de expiración definida en el dashboard.

  • 401WRONG_CREDENTIAL_TYPE

    Se envió un token de mailbox. Los logs necesitan una API key del dashboard.

  • 403IP_NOT_ALLOWED

    La solicitud vino de una IP que no está entre las IPs permitidas de la key.

  • 403ACCOUNT_BLOCKED

    La cuenta está bloqueada.

  • 403MISSING_SCOPE

    La key no tiene `logs:read`, así que no se puede ejecutar ningún comando.

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

  • 503AUTH_UNAVAILABLE

    La autenticación no está disponible temporalmente. Inténtalo de nuevo.

  • CMDUNKNOWN_COMMAND

    El nombre del comando no existe.

  • CMDINTERNAL

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