/api/qmail/inbox
GETRetrieve a paginated list of emails from a specified folder with unread counts.
Description
The /api/qmail/inbox endpoint retrieves a paginated list of emails from a specified folder. By default it returns the inbox (folder 0), but you can query sent (1), drafts (2), trash (3), starred (4), or archive (5) as well. The response includes email metadata, pagination information, and a global unread count across all folders.
Use the limit and offset parameters to implement efficient pagination. The response includes total_in_folder to help calculate the total number of pages available. Maximum of 200 results per request.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
folder |
integer | No | Folder ID to list emails from. 0 = Inbox (default), 1 = Sent, 2 = Drafts, 3 = Trash, 4 = Starred, 5 = Archive. |
limit |
integer | No | Maximum number of emails to return per page. Range: 1-200. Default: 50. |
offset |
integer | No | Number of emails to skip before starting to return results. Default: 0. |
Response
Returns a JSON object containing the email list, pagination metadata, folder totals, and a global unread count.
Response Properties
true on success.Email Object Properties
Example Response
{
"success": true,
"count": 2,
"folder": 0,
"limit": 50,
"offset": 0,
"total_in_folder": 127,
"unread_count": 14,
"emails": [
{
"email_id": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
"subject": "Q4 Budget Report",
"sender_sn": 1048576,
"received_timestamp": 1739453400,
"is_read": false,
"is_starred": true,
"folder": 0,
"body_preview": "Hi team, please find attached the Q4 budget report for your review. Let me know if you have any questions or need additional details about the projected figures..."
},
{
"email_id": "b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
"subject": "Meeting Tomorrow",
"sender_sn": 2097152,
"received_timestamp": 1739438100,
"is_read": true,
"is_starred": false,
"folder": 0,
"body_preview": "Just a reminder that we have a team sync scheduled for tomorrow at 10 AM. Please prepare your status updates and any blockers you would like to discuss..."
}
]
}
Try It Out
Examples
cURL
# List inbox emails (default folder)
curl -X GET "http://localhost:8080/api/qmail/inbox" \
-H "Accept: application/json"
# List inbox with pagination
curl -X GET "http://localhost:8080/api/qmail/inbox?folder=0&limit=20&offset=0" \
-H "Accept: application/json"
# List sent folder
curl -X GET "http://localhost:8080/api/qmail/inbox?folder=1&limit=50&offset=0" \
-H "Accept: application/json"
# List trash folder, page 2
curl -X GET "http://localhost:8080/api/qmail/inbox?folder=3&limit=50&offset=50" \
-H "Accept: application/json"
JavaScript (async/await)
const API_BASE = 'http://localhost:8080/api';
const FOLDERS = { 0: 'Inbox', 1: 'Sent', 2: 'Drafts', 3: 'Trash', 4: 'Starred', 5: 'Archive' };
async function listInbox(folder = 0, limit = 50, offset = 0) {
try {
const params = new URLSearchParams({
folder: folder,
limit: limit,
offset: offset
});
const response = await fetch(`${API_BASE}/qmail/inbox?${params}`);
const data = await response.json();
if (data.success) {
console.log(`Folder: ${FOLDERS[data.folder]}`);
console.log(`Showing ${data.count} of ${data.total_in_folder} emails`);
console.log(`Unread across all folders: ${data.unread_count}`);
data.emails.forEach(email => {
const status = email.is_read ? 'Read' : 'UNREAD';
const star = email.is_starred ? ' *' : '';
console.log(`[${status}${star}] ${email.subject} (SN: ${email.sender_sn})`);
console.log(` Preview: ${email.body_preview}`);
});
} else {
console.error('Request failed:', data.message);
}
return data;
} catch (error) {
console.error('Error fetching inbox:', error);
}
}
// List inbox
listInbox();
// List sent folder, page 2
// listInbox(1, 50, 50);
Python
import requests
API_BASE = 'http://localhost:8080/api'
FOLDERS = {0: 'Inbox', 1: 'Sent', 2: 'Drafts', 3: 'Trash', 4: 'Starred', 5: 'Archive'}
def list_inbox(folder=0, limit=50, offset=0):
"""Retrieve a paginated list of emails from a folder."""
params = {
'folder': folder,
'limit': limit,
'offset': offset
}
response = requests.get(f'{API_BASE}/qmail/inbox', params=params)
data = response.json()
if data.get('success'):
print(f"Folder: {FOLDERS.get(data['folder'], 'Unknown')}")
print(f"Showing {data['count']} of {data['total_in_folder']} emails")
print(f"Unread across all folders: {data['unread_count']}")
for email in data['emails']:
status = 'Read' if email['is_read'] else 'UNREAD'
star = ' *' if email['is_starred'] else ''
print(f"[{status}{star}] {email['subject']} (SN: {email['sender_sn']})")
print(f" Preview: {email['body_preview']}")
else:
print(f"Request failed: {data.get('message')}")
return data
# List inbox
list_inbox()
# List sent folder, page 2
# list_inbox(folder=1, limit=50, offset=50)
Related Endpoints
/api/qmail/download
Download new emails from the RAIDA network before listing them in the inbox.
/api/qmail/read
Get full details for a specific email by its email_id from the inbox listing.