/api/data/emails/search

GET

Search for emails using FTS5 full-text search across subjects, bodies, sender, and recipient fields.

GET /api/data/emails/search

Description

The email search endpoint provides fast full-text search capabilities powered by SQLite's FTS5 extension. It searches across email subjects, message bodies, sender addresses, recipient addresses, and other text fields to find matching emails.

Fast Search with FTS5

This endpoint uses SQLite's FTS5 (Full-Text Search) engine for high-performance searching. Search queries support phrase matching with quotes, prefix matching with *, and Boolean operators (AND, OR, NOT).

Try it Out

Query Parameters

Parameter	Type	Required	Description
`q`	string	Yes	Search query string. Supports FTS5 syntax including phrase matching ("exact phrase"), prefix matching (word*), and Boolean operators (AND, OR, NOT).
`limit`	integer	No	Maximum number of results to return. Must be between 1 and 100. Default: 50.
`offset`	integer	No	Number of results to skip for pagination. Default: 0.

Response

Returns a JSON object containing the search query, results array, and pagination information.

Response Properties

query string

The original search query that was executed.

results array<object>

Array of email objects matching the search query. Each object contains EmailID, Subject, snippet (preview text), From, To, timestamp, and other email metadata.

count integer

Total number of results found (before limit/offset applied).

limit integer

The limit parameter used for this search.

offset integer

The offset parameter used for this search.

Example Response

{
  "query": "meeting",
  "results": [
    {
      "EmailID": 1234,
      "Subject": "Team Meeting Tomorrow",
      "snippet": "Don't forget about the team meeting tomorrow at 10am...",
      "From": "[email protected]",
      "To": "[email protected]",
      "timestamp": "2025-12-20T14:30:00Z",
      "isRead": false,
      "hasAttachments": false
    },
    {
      "EmailID": 1189,
      "Subject": "Re: Meeting Notes",
      "snippet": "Here are the notes from yesterday's meeting as discussed...",
      "From": "[email protected]",
      "To": "[email protected]",
      "timestamp": "2025-12-19T09:15:00Z",
      "isRead": true,
      "hasAttachments": true
    }
  ],
  "count": 47,
  "limit": 50,
  "offset": 0
}

Search Query Syntax

The search supports advanced FTS5 syntax for precise queries:

Syntax	Example	Description
Simple terms	`meeting report`	Finds emails containing both "meeting" AND "report"
Phrase search	`"quarterly review"`	Finds the exact phrase "quarterly review"
Prefix matching	`meet*`	Finds "meeting", "meetings", "meet", etc.
OR operator	`urgent OR priority`	Finds emails with either "urgent" or "priority"
NOT operator	`meeting NOT cancelled`	Finds "meeting" but excludes "cancelled"

Examples

JavaScript (async/await)

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

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

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

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

        const data = await response.json();

        console.log(`Found ${data.count} emails matching "${query}"`);
        console.log(`Showing ${data.results.length} results`);

        data.results.forEach(email => {
            console.log(`[${email.EmailID}] ${email.Subject}`);
            console.log(`  From: ${email.From}`);
            console.log(`  Snippet: ${email.snippet}`);
        });

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

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

cURL

# Basic search
curl "http://localhost:8080/api/data/emails/search?q=meeting"

# Search with limit and offset for pagination
curl "http://localhost:8080/api/data/emails/search?q=urgent&limit=10&offset=0"

# Phrase search (URL encode the quotes)
curl "http://localhost:8080/api/data/emails/search?q=%22team%20meeting%22"

# Complex query with operators
curl "http://localhost:8080/api/data/emails/search?q=meeting%20OR%20conference&limit=25"

# Pretty print the JSON response
curl "http://localhost:8080/api/data/emails/search?q=invoice" | jq

Python

import requests
from typing import Dict, List, Optional

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

def search_emails(
    query: str,
    limit: int = 50,
    offset: int = 0
) -> Dict:
    """
    Search for emails using full-text search.

    Args:
        query: Search query string
        limit: Maximum results to return (1-100)
        offset: Number of results to skip

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

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

    data = response.json()

    print(f"Found {data['count']} emails matching '{query}'")
    print(f"Showing {len(data['results'])} results\n")

    for email in data['results']:
        print(f"[{email['EmailID']}] {email['Subject']}")
        print(f"  From: {email['From']}")
        print(f"  {email['snippet']}\n")

    return data

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

    # Pagination example
    if results['count'] > results['limit']:
        print(f"More results available. Fetching next page...")
        next_page = search_emails(
            'meeting',
            limit=20,
            offset=20
        )

Related Endpoints

Search Users

Search for users by name or description. Useful for recipient autocomplete functionality.

View Details

GET /api/data/emails

Retrieve emails with filtering and sorting options. Use this for browsing inbox/folders.