/api/qmail/search

GET

Full-text search across email subjects and bodies.

http://localhost:8080/api/qmail/search

Description

The /api/qmail/search endpoint performs a full-text search across the subject lines and body content of all emails in the mailbox. It returns matching emails with metadata and a short body preview, making it ideal for building search interfaces and filtering large mailboxes.

Search Scope

The search text is matched against both the subject and body fields of every email. Results are returned in reverse chronological order (newest first) and include a 200-character body preview for each match.

Query Parameters

Parameter Type Required Description
query string Yes The search text to find in email subjects and bodies.
limit integer No Maximum number of results to return. Range: 1-200. Default: 50.

Response

Returns a JSON object containing the search query, result count, and an array of matching email objects.

Response Properties

success boolean
Indicates whether the search completed successfully.
query string
The original search query echoed back.
count integer
Number of matching results returned.
results array<object>
Array of email objects matching the search query.
results[].email_id string
Unique email identifier (hex string).
results[].subject string
The email subject line.
results[].sender_sn integer
The sender's serial number.
results[].received_timestamp integer (int64)
Unix timestamp (in seconds) when the email was received.
results[].is_read boolean
Whether the email has been read.
results[].folder integer
Numeric folder identifier where the email resides.
results[].body_preview string
Preview of the email body (first 200 characters).

Success Response (200 OK)

{
  "success": true,
  "query": "meeting",
  "count": 2,
  "results": [
    {
      "email_id": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
      "subject": "Team Meeting Tomorrow",
      "sender_sn": 1234567,
      "received_timestamp": 1736952600,
      "is_read": false,
      "folder": 0,
      "body_preview": "Hi team, just a reminder that we have our weekly meeting tomorrow at 10am. Please bring your status updates and any blockers you want to discuss. The agenda includes project timeline review and..."
    },
    {
      "email_id": "b2c3d4e5f6071829304b5c6d7e8f90a1",
      "subject": "Re: Meeting Notes",
      "sender_sn": 7654321,
      "received_timestamp": 1736847300,
      "is_read": true,
      "folder": 0,
      "body_preview": "Here are the notes from yesterday's meeting as discussed. Action items have been assigned and deadlines are listed below. Please review and confirm your tasks by end of day Friday."
    }
  ]
}

Error Response (400 Bad Request)

{
  "success": false,
  "message": "Missing required parameter: query"
}

Error Response (500 Internal Server Error)

{
  "success": false,
  "message": "Search failed",
  "error": "server_error"
}

Try It Out

http://localhost:8080/api/qmail/search

Examples

cURL

# Basic search
curl "http://localhost:8080/api/qmail/search?query=meeting"

# Search with custom limit
curl "http://localhost:8080/api/qmail/search?query=invoice&limit=10"

# URL-encode spaces in the query
curl "http://localhost:8080/api/qmail/search?query=project%20update&limit=25"

# Pretty print the JSON response
curl "http://localhost:8080/api/qmail/search?query=meeting" | jq

JavaScript (async/await)

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

async function searchEmails(query, limit = 50) {
    try {
        const params = new URLSearchParams({
            query: query,
            limit: limit.toString()
        });

        const response = await fetch(`${API_BASE}/qmail/search?${params}`);

        if (!response.ok) {
            throw new Error(`HTTP error ${response.status}`);
        }

        const data = await response.json();

        console.log(`Search for "${data.query}" returned ${data.count} result(s)`);

        data.results.forEach(email => {
            const status = email.is_read ? 'Read' : 'Unread';
            console.log(`[${status}] ${email.subject}`);
            console.log(`  From SN: ${email.sender_sn}`);
            console.log(`  ID: ${email.email_id}`);
            console.log(`  Preview: ${email.body_preview}`);
        });

        return data;
    } catch (error) {
        console.error('Search failed:', error);
        throw error;
    }
}

// Example usage
searchEmails('meeting', 20);

Python

import requests

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

def search_emails(query, limit=50):
    """
    Search for emails by subject and body content.

    Args:
        query: Search text to match against subjects and bodies
        limit: Maximum results to return (1-200, default 50)

    Returns:
        Dictionary with success, query, count, and results
    """
    params = {
        'query': query,
        'limit': limit
    }

    response = requests.get(f'{API_BASE}/qmail/search', params=params)
    response.raise_for_status()

    data = response.json()

    print(f"Search for '{data['query']}' returned {data['count']} result(s)\n")

    for email in data['results']:
        status = 'Read' if email['is_read'] else 'Unread'
        print(f"[{status}] {email['subject']}")
        print(f"  From SN: {email['sender_sn']}")
        print(f"  ID: {email['email_id']}")
        print(f"  Folder: {email['folder']}")
        print(f"  Preview: {email['body_preview']}\n")

    return data

# Example usage
if __name__ == '__main__':
    results = search_emails('meeting', limit=20)