List messages
GET
/api/v1/mailbox/messagesMessages 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
| Name | In | Type | Description |
|---|---|---|---|
folder | query | string | |
search | query | string | |
q | query | string | |
unread | query | boolean | |
starred | query | boolean | |
label | query | string | |
attachments | query | boolean | |
mentioned | query | boolean | |
limit | query | integer | |
offset | query | integer |
Request
GET
/api/v1/mailbox/messagescurl -X GET 'https://courier.mailyte.com/api/v1/mailbox/messages' \
-H 'Authorization: Bearer MAILBOX_TOKEN'const response = await fetch('https://courier.mailyte.com/api/v1/mailbox/messages', {
method: 'GET',
headers: {
Authorization: 'Bearer MAILBOX_TOKEN',
},
});
const { data } = await response.json();import requests
response = requests.get(
"https://courier.mailyte.com/api/v1/mailbox/messages",
headers={"Authorization": "Bearer MAILBOX_TOKEN"},
)
data = response.json()["data"]<?php
$response = Http::withToken('MAILBOX_TOKEN')
->get('https://courier.mailyte.com/api/v1/mailbox/messages');
$data = $response->json('data');require "net/http"
require "json"
uri = URI("https://courier.mailyte.com/api/v1/mailbox/messages")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer MAILBOX_TOKEN"
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }Response
Successful Response
dataobjectmessagesarray<object>idstringThis message's id:
folder:uid, e.g.INBOX:4821. Use it in every per-message call.folderstringsubjectstringfromarray<object>namestring or nullemailstringrequired
toarray<object>namestring or nullemailstringrequired
ccarray<object>namestring or nullemailstringrequired
received_atstring or nullISO 8601 with offset.
sizeintegerBytes.
has_attachmentbooleanis_readbooleanis_starredbooleanis_answeredbooleanis_draftbooleankeywordsarray<string>Labels on this message.
previewstring or nullThe first line or two of text.
thread_idstring or nullmessage_idstring or nullThe RFC 5322 Message-ID header.
totalintegerMatching messages in all pages.
offsetintegerlimitintegerhas_moreboolean
200
application/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
| 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. |
422 | Validation Error |
Every status, with what causes it and what to do, is on the error reference.