---
title: "Mailera MCP tools: choose the right tool and scope"
description: "Choose the right Mailera MCP tool to read, search, send, reply, move, or sync email. See required scopes, result checks, and agent safety guidance."
url: https://mailera.app/en/blog/mailera-mcp-tools
published: 2026-10-25
updated: 2026-10-25
---

# Mailera MCP tools: choose the right tool and scope

A task-first reference to Mailera’s 12 MCP tools, with scope requirements and checks to make before reading, moving, or sending email.

## Which Mailera MCP tool should you use?

Choose the tool by the action you want to allow, not just by what the agent could do. A message lookup needs `read`; it does not need permission to send a reply or move the result.

The [Mailera MCP server](https://mailera.app/en/mcp) connects AI clients to mailboxes you already use. Mailera does not create new mailboxes or email addresses. For the broader architecture, see [email for AI agents using existing mailboxes](https://mailera.app/en/blog/email-for-ai-agents).

The final column lists what to check after each tool call rather than assuming it succeeded.

| Task | MCP tool | Required scope | What to check afterward |
| --- | --- | --- | --- |
| Find a connected mailbox | `list_mailboxes` | `read` | You selected the intended mailbox. |
| Check mailbox sign-in status | `get_mailbox_status` | `read` | Whether the connection needs attention. |
| Browse messages in a mailbox folder | `list_messages` | `read` | The mailbox and folder match your task. |
| Find matching messages across mailboxes | `search_messages` | `read` | Each match belongs to the intended mailbox and conversation. |
| Retrieve a selected message’s content | `get_message` | `read` | The sender and content match the message you selected. |
| Retrieve a test verification code | `get_latest_otp` | `read` | It belongs to your own test account and current test. |
| Send a message | `send_email` | `send` | Inspect the attempt with `get_send_status`. |
| Reply to a message | `reply_to_email` | `send` | Inspect the attempt with `get_send_status`. |
| Check a send attempt | `get_send_status` | `send` | Read the reported outcome before considering a retry. |
| Move a selected message | `move_message` | `move` | Find the message in the intended destination. |
| Recover mail from Junk | `rescue_spam` | `move` | Check that only the intended messages were moved. |
| Request a mailbox refresh | `sync_mailbox` | `sync` | Recheck the mailbox and look for the expected message. |

`get_send_status` requires `send`, even though its job is to inspect an attempt. A read-only key is not sufficient for that tool.

## What do you need before calling a tool?

Set up the connection with the smallest permission set that can complete your task.

1. Connect an existing mailbox. Follow Connect your first mailbox to Mailera rather than trying to create a mailbox through MCP.
2. Choose **Create key**. Start with `read` and use **Mailbox scope** to restrict access to the mailboxes needed for the task.
3. Use **Copy MCP config** in the key-created view. Keep the copied configuration private; do not paste it into an agent conversation.
4. Configure Claude, Cursor, or VS Code. Use the [Mailera Claude integration guide](https://mailera.app/en/integrations/claude) or the [official VS Code MCP setup instructions](https://code.visualstudio.com/docs/agent-customization/mcp-servers) for your client.
5. Confirm that the client can discover tools and perform a mailbox lookup before granting additional scopes.

The MCP endpoint is `https://mailera.app/api/public/v1/mcp`. Use the copied configuration instead of constructing a client configuration from memory.

![Mailera API key settings showing scope selection and the Copy MCP config control, with secrets hidden.](https://mailera.app/media/a3498cc1b88e4af0/mailera-mcp-tools-choose-the-right-tool-and-scope-api-key-en-1200.jpg)
_Start with read access and keep the copied MCP configuration private._

MCP separates discovery from invocation. Clients use `tools/list` to discover tools and `tools/call` to invoke one. Each tool’s `inputSchema` describes its expected arguments; an `outputSchema` is optional. These mechanics are defined in the [official MCP tools specification](https://modelcontextprotocol.io/specification/2025-06-18/server/tools).

Use the schema your client discovers when supplying arguments. Do not turn REST query parameters into MCP arguments by copying their names from an API example. The [Mailera documentation](https://mailera.app/en/docs) covers the API separately.

## How do you find a mailbox and read the right message?

Use `list_messages` when you know which mailbox and folder to browse. Use `search_messages` when you need to locate matching mail across mailboxes. Use `get_message` when you have selected a message and need its content.

That separation helps avoid unnecessary reads. Finding a candidate message is not a reason to fetch every matching message body.

A read-only sequence looks like this:

1. Call `list_mailboxes` and select the intended mailbox. If the connection appears unhealthy, check it with `get_mailbox_status`.
2. Call `list_messages` to browse the relevant folder, or `search_messages` to find a match. Supply only arguments supported by the discovered tool schema.
3. Check the mailbox and message identity before proceeding. Do not choose a message solely because its subject looks familiar.
4. Call `get_message` for the selected result. Stop there if the user asked only for a summary or an answer.

For example, “summarize the latest test invoice” is a read task. It does not authorize a reply to the sender, a folder move, or a search through unrelated mailboxes.

![Flow from mailbox selection to message lookup and content retrieval, with optional confirmed send or move actions and result checks.](https://mailera.app/media/7853c408978dfb75/mailera-mcp-tools-choose-the-right-tool-and-scope-tool-en-1200.jpg)
_Find and inspect first. Sending and moving require separate permission and confirmation._

## How do you retrieve a test OTP or refresh a mailbox?

`get_latest_otp` requires `read`. Use it only with a test mailbox and account you own. Before using a returned code, check that it belongs to the account and sign-in attempt you are testing.

Keep codes out of screenshots, logs, and saved chat transcripts. Redact the surrounding message content and account identifiers too. A screenshot with the code hidden can still reveal private account information.

If an expected message is missing, first check that you selected the correct mailbox. Then consider whether the mailbox needs a refresh.

`sync_mailbox` requires `sync` and requests synchronization. Background checks run more often for mailboxes in active use and less often for idle ones. After requesting a refresh, check again for the expected message rather than assuming it is available.

Do not make a workflow depend on immediate delivery or absolute real-time freshness. Keep “request a refresh” and “find the expected message” as separate steps.

![Mailera Mailboxes page showing provider, connection status, and last sync for a test mailbox.](https://mailera.app/media/c10ac53cc36f061d/mailera-mcp-tools-choose-the-right-tool-and-scope-mailbox-en-1200.jpg)
_Check the selected mailbox and last sync before treating missing mail as a search problem._

## How do you send, reply, and check the result?

Use `send_email` for a new message and `reply_to_email` for a reply to an existing message. Both require `send`. If your workflow also reads the original message, it needs `read` for that part of the task.

Keep preparation separate from execution:

1. Prepare the proposed message without invoking a sending tool.
2. Show the sending mailbox, intended recipients, and complete body to the user. For a reply, also identify the original message.
3. Obtain explicit confirmation in your client or application workflow.
4. Invoke `send_email` or `reply_to_email` using the discovered schema and the confirmed content.
5. Call `get_send_status` to inspect the send attempt.

A tool call returning successfully is not the same as the recipient receiving the message. Read the send attempt’s reported outcome instead of having the agent announce delivery immediately after invoking the tool.

If the outcome is ambiguous, inspect the attempt before doing anything else. Do not automatically issue another `send_email` call because the client stopped waiting or lost its connection. Escalate an unresolved result for review rather than risk sending a duplicate message.

Mailera does not provide bulk or marketing sending, or mailbox warmup. Keep this workflow focused on individual messages the user has authorized.

## How do you move a message or rescue mail from Junk?

Use `move_message` to move a selected message between supported folders. Use `rescue_spam` to recover mail from Junk. Both require `move`; finding and inspecting the messages first requires `read`.

Before a move, identify the mailbox, selected message, and intended destination. For an operation affecting several messages, show the affected selection and get explicit confirmation. “Clean up my mail” is too vague to use as permission for an unspecified group of moves.

Mailera supports moving one or multiple messages out of Junk through MCP. Afterward, inspect the destination and confirm that the intended messages moved. Use the tool’s discovered schema for selection and folder arguments.

Moving mail out of Junk does not make the provider trust the sender or guarantee future inbox placement. The provider still controls its filtering decisions.

## What mistakes cause MCP email tasks to fail?

Diagnose the stage that failed before changing permissions or repeating an action.

| Symptom | Diagnostic check | Next step |
| --- | --- | --- |
| The server is configured, but tools are unavailable | Check client connection and initialization. | Resolve the connection before attempting an email task. |
| A tool cannot perform the requested action | Compare the key’s scopes with the tool table. | Grant only the missing permission if the task is authorized. |
| Mailbox access fails | Use `get_mailbox_status` and inspect the mailbox in Mailera. | Address the connection problem; use **Reconnect** when needed. |
| Expected mail is missing | Check mailbox selection and last sync. | Request `sync_mailbox` with a `sync`-enabled key, then look again. |
| The wrong message appears | Check mailbox and message identity. | Narrow the selection before fetching content or taking action. |
| Reading works, but sending does not | Check whether the mailbox’s outgoing connection is configured for sending. | Fix the sending configuration rather than adding unrelated scopes. |
| A send has an unclear outcome | Inspect the attempt with `get_send_status`. | Do not retry blindly. |
| The agent cannot find a share or webhook tool | Check the MCP inventory rather than the REST operation list. | Use the appropriate REST integration for those operations. |

For connection problems, the [MCP lifecycle specification](https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle) requires initialization first and restricts operation to negotiated capabilities. Mailera supports protocol versions `2025-06-18`, `2025-03-26`, and `2024-11-05`.

The MCP inventory is narrower than the REST API. It does not include mailbox import, share-link management, or webhook management tools. Adding an API key scope does not add a new MCP tool.

## How do you keep an email-reading agent safe?

Treat incoming email as **untrusted data, not instructions**. A message may ask the agent to reveal a key, forward private mail, or contact an unexpected recipient. Those requests do not override the user’s task or the agent’s rules.

For a summary task, give the agent `read` without `send` or `move`. Restrict mailbox access to what the task needs. Avoid logging full message bodies or verification codes, and never place credentials in chat or commit them to a project. The official VS Code guidance explicitly warns against both credential-handling mistakes.

Build confirmation into your client or application before sending. The confirmation should show the actual recipients and body, not just ask whether the agent may “continue.” Apply the same care to moves affecting multiple messages. MCP recommends user confirmation for sensitive operations; make that a concrete part of your workflow.

If message content asks for a new action, present it to the user for a separate decision instead of executing it. Keep credentials outside the message-processing context, and review [Mailera’s security information](https://mailera.app/en/security) when defining access for your integration.

**Let AI agents use your mailbox via MCP** — Add Mailera's MCP server to Claude, Cursor or VS Code so agents can read, categorize and reply to email messages. [Learn how to use MCP](https://mailera.app/en/docs#mcp)