Contacts: Lists

List Lists

Every list of the account, oldest first, optionally with member counts.

POSThttps://g.sendcorex.com/v1/contactscommand: list_lists
i

Needs the contact:read scope on your API key.

Arguments

  • with_statsbooleanoptional

    Add stats (members, sendable, opened, clicked) to each list.

  • include_deletingbooleanoptional

    Also return lists that were deleted and are still being cleaned up.

Quick start

import axios from 'axios';

const response = await axios.post(
  'https://g.sendcorex.com/v1/contacts',
  {
    commands: [
      {
        command: "list_lists",
        args: {
          with_stats: true
        }
      }
    ]
  },
  { 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_lists",
      "id": "0",
      "type": "SUCCESS",
      "took_ms": 14,
      "data": {
        "lists": [
          {
            "list_id": "customers",
            "name": "Customers",
            "description": "Everyone who bought at least once",
            "source": "checkout",
            "status": "ready",
            "custom": {
              "origin": "checkout",
              "year": 2026
            },
            "created_at": "2026-10-01T10:00:00.000Z",
            "updated_at": "2026-10-12T15:22:41.000Z",
            "stats": {
              "total": 1834,
              "ok": 1790,
              "opened": 912,
              "clicked": 233
            }
          }
        ]
      }
    }
  ]
}

Response fields

  • lists[].list_id

    The id you use in every list command.

  • lists[].name / description / source

    The attributes you set when creating or updating the list.

  • lists[].status

    ready, or deleting while a deleted list is being cleaned up.

  • lists[].custom

    Your own data, up to 50 keys.

  • lists[].stats

    Only with with_stats. total members, ok sendable members, and members who ever opened or clicked.

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 the scope this command needs. The other commands in the request still run.

  • CMDINVALID_ARGS

    A required argument is missing or invalid: email, field value, enum option, where key, list id…

  • CMDINTERNAL

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