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, including Gmail and Outlook. If an account is missing, follow the Gmail connection instructions or Microsoft mailbox connection instructions 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.
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.
- Check the connected accounts. Call
GET /mailboxesand inspectprovider,status,error,last_sync_at, andgroup_idfor the relevant accounts. Use these fields to review their connection state, synchronization, and group membership. - Choose one useful clue. Start with a distinctive project name or delivery reference rather than a generic word such as “update.”
- Search across connected mailboxes. Call
GET /messages/searchwithq. Leave out optional narrowing filters for the first request. - 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.
- 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.
The API exposes the following filters. Check accepted value formats in the Mailera API documentation 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:
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:
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:
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 says standard search excludes Spam and Trash. In Gmail, use in:anywhere to include those locations, as described in Google’s search operator reference. 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. For choosing tools by task, see Mailera’s MCP tools, task by task.
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 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
