Email Search

mails-agent provides three search modes that let your agent find emails by exact keywords, semantic meaning, or a combination of both. All search is scoped to the authenticated mailbox.

Search Modes

Keyword search (FTS5)

Full-text search powered by SQLite FTS5 in Cloudflare D1. Fast, exact matching on subject and body text. Best for finding emails containing specific terms, addresses, or identifiers.

Semantic search (Workers AI + Vectorize)

Embeds the query using Cloudflare Workers AI and searches against pre-computed email embeddings stored in Vectorize. Finds conceptually related emails even when exact keywords differ. For example, searching "payment confirmation" can match an email titled "Your order receipt".

Hybrid search (RRF fusion)

Combines keyword and semantic results using Reciprocal Rank Fusion (RRF). This mode runs both searches in parallel, merges the ranked result lists, and returns a unified ranking. This is the default mode for /v1/search and the recommended mode for most use cases. The /v1/inbox endpoint defaults to keyword mode.

Mode	Best for	Speed
`keyword`	Exact terms, email addresses, order IDs	Fastest (~10ms)
`semantic`	Conceptual search, natural language queries	Fast (~50ms)
`hybrid`	General purpose (default)	Fast (~60ms)

API Endpoints

GET/v1/inbox?query=xxx&mode=hybrid — Search via inbox endpoint

Add a query parameter to the inbox endpoint to search. The mode parameter selects the search strategy.

Query parameters

Parameter	Type	Default	Description
`query`	string	-	Search query (required for search)
`mode`	string	keyword	Search mode: `keyword`, `semantic`, or `hybrid`. Note: `/v1/search` defaults to `hybrid`.
`label`	string	-	Filter by auto-label (see below)
`limit`	number	20	Max results (max 100)
`offset`	number	0	Pagination offset

Example: Hybrid search

curl -s -H "Authorization: Bearer $API_KEY" \
  "https://mails-worker.genedai.workers.dev/v1/inbox?query=payment%20confirmation&mode=hybrid"

{
  "emails": [
    {
      "id": "msg_xyz789",
      "mailbox": "[email protected]",
      "from_address": "[email protected]",
      "from_name": "Stripe Billing",
      "subject": "Your payment receipt for March",
      "code": null,
      "direction": "inbound",
      "status": "received",
      "received_at": "2026-03-30T08:00:00Z",
      "has_attachments": false,
      "attachment_count": 0
    }
  ],
  "search_mode": "hybrid"
}

GET/v1/search?q=xxx — Dedicated search endpoint

An alias for search that defaults to hybrid mode. The q parameter is equivalent to query.

Example: Keyword-only search

curl -s -H "Authorization: Bearer $API_KEY" \
  "https://mails-worker.genedai.workers.dev/v1/search?q=invoice+INV-2026-001&mode=keyword"

Example: Semantic search

curl -s -H "Authorization: Bearer $API_KEY" \
  "https://mails-worker.genedai.workers.dev/v1/search?q=emails+about+project+deadlines&mode=semantic"

Auto-Labels

Every incoming email is automatically classified into one of four labels using a lightweight rules engine:

Label	Description	Examples
`newsletter`	Bulk marketing, digests, subscriptions	Weekly digest, product updates, blog roundups
`notification`	Automated transactional notifications	Order confirmations, shipping updates, billing receipts
`code`	Emails containing verification codes	2FA codes, signup verification, password resets
`personal`	Human-written messages	Direct correspondence, replies, introductions

Filter by label

# Get only verification code emails
curl -s -H "Authorization: Bearer $API_KEY" \
  "https://mails-worker.genedai.workers.dev/v1/inbox?label=code"

# Get only personal emails
curl -s -H "Authorization: Bearer $API_KEY" \
  "https://mails-worker.genedai.workers.dev/v1/inbox?label=personal"

# Combine label filter with search
curl -s -H "Authorization: Bearer $API_KEY" \
  "https://mails-worker.genedai.workers.dev/v1/inbox?query=github&label=notification"

Search Tips

Use keyword mode when you know the exact term (email address, order number, error code)
Use semantic mode for natural language queries ("emails about the Q1 budget review")
Use hybrid mode (default) when you are unsure -- it combines both strategies
Combine query with label to narrow results (e.g., search "github" within notification emails)
Semantic search requires embeddings to be generated. New emails are embedded within seconds of arrival.