/mail/list

GET

Retrieve a paginated list of emails from a specific mailbox folder.

GET /api/mail/list

Description

The /mail/list endpoint allows you to retrieve a paginated list of emails from a specified folder (inbox, sent, drafts, or trash). This endpoint supports filtering, pagination, and returns email metadata for efficient list display.

Pagination

Use the limit and offset parameters to implement efficient pagination. The response includes total_count to help calculate the total number of pages available.

Query Parameters

Parameter Type Required Description
folder string Yes The mailbox folder to list emails from. Valid values: inbox, sent, drafts, trash.
limit integer No Maximum number of emails to return per page. Range: 1-100. Default: 50.
offset integer No Number of emails to skip before starting to return results. Default: 0.

Response

Returns a JSON object containing the folder name, array of email metadata, and pagination information.

Response Properties

folder string
The name of the folder that was queried.
emails array of objects
An array of email metadata objects. Each object contains: id, from, to, subject, timestamp, is_read, has_attachments.
total_count integer
Total number of emails in the folder.
limit integer
The limit value used for this request.
offset integer
The offset value used for this request.

Example Response

{
  "folder": "inbox",
  "emails": [
    {
      "id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
      "from": "[email protected]",
      "to": "[email protected]",
      "subject": "Meeting reminder",
      "timestamp": "2025-12-20T14:30:00Z",
      "is_read": false,
      "has_attachments": true
    },
    {
      "id": "b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7",
      "from": "[email protected]",
      "to": "[email protected]",
      "subject": "Project update",
      "timestamp": "2025-12-20T10:15:00Z",
      "is_read": true,
      "has_attachments": false
    }
  ],
  "total_count": 127,
  "limit": 50,
  "offset": 0
}

Try It Out

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

Examples

JavaScript (async/await)

const API_BASE = 'http://localhost:8080/api';

async function listInboxEmails() {
    try {
        const params = new URLSearchParams({
            folder: 'inbox',
            limit: 50,
            offset: 0
        });

        const response = await fetch(`${API_BASE}/mail/list?${params}`);
        const data = await response.json();

        console.log(`Total emails in ${data.folder}: ${data.total_count}`);
        console.log(`Showing ${data.emails.length} emails`);

        data.emails.forEach(email => {
            console.log(`[${email.is_read ? 'Read' : 'Unread'}] ${email.subject} - from ${email.from}`);
        });
    } catch (error) {
        console.error('Error fetching emails:', error);
    }
}

listInboxEmails();

cURL

curl -X GET "http://localhost:8080/api/mail/list?folder=inbox&limit=50&offset=0" \
  -H "Accept: application/json"

Python

import requests

API_BASE = 'http://localhost:8080/api'

def list_inbox_emails(limit=50, offset=0):
    params = {
        'folder': 'inbox',
        'limit': limit,
        'offset': offset
    }

    response = requests.get(f'{API_BASE}/mail/list', params=params)
    data = response.json()

    print(f"Total emails in {data['folder']}: {data['total_count']}")
    print(f"Showing {len(data['emails'])} emails")

    for email in data['emails']:
        status = 'Read' if email['is_read'] else 'Unread'
        print(f"[{status}] {email['subject']} - from {email['from']}")

list_inbox_emails()