List messages

GET/api/v1/mailbox/messages
Requires amailbox token— it acts as one mailbox holder, not as the organization.

Messages in one folder, newest first, a page at a time. folder defaults to the inbox. search (or q) matches the sender, recipients, subject and body. Combine the filters freely. Page with offset and limit (default 50, at most 200) while has_more is true.

Errors

Status When
401 No token, or the session expired or was signed out. Sign in again with POST /mailbox-auth/login.
403 The account has a temporary password: until POST /security/password succeeds, every other call answers this with error_code: password_change_required.
404 No folder by that name.

Parameters

NameInTypeDescription
folderquerystring
searchquerystring
qquerystring
unreadqueryboolean
starredqueryboolean
labelquerystring
attachmentsqueryboolean
mentionedqueryboolean
limitqueryinteger
offsetqueryinteger

Request

GET/api/v1/mailbox/messages
curl -X GET 'https://courier.mailyte.com/api/v1/mailbox/messages' \
  -H 'Authorization: Bearer MAILBOX_TOKEN'

Response

Successful Response

  • dataobject
    • messagesarray<object>
      • idstring

        This message's id: folder:uid, e.g. INBOX:4821. Use it in every per-message call.

      • folderstring
      • subjectstring
      • fromarray<object>
        • namestring or null
        • emailstringrequired
      • toarray<object>
        • namestring or null
        • emailstringrequired
      • ccarray<object>
        • namestring or null
        • emailstringrequired
      • received_atstring or null

        ISO 8601 with offset.

      • sizeinteger

        Bytes.

      • has_attachmentboolean
      • is_readboolean
      • is_starredboolean
      • is_answeredboolean
      • is_draftboolean
      • keywordsarray<string>

        Labels on this message.

      • previewstring or null

        The first line or two of text.

      • thread_idstring or null
      • message_idstring or null

        The RFC 5322 Message-ID header.

    • totalinteger

      Matching messages in all pages.

    • offsetinteger
    • limitinteger
    • has_moreboolean
200application/json
{
  "type": "success",
  "msg": "Messages retrieved successfully",
  "data": {
    "messages": [
      {
        "id": "INBOX:4821",
        "folder": "INBOX",
        "subject": "Re: the quarterly numbers",
        "from": [
          {
            "name": "Tunde Bello",
            "email": "tunde@example.com"
          }
        ],
        "to": [
          {
            "name": "Ada Obi",
            "email": "ada@yourdomain.com"
          }
        ],
        "cc": [],
        "received_at": "2026-10-11T09:14:02+00:00",
        "size": 18432,
        "has_attachment": true,
        "is_read": false,
        "is_starred": false,
        "is_answered": false,
        "is_draft": false,
        "keywords": [],
        "preview": "Attached are the Q3 figures we discussed.",
        "thread_id": "1a2b3c",
        "message_id": "<CAJ9x2Q@mail.example.com>"
      }
    ],
    "total": 1284,
    "offset": 0,
    "limit": 50,
    "has_more": true
  }
}

Returned inside the standard envelope.

Errors

StatusWhen
401No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.
403The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.
404No folder by that name.
422Validation Error

Every status, with what causes it and what to do, is on the error reference.