SendcorexDocs

Receive Emails: Reading

List Threads

List the conversations of a folder, Gmail style, with filters for unread, starred, important, attachments and dates.

POSThttps://g.sendcorex.com/v1command: list_threads
i

Each item is a conversation. Open it with get_thread or get_messages using its last_message_uid.

Arguments

  • folderstringoptional

    Folder to list. Defaults to INBOX.

  • limitnumberoptional

    Page size, from 1 to 100. Defaults to 25.

  • cursorstringoptional

    The next_cursor of the previous page.

  • is_readbooleanoptional

    false returns only conversations with an unread message.

  • is_starredbooleanoptional

    Filter by star.

  • is_importantbooleanoptional

    Filter by importance.

  • has_attachmentsbooleanoptional

    Filter by attachments.

  • afterstringoptional

    Only conversations whose last message is on or after this date (inclusive). RFC 3339, YYYY-MM-DD (UTC) or epoch in milliseconds.

    e.g. "2026-10-01"

  • beforestringoptional

    Only conversations whose last message is before this date (exclusive). Same formats as after.

    e.g. "2026-10-08T00:00:00+08:00"

Quick start

import axios from 'axios';

const response = await axios.post(
  'https://g.sendcorex.com/v1',
  {
    commands: [
      {
        command: "list_threads",
        args: {
          folder: "INBOX",
          is_read: false,
          limit: 20
        }
      }
    ]
  },
  { headers: { Authorization: process.env.SENDCOREX_TOKEN } },
);

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_threads",
      "id": "0",
      "type": "SUCCESS",
      "data": {
        "threads": [
          {
            "thread_id": "thr_9a1c4e72",
            "folder": "INBOX",
            "subject": "Invoice for September",
            "preview": "Hi, attached is the invoice for September…",
            "from_name": "Ana Costa",
            "from_email": "ana@client.com",
            "participants": [
              "ana@client.com",
              "you@yourdomain.com"
            ],
            "last_senders": [
              "ana@client.com"
            ],
            "message_count": 2,
            "thread_message_count": 3,
            "unread_count": 1,
            "has_unread": true,
            "has_starred": false,
            "has_important": false,
            "has_attachments": false,
            "last_message_uid": "Vj0xQUJDMTIz",
            "last_message_at": "2026-10-09T14:21:07Z"
          }
        ],
        "has_more": true,
        "next_cursor": "eyJwIjoyfQ"
      }
    }
  ]
}

Response fields

  • threads[].thread_id

    The conversation id.

  • threads[].folder

    The folder being listed.

  • threads[].subject

    Subject of the conversation.

  • threads[].preview

    Short preview of the latest message.

  • threads[].from_name / from_email

    Sender of the latest message.

  • threads[].participants

    Everyone in the conversation.

  • threads[].last_senders

    Who wrote the latest messages.

  • threads[].message_count

    Messages in this folder.

  • threads[].thread_message_count

    Messages in the whole conversation.

  • threads[].unread_count / has_unread

    Unread messages in the conversation.

  • threads[].has_starred / has_important / has_attachments

    Flags of the conversation.

  • threads[].last_message_uid

    The id to open the conversation with get_messages or get_thread.

  • threads[].last_message_at

    Date of the latest message.

  • has_more / next_cursor

    Pagination. Send next_cursor as cursor to get the next page.

Filters and speed

is_read: false, is_starred: true and is_important: true use their own index, so only matching conversations are examined, not the whole folder. If you combine them, one index is used (star, then important, then unread) and the rest is filtered on top of it. after and before are key ranges, so nothing outside the period is scanned. has_attachments and the false values of star and important still scan the folder.

Unread conversations in a date range

{
  "commands": [
    {
      "command": "list_threads",
      "args": {
        "is_read": false,
        "after": "2026-10-01",
        "before": "2026-10-08T00:00:00+08:00"
      }
    }
  ]
}

Pagination

When has_more is true, call the command again with cursor set to next_cursor.

Node.js

let cursor;
const threads = [];

do {
  const [result] = await call({
    command: 'list_threads',
    args: { folder: 'INBOX', limit: 100, ...(cursor ? { cursor } : {}) },
  });
  threads.push(...result.data.threads);
  cursor = result.data.has_more ? result.data.next_cursor : null;
} while (cursor);
i

call is any helper that posts { commands: [...] } to /v1 and returns results, as in Run Commands.

Errors

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

  • 401TOKEN_EXPIRED

    The access token has expired. Call Refresh Token and repeat the request.

  • 401INVALID_TOKEN

    The token is malformed, unknown or revoked.

  • 429RATE_LIMITED

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

  • CMDINVALID_ARGS

    A required argument is missing or invalid.

  • CMDINVALID_CURSOR

    The cursor is malformed or belongs to another account or folder.

  • CMDINTERNAL

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