Skip to main content
The GET /messages endpoint lets you search across every inbox in your workspace in one call. You choose the mode that fits your use case — exact keyword matching for speed, semantic similarity for meaning-aware results, or a hybrid blend for the best overall relevance.

​
Search modes

ModeHow it worksPlan
keywordFull-text search. Fast, exact-term matching.All plans
semanticVector similarity — finds messages by meaning, not just words.Pro and up
hybridWeighted blend of keyword + semantic. Best overall relevance.Pro and up
Pass query, mode, and an optional limit as query parameters:
cURL
curl "https://sentvia-api-production.up.railway.app/v1/messages?query=refund%20policy&mode=hybrid&limit=10" \
  -H "Authorization: Bearer sv_live_..."
The response includes a mode_used field confirming which mode actually ran, followed by a ranked messages array:
Response
{
  "mode_used": "hybrid",
  "messages": [
    {
      "id": "m_...",
      "subject": "Re: refund request",
      "from_addr": "jane@acme.com",
      "score": 0.91
    }
  ]
}

​
Notes

  • No query parameter — omit query entirely and the endpoint returns your most recent messages (mode_used: "recent").
  • Restrict to one inbox — add inbox_id to scope results to a single inbox instead of searching your entire workspace.
  • Plan fallback — on plans without semantic search, passing mode=semantic or mode=hybrid gracefully falls back to keyword. The mode_used field in the response always tells you exactly what ran.
Semantic search embeds message content automatically as mail arrives — there is nothing to index yourself. New messages are immediately searchable by meaning.