Search

Find email by meaning, not just keywords. A search for “bill for the cargo boxes” finds an email about an “invoice for shipping containers”. Search covers only your own email.

Search email #

POST /v1/search

Returns the closest matching messages across all your inboxes, or within the filters you set. New email is searchable within seconds.

Body

query string required: What you are looking for, in plain words. Up to 2,000 characters.
inbox_id string: Only this inbox.
thread_id string: Only this thread.
direction string: in for received or out for sent email.
month string: Only this month, as YYYY-MM.
top_k integer: Number of results, 1–50. Default 10.

Results are ordered best match first. A lower score means a closer match.

curl

curl -X POST "$MAILA_API_URL/v1/search" \
  -H "Authorization: Bearer $MAILA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "bill for the cargo boxes",
    "inbox_id": "inb_mvdlh9c06724trm1",
    "top_k": 5
  }'

Response

{
  "object": "list",
  "data": [
    {
      "object": "search_result",
      "item_id": "msg_mvdliiuwzfsa7ngv",
      "thread_id": "thr_mvdlijmoxjmnbx5g",
      "inbox_id": "inb_mvdlh9c06724trm1",
      "subject": "Quarterly invoice attached",
      "from": "billing@example.com",
      "received_at": 1792335186,
      "snippet": "Please find the October invoice for the shipping containers attached.",
      "score": 0.516
    }
  ],
  "next_cursor": null
}