Counters: Rotas

Run Commands

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

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

Mesmo envelope de Logs e Contacts. Peça os totais, este mês e os últimos 30 dias em uma requisição.

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

    get_totals, get_month, get_months, get_daily ou get_hourly.

  • commands[].argsobjectopcional

    Os argumentos do comando.

  • commands[].idstringopcional

    Seu próprio identificador para o resultado. Padrão: o índice ("0", "1"…).

Início rápido

import axios from 'axios';

const response = await axios.post(
  'https://g.sendcorex.com/v1/counters',
  {
    commands: [
      {
        command: "get_totals",
        id: "all"
      },
      {
        command: "get_month",
        id: "now"
      }
    ]
  },
  { 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": "get_totals",
      "id": "all",
      "type": "SUCCESS",
      "took_ms": 3,
      "data": {
        "totals": {
          "delivered": 48210,
          "bounced": 612,
          "blocked": 88,
          "complaints": 9,
          "rate_limited": 140,
          "total": 49050,
          "delivered_rate": 98.29,
          "bounce_rate": 1.25,
          "blocked_rate": 0.18,
          "complaint_rate": 0.02,
          "rate_limited_rate": 0.29
        }
      }
    },
    {
      "command": "get_month",
      "id": "now",
      "type": "SUCCESS",
      "took_ms": 2,
      "data": {
        "month": "2026-10",
        "delivered": 48210,
        "bounced": 612,
        "blocked": 88,
        "complaints": 9,
        "rate_limited": 140,
        "total": 49050,
        "delivered_rate": 98.29,
        "bounce_rate": 1.25,
        "blocked_rate": 0.18,
        "complaint_rate": 0.02,
        "rate_limited_rate": 0.29
      }
    }
  ]
}

Campos da resposta

  • type

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

  • results[].command / id / type

    Qual comando, seu id (ou o índice), e SUCCESS ou ERROR.

  • results[].data

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

  • results[].code / message

    O erro. Só aparece quando type é ERROR.

Autenticação

Use a API key que você cria no dashboard, em Developers → API Keys, com o escopo counters:read.

  • Authorization

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

  • counters:read

    O único escopo de que esta rota precisa. É somente leitura.

  • Tokens de mailbox

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

O que é contado

  • Todo email

    API, SMTP relay e campanhas, tudo junto. Cada email conta uma vez, quando recebe seu resultado final.

  • Em tempo real

    Os contadores mudam alguns segundos depois de cada resultado de entrega. Não há processamento diário em lote.

  • Horas e meses em UTC

    get_hourly e get_month(s) usam UTC. get_daily monta os dias no fuso horário que você pedir.

Rate limits e cache

  • 15 requisições / segundo

    Por IP + API key. Acima disso você recebe HTTP 429 com Retry-After.

  • Cache de leitura: 1,5 s

    O mesmo comando com os mesmos args dentro de 1,5 segundo retorna o mesmo resultado.

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. A Counters API precisa 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 `counters: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.