Counters: Routes

Run Commands

The single entry point for your account counters. Send 1 to 20 commands in one request and get one result per command.

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

Same envelope as Logs and Contacts. Ask for the totals, this month and the last 30 days in one request.

i

Errors are reported per command. A command that fails does not stop the others, and the HTTP status stays 200.

Body parameters

  • commandsobject[]required

    1 to 20 commands, executed in order. The whole body can have up to 1 MB.

  • commands[].commandstringrequired

    get_totals, get_month, get_months, get_daily or get_hourly.

  • commands[].argsobjectoptional

    The command arguments.

  • commands[].idstringoptional

    Your own identifier for the result. Defaults to the index ("0", "1"…).

Quick start

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);
}

Response

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

Response fields

  • type

    Always SUCCESS when the request itself was accepted.

  • results[].command / id / type

    Which command, your id (or the index), and SUCCESS or ERROR.

  • results[].data

    The command output. Only present when type is SUCCESS.

  • results[].code / message

    The error. Only present when type is ERROR.

Authentication

Use the API key you create in the dashboard, under Developers → API Keys, with the counters:read scope.

  • Authorization

    Send Authorization: <api key> or Authorization: Bearer <api key>.

  • counters:read

    The only scope this route needs. It is read-only.

  • Mailbox tokens

    The webmail token does not work here. It is rejected with WRONG_CREDENTIAL_TYPE.

What is counted

  • Every email

    API, SMTP relay and campaigns, all together. Each email counts once, when it gets its final result.

  • Live

    The counters move a few seconds after each delivery result. There is no daily batch.

  • Hours and months in UTC

    get_hourly and get_month(s) use UTC. get_daily builds the days in the timezone you ask for.

Rate limits and cache

  • 15 requests / second

    Per IP + API key. Over that you get HTTP 429 with Retry-After.

  • Read cache: 1.5 s

    The same command with the same args within 1.5 seconds returns the same result.

Errors

HTTP-level errors return type, code and message. Errors marked CMD come back inside the command result, with HTTP 200.

  • 400INVALID_JSON

    The body is not {"commands":[...]} or is larger than 1 MB.

  • 400INVALID_ARGS

    The request has no commands or more than 20.

  • 401MISSING_AUTH_HEADER

    No Authorization header was sent.

  • 401INVALID_API_KEY

    The API key does not exist, was revoked or was disabled in the dashboard.

  • 401API_KEY_EXPIRED

    The API key passed the expiration date set in the dashboard.

  • 401WRONG_CREDENTIAL_TYPE

    A mailbox token was sent. The Counters API needs a dashboard API key.

  • 403IP_NOT_ALLOWED

    The request came from an IP that is not in the allowed IPs of the key.

  • 403ACCOUNT_BLOCKED

    The account is blocked.

  • 403MISSING_SCOPE

    The key does not have `counters:read`, so no command can run.

  • 429RATE_LIMITED

    More than 15 requests/s or 15 in flight for the same IP + API key. Wait the number of seconds in Retry-After.

  • 503AUTH_UNAVAILABLE

    Authentication is temporarily unavailable. Try again.

  • CMDUNKNOWN_COMMAND

    The command name does not exist.

  • CMDINTERNAL

    Server error. The detail is only written to the server log.