Logs: Routes

Run Commands

The single entry point for delivery logs. Send 1 to 20 commands in one request and get one result per command.

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

It is the same envelope as Contacts: every read is a command sent to this route. The pages below this one document each command and its arguments.

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

    list_logs or get_logs.

  • commands[].argsobjectoptional

    The command arguments. Any value can be a $ref to the result of an earlier command.

  • commands[].idstringoptional

    Your own identifier for the result. Defaults to the index ("0", "1"…). Required if you want to use $ref.

Quick start

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

Response

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

Response fields

  • type

    Always SUCCESS when the request itself was accepted.

  • results[].command

    The command that produced this result.

  • results[].id

    The id you sent, or the index of the command.

  • results[].type

    SUCCESS or ERROR.

  • results[].took_ms

    Time the command took inside the server. The rest of the request time is network.

  • results[].data

    The command output. Only present when type is SUCCESS.

  • results[].code / message

    The error. Only present when type is ERROR.

Authentication

Logs use the API key you create in the dashboard, under Developers → API Keys, with the logs:read scope. It is the same kind of key used to send email and to manage contacts.

  • Authorization

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

  • logs:read

    The only scope logs need. It is read-only: nothing on this route changes data.

  • Mailbox tokens

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

  • Allowed IPs

    If the key has an IP allowlist, requests from other IPs get 403 IP_NOT_ALLOWED.

  • Revoking

    Keys are cached for 60 seconds, so a revoked key stops working within a minute. The expiration date is checked on every request.

Use a previous result with $ref

Any value inside args can be {"$ref": "<id>", "path": "<path>"}. It is replaced by the value found at path in the result of the command with that id. In path, * walks a list. This request lists the latest bounces and reads their bodies, in one round trip.

Request body

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

What is in the logs

  • Every send

    Each email you send gets one log, which is updated as the delivery gets a result.

  • 60 days

    Logs are kept for 60 days. Older ones are gone, and their ids come back in not_found.

  • No warm-up

    Emails sent by inbox warm-up never show up, so polling only returns your real traffic.

  • No body by default

    Lists never carry the HTML. Get Logs returns it only with include_content: true.

Rate limits and cache

Limits apply per IP + API key. There is no queue: when you go over, the request is rejected with HTTP 429 and a Retry-After header.

  • 15 requests / second

    Peak of 15. Responses served from the cache count too.

  • 15 in flight

    At most 15 requests being processed at the same time. Walking many pages in parallel is the usual way to hit it: walk them one after the other.

  • Read cache: 1.5 s

    The same read (same command and args) within 1.5 seconds returns the same result, and identical reads in flight share one query. Polling every few seconds is fine.

Cursors

List Logs returns next_cursor while there is more. It is opaque: pass it back as it is, with the same filters.

next_cursor

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

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. Logs need 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 `logs: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.