Search

Search finds messages within a mailbox by full-text query and by sender, subject, or date. It runs against SpiderMail's stored copy of your mail — including the extracted text of attachments — so you can find an email by something that was inside a PDF, not just in the body.

Search a mailbox

GET /mail/search requires the mailbox email, plus any combination of filters:

curl -G "https://spideriq.ai/api/v1/mail/search" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "email=alice@yourcompany.com" \
  --data-urlencode "q=pricing proposal" \
  --data-urlencode "from_addr=bob@example.com" \
  --data-urlencode "since=2026-05-01"

The filters:

• email (required) — the mailbox to search.

• q — full-text query across subject and body.

• from_addr — match the sender (substring).

• subject — match the subject (substring).

• since / before — restrict to a date range (ISO 8601, e.g. 2026-05-01).

All supplied filters combine — the example above finds messages in Alice's mailbox from Bob, mentioning "pricing proposal", since May 1.

Note: Search is scoped to a single mailbox — email is required. To look across every mailbox, run the search per mailbox, or use a Master Inbox listing with filters for a unified view.

From an agent

The search_mail MCP tool searches across mailboxes with a query plus optional from, to, mailbox, date_from, and date_to filters. See MCP Tools.

Next steps

1. Organize results with labels and views.

2. Open and act on a message.

3. Search params in the API Reference.