Cross-Inbox Search

Search emails across all inboxes by keyword, sender, date, and more.

Last updated 2026-03-29

LobsterMail provides full-text search across all your inboxes with a single API call. Search by keyword, filter by sender, direction, date range, or attachment presence.

How It Works#

Search uses PostgreSQL full-text search with weighted ranking:

Subject — highest weight (most relevant matches)
Sender address — medium weight
Body preview — lower weight (first ~200 characters of the email body)

Note: Only the body preview is searchable, not the full email body stored in S3. If you need to search full content, retrieve individual emails with getEmail().

SDK Usage#

const results = await lm.searchEmails({ q: 'invoice' });

for (const email of results.data) {
  console.log(`${email.subject} — from ${email.from}`);
}

Options#

Option	Type	Description
`q`	`string`	Required. Search query (e.g. `"invoice"`, `"verification code"`).
`inboxId`	`string`	Scope search to a single inbox.
`direction`	`'inbound' \| 'outbound'`	Filter by email direction.
`from`	`string`	Filter by sender address (partial match).
`since`	`string`	Only emails after this ISO 8601 timestamp.
`until`	`string`	Only emails before this ISO 8601 timestamp.
`hasAttachments`	`boolean`	Filter by attachment presence.
`limit`	`number`	Max results per page (1–50, default 20).
`cursor`	`string`	Pagination cursor from a previous response.

Filtering#

// Search a specific inbox
const results = await lm.searchEmails({
  q: 'receipt',
  inboxId: inbox.id,
});

// Filter by sender and date
const results = await lm.searchEmails({
  q: 'shipping confirmation',
  from: 'orders@',
  since: '2026-03-01T00:00:00Z',
});

// Only emails with attachments
const results = await lm.searchEmails({
  q: 'invoice',
  hasAttachments: true,
});

Pagination#

Use the cursor from the response to fetch the next page:

let cursor: string | undefined;
do {
  const results = await lm.searchEmails({ q: 'report', limit: 10, cursor });
  for (const email of results.data) {
    console.log(email.subject);
  }
  cursor = results.hasMore ? results.cursor ?? undefined : undefined;
} while (cursor);

REST API#

GET /v1/emails/search?q=invoice&from=billing@acme.com&limit=10

Returns { data: EmailSummary[], pagination: { hasMore, cursor } }.

MCP Tool#

search_emails(query: "invoice", from: "billing@")

Rate Limits#

Search is rate-limited to 30 requests per minute per account (separate from other endpoint limits).