---
title: "Cross-Mailbox Search API: What to Look For in 2026"
description: "How a cross-mailbox search API works, from IMAP's multimailbox extension to EWS filters, plus what to check on scope, limits and isolation before you pick one."
canonical: "https://myagent.mx/blog/cross-mailbox-search-api"
publishedAt: "2026-10-27T00:00:00.000Z"
updatedAt: "2026-10-27T23:08:56.067Z"
category: "apis"
topic: "cross mailbox search"
author: "Roshan Jonnalagadda"
authorProfile: "https://myagent.mx/blog/author/roshan-jonnalagadda"
keywords:
  - "cross mailbox search"
  - "cross mailbox search api"
  - "best email search api"
  - "email search api"
  - "multi mailbox search"
---

# Cross-Mailbox Search API: What to Look For in 2026

How a cross-mailbox search API works, from IMAP's multimailbox extension to EWS filters, plus what to check on scope, limits and isolation before you pick one.

![Engineer testing a cross-mailbox search API](/images/blog/cross-mailbox-search-api/hero.svg)

A cross-mailbox search API lets you run one query against many mailboxes and get back one result set that says which mailbox each message came from. A single-mailbox search asks "what is in this inbox?" and a cross-mailbox search asks "where, across all of these inboxes, is the message about invoice 4417?" For an AI agent, a support tool or a multi-tenant SaaS product, that difference decides whether you write one request or a loop of hundreds.

This guide explains how cross-mailbox search works at the protocol level, what the common APIs expose, which questions to ask about permissions and limits, and how isolation fits in when each customer or agent has its own inbox.

## TL;DR

- Cross-mailbox search runs one query over several mailboxes and labels each hit with its source mailbox. Plain IMAP SEARCH only covers the one mailbox you have selected.
- Compare APIs on mailbox scope, permissions required, filter inputs, returned fields and result limits. Servers are allowed to cap the search or return partial results.
- In a multi-tenant product, the search scope should be set by the credential, not by a parameter your own code has to remember to add.
- Sendmux gives agents and platforms real mailboxes with mailbox-scoped search, per-mailbox credentials and structured JSON responses. Searching several mailboxes requires a separate request for each mailbox.

## Table of Contents

- [Single-mailbox search versus cross-mailbox search](#single-mailbox-search-versus-cross-mailbox-search)
- [How the APIs you already know handle it](#how-the-apis-you-already-know-handle-it)
- [What a good cross-mailbox search API returns](#what-a-good-cross-mailbox-search-api-returns)
- [Threading changes what "a result" means](#threading-changes-what-a-result-means)
- [Isolation: the part most guides skip](#isolation-the-part-most-guides-skip)
- [Where Sendmux fits](#where-sendmux-fits)
- [Our perspective](#our-perspective)
- [Try an agent mailbox with search](#try-an-agent-mailbox-with-search)
- [How to choose: a short decision path](#how-to-choose-a-short-decision-path)
- [A worked example](#a-worked-example)
- [Common mistakes](#common-mistakes)
- [FAQ](#faq)
- [Sources](#sources)

## Single-mailbox search versus cross-mailbox search

Most email search you have used is single-mailbox. You open an account, pick a folder, type a query. IMAP works the same way: the SEARCH command [operates only on the currently selected mailbox](https://www.rfc-editor.org/rfc/rfc7377.html). To look through five folders, a client has to SELECT one, run SEARCH, wait, then repeat for the next.

That pattern is fine for a person. It is painful for software that needs an answer across a team, a tenant or a fleet of agents. Every extra mailbox is another round trip, and selecting a mailbox changes the connection's state, which can disturb whatever the client had open.

RFC 7377, published in October 2014, addresses this with the IMAP4 Multimailbox SEARCH extension. A client can [search multiple mailboxes with a single command](https://www.rfc-editor.org/rfc/rfc7377.html). The server identifies the mailbox in its responses, so you know where each match lives. The RFC also notes that doing it in one command cuts the round trips and gives the server room to optimise the search.

The same idea shows up in HTTP APIs, with different names. Whatever the transport, a cross-mailbox search has three parts:

1. A **scope**: which mailboxes to search (all, a named list, or those a credential can reach).
2. A **filter**: sender, subject, date range, label, text, attachment status.
3. A **result shape**: matching messages, each tagged with its source mailbox, usually with a cap on how many come back.

## How the APIs you already know handle it

The providers that dominate business email each take a different route, and the differences are useful when you are deciding what your own product should offer.

### Gmail: one user at a time

The Gmail API supports rich search, but per user. Its `messages.list` and `threads.list` methods accept a `q` parameter that [supports most of the same advanced search syntax as the Gmail web interface](https://developers.google.com/workspace/gmail/api/guides/filtering), so you can filter by sender, date or label. The scope, though, is the authorised account. To search ten accounts you make ten authorised calls and merge the results yourself. That is workable for a handful of connected accounts and becomes a chore, and a cost, at scale.

### Exchange Web Services: scope as a parameter, permissions as a gate

The EWS integration documented by [Cortex XSOAR](https://xsoar.pan.dev/docs/reference/integrations/ews-v2) is a clear illustration of the API shape. A cross-mailbox operation takes a filter plus either a mailbox scope or a list of email addresses. A single-mailbox operation, by contrast, targets a folder in one mailbox and applies a query there.

The documented cross-mailbox call has a few features worth borrowing as a checklist:

- A **maximum result count**, with a default of 250.
- **Returned fields** including item ID, source mailbox, subject, recipients, sender, attachment status, sent time and received time.
- A **permission requirement**: searching across mailboxes needs eDiscovery permissions, while other operations on a target mailbox may need impersonation or delegation access.

Notice what that means in practice. The search is powerful, so the permission is heavy. A compliance officer should hold it. An application component that only needs to find one customer's reply should not.

## What a good cross-mailbox search API returns

When you evaluate an email search API, look past "it supports search" and check the following.

| Question | Why it matters |
|---|---|
| What is the scope model? | All mailboxes, a list, or only what the credential can see. This decides how safe the API is to expose to an agent. |
| What permission does a search need? | Broad permissions on a general-purpose key are a risk. |
| Which filters exist? | Sender, recipient, subject, date range, body text, attachment, label or thread. |
| What does a hit contain? | Message ID, source mailbox, sender, recipients, subject, timestamps, attachment flag, ideally a thread identifier. |
| What is the result limit? | EWS defaults to 250. Find out whether you can page past it. |
| Is the result complete? | RFC 7377 says servers [may limit the mailboxes or messages searched or return partial results](https://www.rfc-editor.org/rfc/rfc7377.html). Your code should handle that case. |
| How fresh is the index? | New mail should be searchable within seconds if an agent is waiting on a reply. |
| How is it priced? | Per query, per mailbox, per connected account, or bundled with usage. |

The partial-results point deserves emphasis. A search that silently truncates is worse than one that fails, because an agent will conclude "no such email exists" when the truth is "the server stopped looking". Build your agent so it checks for truncation flags and narrows the filter or pages on, rather than treating an empty or capped list as final.

## Threading changes what "a result" means

For support, sales and scheduling agents, the unit you want is rarely a single message. It is the conversation. If a search returns twelve messages from one thread, the agent has to work out that they are one exchange before it can decide what to do.

So ask whether the API can return threads, whether replies stay linked to the original sent message, and whether the thread view works across mailboxes when several of your agents were copied on the same conversation. Sales tools that need reply threading and inbound routing feel this first, because a reply that lands in the wrong thread breaks follow-up logic.

There is a useful practical lesson here from outside agent tooling. Teams that pilot email parsing on real inboxes, such as [piloting email parsing on real inboxes](https://freightsuite.com/blog/email-parsing-logistics) in logistics operations, find quickly that the gap between searching one mailbox and searching across several comes down to correlating messages and keeping requests moving without waiting for each one to finish. The same two concerns, correlation and pipelining, are what a good API hides from you.

## Isolation: the part most guides skip

Search across mailboxes sounds like the opposite of isolation. In a multi-tenant product it needs to be both: broad for you, narrow for each customer.

The pattern that works is to separate two kinds of credential:

- **Platform-level credentials** that can search across all of your tenants' mailboxes, held by your backend, used for admin tools, support and audit.
- **Mailbox-scoped credentials** that can see exactly one mailbox and nothing else, handed to an agent or a tenant-facing feature.

With the second kind, "cross-mailbox" for that agent is just "its own mailbox", and the API cannot return another tenant's mail even if the agent is prompted into trying. That is a stronger guarantee than a `tenant_id` filter your own code must remember to add on every query. An injected prompt can change what an agent asks for. It cannot change what its key is allowed to see.

Compare this with the EWS model above. Impersonation and eDiscovery grant wide reach to a service account, which suits a security team and suits an AI agent badly. For agents, you want least privilege by default and wide reach only on a deliberate, logged path.

Whatever you choose, check for per-key logs. When a search touches several mailboxes, you want a record of which key ran it, over what scope, and when.

## Where Sendmux fits

Sendmux is email API infrastructure for AI agents and platforms. Each agent or tenant can use a real mailbox, on a shared @myagent.mx address or on your own domain, with HTTP API access and SMTP submission for manual mailbox credentials. Several features line up with the checklist above:

- **Mailbox-scoped search** within one selected mailbox per request. A connected app with several granted mailboxes selects each mailbox separately and combines the results itself.
- **Per-mailbox API keys and permissions**, so an agent's credential covers its own mailbox and nothing more.
- **Structured JSON responses**, including search snippets and thread metadata that an agent can read without fetching raw MIME.
- **Live notifications** through SSE or webhooks, so your system can learn about new mail without polling and then fetch it through the API.
- **Delivery logs and metrics**, for inspecting message-level sending activity and delivery outcomes.

For a deeper walk through the RFC, command-line and API options, see our [cross-mailbox search guide](https://sendmux.ai/blog/email-deliverability/cross-mailbox-search), and for the wider mailbox model, the [mailbox API guide](https://sendmux.ai/blog/email-deliverability/mailbox-api).

## Our perspective

We build for the moment when you have more agents than anyone can watch. At that point, search stops being a convenience and becomes the way you understand what your system is doing: which agent answered which customer, which thread went quiet, which mailbox is full of bounces.

Three opinions guide how we think about it.

First, scope belongs to the credential. If an agent can only ever hold a key for its own mailbox, you do not have to trust its prompt to keep tenants apart. Wide search is a platform capability, kept on your server, not something you hand to an agent.

Second, a mailbox should persist. Many email APIs treat inbound mail as an event to forward and forget. A search API is only as good as the mail that is still there to find, so we keep mailbox state and let you search it, thread it and read it back later.

Third, pricing should not punish you for isolation. Giving every tenant its own inbox is good design, and a per-inbox or per-seat fee turns good design into a cost line. 

We would rather tell you plainly where a pre-claim agent mailbox stops than oversell it. A mailbox that an agent registers on its own can receive, read, search and thread mail once registration is active, but it cannot send until a human owner accepts the invitation and explicitly approves sending. We think that is the right default: the person whose name the mail goes out under stays in control of what leaves.

## Try an agent mailbox with search

If you want to see how an agent behaves with a real inbox, myagent.mx lets an agent register its own @myagent.mx inbox without a human signup form or an existing Sendmux API key. Once registration is active, the mailbox can receive, read, search and thread mail; sending requires owner acceptance, explicit approval and a separate short-lived sending token. Start at [myagent.mx](https://myagent.mx/), or look at the [inbox API product page](https://sendmux.ai/product/inboxes) for the full developer picture.

## How to choose: a short decision path

1. **Decide who searches.** If only your backend does, a platform-wide search with a strong admin credential is fine. If agents or tenants do, insist on mailbox-scoped keys.
2. **List the filters your agent needs.** Sender, date range, thread and attachment cover most support and scheduling work.
3. **Check the limits.** Find the default result cap, how paging works, and what the API does when a search is truncated.
4. **Test freshness.** Send a message and time how long until a search finds it. Agents that wait on replies need seconds, not minutes.
5. **Model the cost at your real mailbox count.** Per-connected-account or per-seat pricing can dominate once you reach hundreds of tenants.
6. **Read the logs.** Run a few searches and confirm you can see who ran them.

If you are comparing vendors as you go, our write-ups on [agent mailbox alternatives](https://sendmux.ai/blog/email-deliverability/agentmail-alternatives) and [Resend alternatives for AI agent mailboxes](https://sendmux.ai/blog/email-deliverability/resend-alternatives) set out the same criteria side by side.

## A worked example

Imagine a platform with 400 customer workspaces, each with a support agent and its own mailbox. A customer writes in: "I never got a reply to my refund request last week."

With a per-account API, your support tool would need to find that customer's mailbox, authorise against it, run a query and read the thread. If the refund request was copied to a finance agent, that is a second account and a second call.

With a cross-mailbox search, the backend sends one query: sender is the customer's address, date range is the last fourteen days, scope is the two mailboxes involved. Each hit comes back tagged with its source mailbox, subject, timestamps and thread. Your tool sees at once that the support agent received the request, the finance agent was copied, and nobody replied. One request, one answer, one log entry.

![One query searches two mailboxes and returns tagged results](/images/blog/cross-mailbox-search-api/image-2.svg)

Now the customer-facing side. The support agent itself runs on a key scoped to its own mailbox. If it searches for "refund", it sees only its own mail. That is exactly what you want.

## Common mistakes

- **Treating an empty result as proof.** Check for truncation and partial-result signals first.
- **Using one all-powerful key for every agent.** It is convenient on day one and a liability by day thirty.
- **Searching by subject only.** Subjects change on replies and forwards. Use thread identifiers and sender plus date where you can.
- **Ignoring pagination.** A default cap of a few hundred is easy to hit on a busy mailbox.
- **Polling for new mail** when webhooks or server-sent events can push it to you.

## FAQ

### What is a cross-mailbox search API?

It is an API that searches several mailboxes in one request and reports which mailbox each match came from. IMAP's multimailbox extension (RFC 7377) defines this for IMAP, and HTTP email APIs offer the same idea with their own endpoints. It saves you from selecting and searching each mailbox in turn.

### Is there a limit to how many results I can get back?

Usually, yes. The EWS cross-mailbox operation documented by Cortex XSOAR defaults to 250 results, and RFC 7377 lets servers limit the mailboxes or messages searched or return partial results. Check your provider's cap and design your agent to page or narrow the filter.

### Can I search across mailboxes without giving an agent broad access?

Yes, if the search runs on your backend with a platform-level credential while agents use keys scoped to a single mailbox. The agent then cannot see other tenants' mail, whatever it is asked to do. Sendmux supports per-mailbox API keys and permissions for this reason.

### Does the Gmail API search several accounts at once?

No. The Gmail API searches the authorised user's mailbox with a query that mirrors the web interface's syntax. To cover several accounts you authorise and query each one, then merge the results yourself.

### Can a self-registered agent send email from its myagent.mx mailbox?

Not straight away. A durable read token covers reading and receiving mail, including search and threading. Sending requires the human owner to accept the invitation and explicitly approve it. The durable read token remains unchanged; it is used to obtain a separate one-hour sending token.

## Sources

- [RFC 7377: IMAP4 Multimailbox SEARCH Extension](https://www.rfc-editor.org/rfc/rfc7377.html)
- [EWS v2 integration reference, Cortex XSOAR](https://xsoar.pan.dev/docs/reference/integrations/ews-v2)
- [Search and filter messages, Gmail API guide](https://developers.google.com/workspace/gmail/api/guides/filtering)

## Recommended

- [Best Mailbox Migration Tools for Developers](https://sendmux.ai/blog/email-deliverability/best-mailbox-migration-tools)
- [Cross-Mailbox Search: RFC, CLI and API Guide](https://sendmux.ai/blog/email-deliverability/cross-mailbox-search)
- [Mailbox API Guide for Agent-Scale Email](https://sendmux.ai/blog/email-deliverability/mailbox-api)