Logs: Reading

List Logs

Your delivery logs, newest first, up to 50 per page. Filter by status, recipient, subject, domain, sender and date, in any combination.

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

Needs the logs:read scope on your API key.

i

Filters combine with AND. Without after, you get the last 60 days, which is how long logs are kept.

i

Warm-up emails never show up here, and the email body is never part of a list. Use Get Logs with include_content to read one.

Arguments

  • statusstring | string[]optional

    delivered, bounced, spam, rate_limited or not_sent, or a list of them. Without it you get all five.

    e.g. "bounced"

  • recipientstringoptional

    A full email address. Case and surrounding spaces are ignored.

    e.g. "ana@acme.com"

  • subjectstringoptional

    Words of the subject. Whole words, and every word must be there: order shipped finds "Your order #1042 has shipped", ord does not. Accents and case are ignored.

    e.g. "order shipped"

  • searchstringoptional

    Free text, for a search box. With an @ it is a recipient, otherwise it is subject words.

    e.g. "ana@acme.com"

  • domainstringoptional

    The recipient domain, exactly.

    e.g. "gmail.com"

  • fromstringoptional

    The sender address, exactly.

    e.g. "noreply@yourdomain.com"

  • afterstring | numberoptional

    Only logs sent at or after this moment. ISO 8601, YYYY-MM-DD (midnight UTC) or epoch milliseconds. Defaults to 60 days ago.

    e.g. "2026-10-01"

  • beforestring | numberoptional

    Only logs sent before this moment. Same formats.

    e.g. "2026-10-17T00:00:00Z"

  • limitnumberoptional

    Page size, from 1 to 50. Defaults to 50.

    e.g. 50

  • cursorstringoptional

    The next_cursor of the previous page. Send it with the same filters.

Quick start

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

Response

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

Response fields

  • logs

    The logs of this page, newest first. Each one has the fields below.

  • count

    How many logs are in this page.

  • has_more / next_cursor

    While has_more is true, send next_cursor as cursor with the same filters.

  • partial

    true when the search hit its time limit before filling the page. The page can have fewer logs, even zero, and next_cursor continues from where it stopped.

  • total / total_exact

    How many logs match the filters, on the first page only (the request without cursor). On later pages both are null, so keep the first value. total is a number only when it is exact (total_exact: true). With total: null and total_exact: false there are too many to count; with both null the search cannot be counted (for example a subject with no indexable word). Keep paging with has_more either way.

  • logs[].id

    The email ID (a UUID). It is the id you get back when you send, and what you pass to Get Logs.

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

    The recipient and the recipient's domain.

  • logs[].from_domain

    The sender's domain (the part after @ in from).

  • logs[].from

    The sender address.

  • logs[].subject

    The subject line.

  • logs[].status

    delivered, bounced, spam, rate_limited or not_sent. status_code is the same thing as a number.

  • logs[].response

    What the recipient server answered, for example 250 2.0.0 OK or the 550 bounce reason.

  • logs[].message

    Extra detail from Sendcorex about the delivery, when there is any.

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

    true when Sendcorex did not send to this recipient (suppressed or restricted), and why.

  • logs[].retries

    How many times the delivery was retried.

  • logs[].tracking_id

    The internal delivery id. Bounce and complaint webhooks carry the same value.

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

    When the email was sent, and when its status last changed. ISO 8601, UTC.

Statuses

  • delivered

    The recipient server accepted the email.

  • bounced

    The recipient server rejected it for good: the address does not exist, the domain does not accept mail…

  • spam

    The recipient server refused it as spam.

  • rate_limited

    The recipient server kept deferring it and the retries ran out.

  • not_sent

    Not sent because of your account (for example, no credits left, a blocked or restricted account, a sender domain listed on Spamhaus or without DKIM, or an invalid From). It is not a bounce. The exact reason is in response.

i

Emails still waiting for a retry are not here yet: they show up when they reach one of these five statuses.

Pagination

Keep going while has_more is true. Do not stop on a short or empty page: when partial is true the search ran out of time on that call, not out of 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 is any helper that posts { commands: [...] } to /v1/logs and returns results, as in Run Commands.

!

A cursor only works with the filters it came from. Change a filter and you get INVALID_CURSOR: start again without one.

Watching for new bounces

To react to bounces (or anything else) as they happen, poll with after set to the newest sent_at you have seen. after includes that moment, so the last log comes back once more: skip ids you already have.

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

Identical reads within 1.5 seconds share one result, so several workers polling the same thing do not add load. If you need the event the moment it happens, use the bounced webhook instead.

More examples

Request body

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

The log

List Logs and Get Logs return the same shape.

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

Errors

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

  • 401INVALID_API_KEY

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

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

  • CMDMISSING_SCOPE

    The API key does not have `logs:read`.

  • CMDINVALID_ARGS

    An argument is invalid: unknown status, recipient that is not a full email, limit out of range, id that is not a UUID, after later than before…

  • CMDINVALID_CURSOR

    The cursor is malformed, or it came from a different search or account. Start again without a cursor.

  • CMDINTERNAL

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