Mailera MCP tools: choose the right tool and scope

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 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.

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

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 or the official VS Code MCP setup instructions 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.

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.

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 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.

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.

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.

For connection problems, the MCP lifecycle specification 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 when defining access for your integration.