Search

MoMail’s search API uses vector embeddings to enable semantic search. Find emails by meaning, not just keywords.

Search Emails

Perform a semantic search across your emails.

POST /search

Request Body

{
  "query": "Q4 budget discussions from Sarah",
  "domain": "example.com",
  "limit": 20,
  "offset": 0
}

Parameters

Field	Type	Required	Description
query	string	Yes	Natural language search query
domain	string	No	Filter by specific domain
limit	number	No	Maximum results (1-100, default: 20)
offset	number	No	Results to skip (for pagination)

Response

{
  "success": true,
  "data": [
    {
      "email_id": "msg_abc123",
      "subject": "Q4 Budget Review - Action Required",
      "from": "sarah@example.com",
      "date": "2024-01-15T10:30:00.000Z",
      "snippet": "Hi team, I wanted to discuss our Q4 budget allocation...",
      "score": 0.92
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 45,
    "hasMore": true
  }
}

Response Fields

Field	Type	Description
email_id	string	Unique email identifier
subject	string	Email subject line
from	string	Sender email address
date	string	ISO 8601 timestamp
snippet	string	Preview of email body (first 200 characters)
score	number	Similarity score (0-1, higher is better)

Search Suggestions

Get autocomplete suggestions for search queries.

GET /search/suggestions?q={query}

Parameters

Parameter	Type	Required	Description
q	string	Yes	Partial search query

Response

{
  "success": true,
  "data": [
    "budget Q4",
    "budget review",
    "budget meeting",
    "budget allocation"
  ]
}

Search Query Examples

MoMail’s semantic search understands natural language:

Query	Finds emails about…
“invoices from last month”	Invoices received recently
”meeting notes with the design team”	Meeting summaries and notes
”urgent issues requiring attention”	High-priority problems
”project delays and timeline updates”	Schedule changes
”feedback on the proposal”	Reviews and comments

Understanding Scores

The score field indicates how relevant each result is:

Score	Relevance
0.90-1.00	Highly relevant
0.70-0.89	Very relevant
0.50-0.69	Moderately relevant
0.30-0.49	Somewhat relevant
Below 0.30	Weak match

Rate Limits

Search endpoints have specific rate limits:

Plan	Searches per Minute
Free	10
Pro	60
Enterprise	300

Code Examples

cURL

# Search emails
curl -X POST https://api.momail.io/v1/search \
  -H "X-API-Key: your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Q4 budget discussions",
    "limit": 10
  }'

# Get suggestions
curl "https://api.momail.io/v1/search/suggestions?q=budget" \
  -H "X-API-Key: your_key"

JavaScript

// Search emails
const results = await fetch('https://api.momail.io/v1/search', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: 'Q4 budget discussions',
    limit: 20
  })
}).then(r => r.json());

// Display results
results.data.forEach(email => {
  console.log(`${email.subject} (${email.score})`);
});

// Get suggestions
const suggestions = await fetch(
  'https://api.momail.io/v1/search/suggestions?q=budget',
  { headers: { 'X-API-Key': 'your_key' } }
).then(r => r.json());

Python

import requests

headers = {
    'X-API-Key': 'your_key',
    'Content-Type': 'application/json'
}

# Search emails
response = requests.post(
    'https://api.momail.io/v1/search',
    headers=headers,
    json={
        'query': 'Q4 budget discussions',
        'limit': 20
    }
)
results = response.json()['data']

for email in results:
    print(f"{email['subject']} (score: {email['score']})")

# Get suggestions
response = requests.get(
    'https://api.momail.io/v1/search/suggestions',
    headers={'X-API-Key': 'your_key'},
    params={'q': 'budget'}
)
suggestions = response.json()['data']

Advanced Search Tips

Combining Filters

While the basic search uses semantic matching, you can combine it with domain filtering:

{
  "query": "project updates",
  "domain": "company.com",
  "limit": 50
}

Pagination

For large result sets, use pagination:

async function searchAll(query) {
  const allResults = [];
  let offset = 0;
  const limit = 100;

  while (true) {
    const response = await fetch('https://api.momail.io/v1/search', {
      method: 'POST',
      headers: { 'X-API-Key': 'your_key', 'Content-Type': 'application/json' },
      body: JSON.stringify({ query, limit, offset })
    }).then(r => r.json());

    allResults.push(...response.data);

    if (!response.meta.hasMore) break;
    offset += limit;
  }

  return allResults;
}