Logs: Leitura

Listar logs

Seus logs de entrega, do mais novo para o mais antigo, até 50 por página. Filtre por status, destinatário, assunto, domínio, remetente e data, em qualquer combinação.

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

Requer o escopo logs:read na sua API key.

i

Os filtros se combinam com AND. Sem after, você recebe os últimos 60 dias, que é o tempo que os logs ficam guardados.

i

Emails de warm-up nunca aparecem aqui, e o corpo do email nunca faz parte de uma lista. Use Get Logs com include_content para ler um.

Argumentos

  • statusstring | string[]opcional

    delivered, bounced, spam, rate_limited ou not_sent, ou uma lista deles. Sem ele, você recebe os cinco.

    ex.: "bounced"

  • recipientstringopcional

    Um endereço de email completo. Maiúsculas e espaços ao redor são ignorados.

    ex.: "ana@acme.com"

  • subjectstringopcional

    Palavras do assunto. Palavras inteiras, e todas precisam estar lá: order shipped encontra "Your order #1042 has shipped", ord não. Acentos e maiúsculas são ignorados.

    ex.: "order shipped"

  • searchstringopcional

    Texto livre, para uma caixa de busca. Com um @ é um destinatário; caso contrário, são palavras do assunto.

    ex.: "ana@acme.com"

  • domainstringopcional

    O domínio do destinatário, exato.

    ex.: "gmail.com"

  • fromstringopcional

    O endereço do remetente, exato.

    ex.: "noreply@yourdomain.com"

  • afterstring | numberopcional

    Só logs enviados neste momento ou depois. ISO 8601, YYYY-MM-DD (meia-noite UTC) ou epoch em milissegundos. Padrão: 60 dias atrás.

    ex.: "2026-10-01"

  • beforestring | numberopcional

    Só logs enviados antes deste momento. Mesmos formatos.

    ex.: "2026-10-17T00:00:00Z"

  • limitnumberopcional

    Tamanho da página, de 1 a 50. Padrão: 50.

    ex.: 50

  • cursorstringopcional

    O next_cursor da página anterior. Envie com os mesmos filtros.

Início 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);

Resposta

{
  "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 da resposta

  • logs

    Os logs desta página, do mais novo para o mais antigo. Cada um tem os campos abaixo.

  • count

    Quantos logs há nesta página.

  • has_more / next_cursor

    Enquanto has_more for true, envie next_cursor como cursor com os mesmos filtros.

  • partial

    true quando a busca atingiu o limite de tempo antes de preencher a página. A página pode ter menos logs, até zero, e o next_cursor continua de onde parou.

  • total / total_exact

    Quantos logs batem com os filtros, só na primeira página (a requisição sem cursor). Nas páginas seguintes os dois vêm null, então guarde o primeiro valor. total só vem com número quando é exato (total_exact: true). Com total: null e total_exact: false, são logs demais para contar; com os dois null, a busca não pode ser contada (por exemplo, um assunto sem palavra indexável). Nos dois casos, continue paginando por has_more.

  • logs[].id

    O ID do email (um UUID). É o id que você recebe ao enviar, e o que você passa para o Get Logs.

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

    O destinatário e o domínio do destinatário.

  • logs[].from_domain

    O domínio do remetente (a parte depois do @ em from).

  • logs[].from

    O endereço do remetente.

  • logs[].subject

    A linha de assunto.

  • logs[].status

    delivered, bounced, spam, rate_limited ou not_sent. status_code é a mesma coisa em número.

  • logs[].response

    O que o servidor de destino respondeu, por exemplo 250 2.0.0 OK ou o motivo do bounce 550.

  • logs[].message

    Detalhe extra da Sendcorex sobre a entrega, quando houver.

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

    true quando a Sendcorex não enviou para esse destinatário (suprimido ou restrito), e o motivo.

  • logs[].retries

    Quantas vezes a entrega foi tentada de novo.

  • logs[].tracking_id

    O id interno da entrega. Os webhooks de bounce e de reclamação trazem o mesmo valor.

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

    Quando o email foi enviado e quando o status dele mudou pela última vez. ISO 8601, UTC.

Status

  • delivered

    O servidor de destino aceitou o email.

  • bounced

    O servidor de destino o rejeitou de vez: o endereço não existe, o domínio não aceita emails…

  • spam

    O servidor de destino o recusou como spam.

  • rate_limited

    O servidor de destino continuou adiando e as tentativas acabaram.

  • not_sent

    Não enviado por causa da sua conta (por exemplo, sem créditos, conta bloqueada ou restrita, domínio do remetente na Spamhaus ou sem DKIM, ou From inválido). Não é bounce. O motivo exato vem em response.

i

Emails ainda aguardando uma nova tentativa não aparecem aqui: eles surgem quando chegam a um destes cinco status.

Paginação

Continue enquanto has_more for true. Não pare em uma página curta ou vazia: quando partial é true, a busca ficou sem tempo naquela chamada, não sem 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 é qualquer helper que faz POST de { commands: [...] } para /v1/logs e retorna results, como em Run Commands.

!

Um cursor só funciona com os filtros de onde veio. Mude um filtro e você recebe INVALID_CURSOR: comece de novo sem cursor.

Acompanhando novos bounces

Para reagir a bounces (ou qualquer outra coisa) assim que acontecem, faça polling com after igual ao sent_at mais recente que você viu. after inclui esse momento, então o último log volta mais uma vez: ignore ids que você já tem.

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

Leituras idênticas dentro de 1,5 segundo compartilham um resultado, então vários workers consultando a mesma coisa não aumentam a carga. Se você precisa do evento no momento em que acontece, use o webhook bounced.

Mais exemplos

Corpo da requisição

{
  "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
      }
    }
  ]
}

O log

List Logs e Get Logs retornam o mesmo formato.

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"
}

Erros

Erros no nível HTTP retornam type, code e message. Erros marcados com CMD voltam dentro do resultado do comando, com HTTP 200.

  • 401INVALID_API_KEY

    A API key não existe, foi revogada ou foi desativada no dashboard.

  • 429RATE_LIMITED

    Mais de 15 requisições/s ou 15 simultâneas para o mesmo IP + API key. Aguarde o número de segundos em Retry-After.

  • CMDMISSING_SCOPE

    A API key não tem `logs:read`.

  • CMDINVALID_ARGS

    Um argumento é inválido: status desconhecido, destinatário que não é um email completo, limit fora do intervalo, id que não é UUID, after depois de before…

  • CMDINVALID_CURSOR

    O cursor está malformado, ou veio de outra busca ou outra conta. Comece de novo sem cursor.

  • CMDINTERNAL

    Erro no servidor. O detalhe só é gravado no log do servidor.