Logs: Rotas

Run Commands

O ponto de entrada único para os logs de entrega. Envie de 1 a 20 comandos em uma requisição e receba um resultado por comando.

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

É o mesmo envelope de Contacts: toda leitura é um comando enviado para esta rota. As páginas abaixo desta documentam cada comando e seus argumentos.

i

Os erros são reportados por comando. Um comando que falha não interrompe os outros, e o status HTTP continua 200.

Parâmetros do corpo

  • commandsobject[]obrigatório

    1 a 20 comandos, executados em ordem. O corpo inteiro pode ter até 1 MB.

  • commands[].commandstringobrigatório

    list_logs ou get_logs.

  • commands[].argsobjectopcional

    Os argumentos do comando. Qualquer valor pode ser um $ref para o resultado de um comando anterior.

  • commands[].idstringopcional

    Seu próprio identificador para o resultado. Padrão: o índice ("0", "1"…). Obrigatório se você quiser usar $ref.

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

Resposta

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

  • type

    Sempre SUCCESS quando a requisição em si foi aceita.

  • results[].command

    O comando que gerou este resultado.

  • results[].id

    O id que você enviou, ou o índice do comando.

  • results[].type

    SUCCESS ou ERROR.

  • results[].took_ms

    Tempo que o comando levou dentro do servidor. O resto do tempo da requisição é rede.

  • results[].data

    A saída do comando. Só aparece quando type é SUCCESS.

  • results[].code / message

    O erro. Só aparece quando type é ERROR.

Autenticação

Os logs usam a API key que você cria no dashboard, em Developers → API Keys, com o escopo logs:read. É o mesmo tipo de key usado para enviar email e gerenciar contatos.

  • Authorization

    Envie Authorization: <api key> ou Authorization: Bearer <api key>.

  • logs:read

    O único escopo de que os logs precisam. É somente leitura: nada nesta rota altera dados.

  • Tokens de mailbox

    O token do webmail não funciona aqui. Ele é rejeitado com WRONG_CREDENTIAL_TYPE.

  • IPs permitidos

    Se a key tem uma allowlist de IPs, requisições de outros IPs recebem 403 IP_NOT_ALLOWED.

  • Revogação

    As keys ficam em cache por 60 segundos, então uma key revogada para de funcionar em até um minuto. A data de expiração é verificada em toda requisição.

Use um resultado anterior com $ref

Qualquer valor dentro de args pode ser {"$ref": "<id>", "path": "<path>"}. Ele é substituído pelo valor encontrado em path no resultado do comando com esse id. Em path, * percorre uma lista. Esta requisição lista os bounces mais recentes e lê os corpos deles, em uma única ida e volta.

Corpo da requisição

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

O que há nos logs

  • Todo envio

    Cada email que você envia ganha um log, que é atualizado conforme a entrega tem um resultado.

  • 60 dias

    Os logs ficam guardados por 60 dias. Os mais antigos somem, e os ids deles voltam em not_found.

  • Sem warm-up

    Emails enviados pelo warm-up de inbox nunca aparecem, então o polling só retorna o seu tráfego real.

  • Sem corpo por padrão

    Listas nunca trazem o HTML. Get Logs só o retorna com include_content: true.

Rate limits e cache

Os limites valem por IP + API key. Não há fila: quando você passa do limite, a requisição é rejeitada com HTTP 429 e um header Retry-After.

  • 15 requisições / segundo

    Pico de 15. Respostas servidas pelo cache também contam.

  • 15 simultâneas

    No máximo 15 requisições sendo processadas ao mesmo tempo. Percorrer muitas páginas em paralelo é o jeito mais comum de atingir esse limite: percorra uma depois da outra.

  • Cache de leitura: 1,5 s

    A mesma leitura (mesmo comando e args) dentro de 1,5 segundo retorna o mesmo resultado, e leituras idênticas em andamento compartilham uma consulta. Fazer polling a cada poucos segundos não tem problema.

Cursores

List Logs retorna next_cursor enquanto houver mais. Ele é opaco: devolva-o como veio, com os mesmos filtros.

next_cursor

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

Erros

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

  • 400INVALID_JSON

    O corpo não é {"commands":[...]} ou tem mais de 1 MB.

  • 400INVALID_ARGS

    A requisição não tem comandos ou tem mais de 20.

  • 401MISSING_AUTH_HEADER

    Nenhum header Authorization foi enviado.

  • 401INVALID_API_KEY

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

  • 401API_KEY_EXPIRED

    A API key passou da data de expiração definida no dashboard.

  • 401WRONG_CREDENTIAL_TYPE

    Foi enviado um token de mailbox. Os logs precisam de uma API key do dashboard.

  • 403IP_NOT_ALLOWED

    A requisição veio de um IP que não está nos IPs permitidos da key.

  • 403ACCOUNT_BLOCKED

    A conta está bloqueada.

  • 403MISSING_SCOPE

    A key não tem `logs:read`, então nenhum comando pode rodar.

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

  • 503AUTH_UNAVAILABLE

    A autenticação está temporariamente indisponível. Tente de novo.

  • CMDUNKNOWN_COMMAND

    O nome do comando não existe.

  • CMDINTERNAL

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