/api/qmail/inbox

GET

Retrieve 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.

Pagination

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

success boolean
Always true on success.
count integer
The number of emails returned in this response.
folder integer
The folder ID that was queried (0=Inbox, 1=Sent, 2=Drafts, 3=Trash, 4=Starred, 5=Archive).
limit integer
The limit value used for this request.
offset integer
The offset value used for this request.
total_in_folder integer
Total number of emails in the queried folder.
unread_count integer
Total number of unread emails across all folders.
emails array of objects
An array of email summary objects. Each object contains the properties listed below.

Email Object Properties

email_id string
Hexadecimal identifier for the email.
subject string
The email subject line.
sender_sn integer
The serial number of the sender.
received_timestamp integer (int64)
Unix timestamp (in seconds) of when the email was received.
is_read boolean
Whether the email has been marked as read.
is_starred boolean
Whether the email has been starred/flagged by the user.
folder integer
The folder containing this email (0=Inbox, 1=Sent, 2=Drafts, 3=Trash, 4=Starred, 5=Archive).
body_preview string
A preview snippet of the email body (first 200 characters).

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

http://localhost:8080/api/qmail/inbox?folder=0&limit=50&offset=0

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.