List Messages

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

  Filter by read state. This filter scans the folder.

• is_starredbooleanoptional

  Filter by star. This filter scans the folder.

• is_importantbooleanoptional

  Filter by importance. This filter scans the folder.

• is_spambooleanoptional

  Filter by spam. This filter scans the folder.

• afterstringoptional

  Only messages received on or after this date. RFC 3339, YYYY-MM-DD (UTC) or epoch in milliseconds.

• beforestringoptional

  Only messages received before this date. Same formats as after.

• labelstringoptional

  List the messages with this label in every folder. folder and the boolean filters are ignored. Case-insensitive. after and before still work.

  e.g. "cliente-vip"

Quick start

import axios from 'axios';

const response = await axios.post(
  'https://g.sendcorex.com/v1',
  {
    commands: [
      {
        command: "list_messages",
        args: {
          folder: "INBOX",
          is_read: false,
          limit: 50
        }
      }
    ]
  },
  { 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_messages",
      "id": "0",
      "type": "SUCCESS",
      "data": {
        "messages": [
          {
            "message_uid": "Vj0xQUJDMTIz",
            "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",
            "has_attachments": false,
            "size_bytes": 4821,
            "is_read": false,
            "is_starred": false,
            "is_important": false,
            "is_spam": false,
            "snoozed_until": null,
            "received_at": "2026-10-09T14:21:07Z"
          }
        ],
        "has_more": false,
        "next_cursor": null
      }
    }
  ]
}

Response fields

• messages[].message_uid

  The message id.

• messages[].thread_id

  The conversation the message belongs to.

• messages[].folder

  The folder of this entry.

• messages[].subject / preview

  Subject and a short preview.

• messages[].from_name / from_email

  The sender.

• messages[].has_attachments / size_bytes

  Attachment flag and message size.

• messages[].is_read / is_starred / is_important / is_spam

  Message state.

• messages[].snoozed_until

  When a snoozed message is due, or null.

• messages[].received_at

  When the message was received.

• has_more / next_cursor

  Pagination.

List by label

With label, the command reads the label index, so only labeled messages are examined. Each message is returned with its current state across all folders, so you get folders and labels instead of a single folder.

{
  "messages": [
    {
      "message_uid": "Vj0xQUJDMTIz",
      "thread_id": "thr_9a1c4e72",
      "subject": "Invoice for September",
      "preview": "Hi, attached is the invoice for September…",
      "from_name": "Ana Costa",
      "from_email": "ana@client.com",
      "folders": [
        "INBOX"
      ],
      "labels": [
        "cliente-vip"
      ],
      "is_read": false,
      "is_starred": false,
      "is_important": false,
      "received_at": "2026-10-09T14:21:07Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

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.