Search messages
Tool ID: email_messages_search
Summary
Searches messages in a folder (by default the Inbox) using words that match subject, from, or body text. Returns a short list of matching messages so you can pick one to open fully.
When to use it
- Find mail about a topic — “shipping delay”, an invoice number, a person’s name.
- Recent mail — Leave the search empty to see recent messages in the folder.
- Before replying — Locate the right thread, then open it with Get message.
What you need
| Requirement | Required? |
|---|---|
| Metraclick connection | Yes |
| Tool enabled for your account | Yes |
| Email credentials | Yes |
Parameters
| Parameter | Required? | Description |
|---|---|---|
mailbox |
No | Account id. Omit for the default mailbox. |
folder |
No | Folder to search. Default: INBOX. |
query |
No | Search text. Empty means recent messages in that folder. |
limit |
No | Maximum results (up to 50). Default: 20. |
What you get back
| Field | Meaning |
|---|---|
mailbox, folder, query |
Echo of how the search ran |
count |
How many messages were returned |
messages |
Short summaries (including IMAP uid, subject, from, date, and similar) |
Use the uid from a result when you want to open or reply to that message.
Example prompts
Search our inbox for messages about “invoice 1042” and summarize what you find.
Show the 10 most recent emails in the default mailbox.
In the sales mailbox Sent folder, find messages to customer@example.com from last week.
Search the inbox for emails from Maria and list subjects only.
Tips
- Then open one — Search returns summaries. Ask to get the full message when you need the body.
- Limit — You can ask for “up to 50 results”; that is the hard maximum.
- Folder names — If search fails on Drafts/Sent, list folders first for the exact name.