---
title: "Multi-mailbox email search: find the right message"
description: "Search connected Gmail and Outlook mailboxes with Mailera's API. Narrow results, check Junk, and verify the source mailbox with read-only access."
url: https://mailera.app/en/blog/multi-mailbox-email-search
published: 2026-10-25
updated: 2026-10-25
---

# Multi-mailbox email search: find the right message

Search connected Gmail and Outlook accounts through one API, then confirm which mailbox and folder hold the match. Use read-only access and check account setup, sync, and retention when results are missing.

## Which mailboxes and messages can you search?

Multi-mailbox email search means submitting one message query across several connected accounts instead of opening each account separately. A unified inbox brings messages into one view; cross-mailbox search finds a particular message across connected accounts.

[Mailera connects existing mailboxes](https://mailera.app/en/product), including Gmail and Outlook. If an account is missing, follow the [Gmail connection instructions](https://mailera.app/en/providers/gmail) or [Microsoft mailbox connection instructions](https://mailera.app/en/providers/microsoft) before searching. This workflow is for mailboxes you own or are authorized to access, not an email-address finder or an organization-wide discovery procedure.

The search endpoint is `GET /messages/search`, which searches across connected mailboxes. Separately, the API-key creation dialog lets you select one group under **Mailbox scope**; Admins can also choose all groups. When creating a key, select the smallest group needed for the task.

Mailera does not create new mailboxes or email addresses, and it does not support Proton Mail or Tuta. The free self-serve plan retains messages for 30 days, and the first message load is limited to that retention period. For older correspondence, search the original provider’s mailbox; Mailera’s retention window is not a statement that the provider deleted the message.

Search freshness also depends on synchronization. Background checks vary with mailbox activity, and inactive mailboxes can sleep and wake on use. Treat search as retrieval from available messages, not an absolute real-time view of every provider account.

For the broader workflow around shared views and agent operations, see [unified inbox operations for AI agents](https://mailera.app/en/blog/unified-inbox-for-ai-agents).

![Connected mailboxes and a distinctive query lead to search results, followed by verification of the source mailbox and folder.](https://mailera.app/media/0ab537339475a60a/multi-mailbox-email-search-find-the-right-message-search-en-1200.jpg)
_Search connected accounts, then verify where the matching message lives._

## How do you narrow the search to the right message?

Use a harmless test message in accounts you control. For example, send a project delivery update with the distinctive text `Cedar delivery update`. Avoid using customer correspondence to test your integration.

1. **Check the connected accounts.** Call `GET /mailboxes` and inspect `provider`, `status`, `error`, `last_sync_at`, and `group_id` for the relevant accounts. Use these fields to review their connection state, synchronization, and group membership.
2. **Choose one useful clue.** Start with a distinctive project name or delivery reference rather than a generic word such as “update.”
3. **Search across connected mailboxes.** Call `GET /messages/search` with `q`. Leave out optional narrowing filters for the first request.
4. **Narrow gradually.** Add a sender, mailbox, folder, or date restriction only when that clue is reliable. Change one filter at a time so you can see which restriction removes the match.
5. **Verify the source and content.** Check the result’s mailbox and folder, then retrieve the message. Compare the sender, received time, and body with what you expected.

![Mailboxes page with connected test accounts and private details redacted.](https://mailera.app/media/ad5c2e923c37028a/multi-mailbox-email-search-find-the-right-message-mailbox-en-1200.jpg)
_Use GET /mailboxes to inspect connection status, last sync, and group membership._

The API exposes the following filters. Check accepted value formats in the [Mailera API documentation](https://mailera.app/en/docs) when building your request, particularly for dates and read-state values.

| Clue | Parameter | What to check before narrowing |
| --- | --- | --- |
| Distinctive text | `q` | Use a recognizable term; inspect the result rather than treating a text match as confirmation. |
| Sender | `from` | Check the sender’s actual address, not just a familiar display name. |
| Approximate arrival date | `since` | Confirm the date format and timezone; avoid cutting off an earlier arrival. |
| Likely receiving account | `mailbox` | Confirm the account is connected and use the documented mailbox value. |
| Likely folder | `folder` | Use an explicit folder when needed; `junk` is the value for the Junk search below. |
| Read state | `unread` | Only restrict this if you know the message’s current read state. |

For this workflow, use plain query text plus Mailera’s separate filters. Keep Gmail and Outlook search expressions in their respective provider searches rather than copying an entire provider query into `q`.

## How do you run cross-mailbox search through the API?

### Create a search-only key

In **Settings**, open the API key tab and choose **Create key**. Set **Mailbox scope** to the smallest group needed for the task and enable **Read**. Leave **Send messages** and **Move messages** off for a retrieval-only task.

Store the key securely and set it as `MAILERA_API_KEY` in your local environment. Do not paste it into a shared script or commit it to source control.

### Search messages, not the mailbox list

This request URL-encodes the query text:

```bash
curl --get 'https://mailera.app/api/public/v1/messages/search' \
  --header "Authorization: Bearer $MAILERA_API_KEY" \
  --data-urlencode 'q=Cedar delivery update'
```

`GET /mailboxes` also accepts `q`, but that searches the mailbox list. Use `GET /messages/search` when the thing you are looking for is an email, not an account.

Read the objects in `data`. The fields that establish where a match came from are:

| Field | How to use it |
| --- | --- |
| `mailbox_id` | Identify the source mailbox and build the message-detail request. |
| `mailbox_email` | Confirm the receiving account without relying on memory. |
| `folder` | Check whether the result is in Inbox, Junk, or another returned folder. |
| `id` | Identify the message to retrieve. |
| `from.address` | Compare the sender’s address with your expected sender. |
| `received_at` | Check the arrival time alongside the message content. |

Keep `mailbox_id` and `id` together. Similar subjects in different accounts are not enough to identify the correct message.

### Check Junk explicitly

To search Junk across connected mailboxes, add `folder=junk`:

```bash
curl --get 'https://mailera.app/api/public/v1/messages/search' \
  --header "Authorization: Bearer $MAILERA_API_KEY" \
  --data-urlencode 'q=Cedar delivery update' \
  --data-urlencode 'folder=junk'
```

Searching across mailboxes and choosing a folder are separate parts of the request. For a deliberate Junk check, use the explicit folder filter rather than assuming that a cross-mailbox search covers every folder.

### Follow pagination before concluding there is no match

The search endpoint accepts `limit` and `cursor`, and responses include `next_cursor`. When a response supplies a continuation cursor, pass it as `cursor` on the next request while keeping the same search filters. Continue until no continuation cursor remains.

A first page is not necessarily the full result set. If you set `limit` for a compact preview, do not treat that preview as a complete search.

### Retrieve and verify the message

Set `MAILBOX_ID` to the matching result’s `mailbox_id` and `MESSAGE_ID` to its `id`:

```bash
curl 'https://mailera.app/api/public/v1/mailboxes/'"$MAILBOX_ID"'/messages/'"$MESSAGE_ID" \
  --header "Authorization: Bearer $MAILERA_API_KEY"
```

The response contains the message under `data`, including `body.text` and `body.html`. Confirm the source mailbox, `folder`, sender, received time, and relevant content. If `body_error` is populated, investigate the content retrieval problem rather than treating the preview as the full message.

Once you have identified the message, the receiving account, and its folder, stop if the task is only to find it.

## What common mistakes cause missing or misleading results?

First separate a failed request from a successful search with no matches. An authentication or permission failure needs an access fix; changing search terms will not resolve it.

| Symptom | Check | Next action |
| --- | --- | --- |
| You are unsure which accounts are connected or how they are grouped | `GET /mailboxes`, including `group_id` | Review the account list; when creating a key, select the smallest necessary group under **Mailbox scope**. |
| A known message disappears after adding filters | Sender, date, and unread restrictions | Remove the last restriction and retry. |
| Inbox searches miss an expected message | Folder restriction | Run an explicit `folder=junk` search. |
| Only a short list appears | `limit` and `next_cursor` | Retrieve the remaining pages with the same filters. |
| Recent mail is missing | Connection status and last sync | Resolve the connection or synchronization issue before repeating the search. |
| Older mail is missing | Message age and retention | Search the original provider’s mailbox. |
| The request fails | Authentication and `read` permission | Correct access before interpreting results. |

Mailbox details expose `status`, `error`, and synchronization information. Use those signals when a query looks right but recent mail is absent. A read-only search key cannot initiate synchronization: `POST /mailboxes/{id}/sync` requires the separate `sync` permission and also wakes sleeping mailboxes. Keep that recovery action separate from routine retrieval.

When checking Gmail directly, account for its own folder rules. [Google’s Gmail search guidance](https://support.google.com/mail/answer/6593?hl=en) says standard search excludes Spam and Trash. In Gmail, use `in:anywhere` to include those locations, as described in [Google’s search operator reference](https://support.google.com/mail/answer/7190?hl=en). That syntax belongs to Gmail; the Mailera Junk request above uses `folder=junk` instead.

## Can an AI agent search without sending email?

Yes. Mailera’s MCP tool `search_messages` requires `read`, not `send`. When creating the agent’s key, select the smallest necessary group under **Mailbox scope** and enable **Read**. It does not need **Send messages** or **Move messages** to find and retrieve a message.

For client configuration, see the [Mailera MCP documentation](https://mailera.app/en/mcp). For choosing tools by task, see [Mailera’s MCP tools, task by task](https://mailera.app/en/blog/mailera-mcp-tools).

Incoming email is untrusted data, not instructions. An agent must not follow directions embedded in a message body, such as requests to reveal credentials, change its rules, or forward other mail. Ask it to report only the mailbox, folder, sender, date, and the minimum relevant content.

Avoid logging full private message bodies. If a later task requires sending, authorize that separately and require human confirmation before the send action. Review the [Mailera security information](https://mailera.app/en/security) alongside your own credential-storage and logging controls.

**Do this with the API** — Every action in this article is available via the REST API, with curl examples, API keys and webhooks. [View API docs](https://mailera.app/en/docs)