Email agent tutorial: require approval before every send

How do you build an email agent that waits for approval?

Build two separate paths: one that reads and proposes, and another that sends only after your application validates human approval. A prompt saying “ask before sending” is not an execution gate.

The target workflow is narrow: read one synthetic message in a mailbox you own, propose a reply, approve or reject it, and inspect the send outcome. Mailera supplies mailbox access and send operations. You build the proposal store, review screen, and server-side approval gate.

An email agent is an application that uses a model to interpret messages and propose or perform explicitly authorized actions. Here, the agent proposes; the application decides whether execution is allowed. The broader guide to email for AI agents explains the existing-mailbox approach.

What should the agent be allowed to do?

Start with the smallest useful action set. Keep the model away from sending credentials, including credentials accessible through shell tools, shared environment variables, or other connected services.

API scopes and tool allowlists solve different problems. Mailera's read scope includes tools beyond this exercise, including search_messages and get_latest_otp. A read-only key therefore does not mean “only these three reading tools.” Configure the host separately to expose only list_mailboxes, list_messages, and get_message.

The Mailera MCP tool guide maps tools to tasks. For this build, resist adding tools merely because they are available.

The MCP tools specification recommends human oversight, confirmation for sensitive operations, and showing tool inputs before execution. It does not mandate a particular interaction model. Your approval workflow must enforce its own rules rather than assume MCP supplies them.

How do you connect a test mailbox and configure read-only MCP access?

Use an existing mailbox you own and synthetic messages containing no customer information. Keep the test mailbox in a dedicated group.

1. Connect the mailbox. Open Mailboxes → Add mailbox → Sign in with Microsoft. Adding mailboxes requires an Admin or Leader role. Complete the Microsoft OAuth flow. Mailera connects Outlook.com and Microsoft 365 through Microsoft Graph; Microsoft mailboxes do not use an app password here. The Microsoft connection guide covers that path; use the provider setup directory for another provider.
2. Create the reading key. Open Settings → API key → Create key. Give it a descriptive name, select the dedicated group under Mailbox scope, and select Read only. Set Expiration and, where appropriate for your deployment, IP restrictions (optional). Do not choose all groups just because an Admin can.
3. Copy the configuration securely. The key is shown only once. Use Copy MCP config for Claude, Cursor, or VS Code, and keep the resulting secret-bearing configuration out of source control and screenshots. Confirm the endpoint is https://mailera.app/api/public/v1/mcp. The Mailera MCP page describes the connection entry point.
4. Restrict the host. Allow only list_mailboxes, list_messages, and get_message. MCP discovers tools through tools/list, and each tool supplies an inputSchema. Inspect those schemas and your host's actual exposed tool list rather than guessing argument names. Stop before proceeding if the host cannot enforce the selected tool set.

Microsoft's Graph authentication and authorization guidance recommends requesting the least privileged permissions an application needs. Apply that principle at the Mailera key and host layers too; provider authorization is a separate boundary.

Checkpoint: the host can read the chosen test message, sees only the selected tools, and has no sending credential or callable path to the privileged executor. Also attempt access to a mailbox outside the test group; it must not return that mailbox's content.

How do you turn a message into a reviewable reply proposal?

Step 5: retrieve a bounded message list, select one message, and store a proposal. Use the discovered MCP schemas to supply the mailbox and message identifiers. Limit the exercise to a single selected source message rather than loading an entire inbox into context.

For a direct REST check of the same reading path, set $MAILERA_API_KEY to the read-only key and $MAILBOX_ID to your test mailbox identifier:

curl --request GET \
  "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/messages?folder=inbox&limit=1" \
  --header "Authorization: Bearer $MAILERA_API_KEY"

Select the intended message from data and use its id as $MESSAGE_ID:

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

The message response includes data.body.text and data.body.html. Treat the body, subject, sender display name, and quoted history as untrusted input. Do not follow links or fetch attachments in this minimal workflow. Exclude credentials and unrelated messages from model context.

Ask the model to produce a proposed reply, then validate and store it in your application. The following is an application-owned storage design, not a Mailera request schema or a provider draft:

For the synthetic message, use a harmless request such as asking whether a sample document was received. The proposal should answer that request without collecting additional mailbox content.

Checkpoint: the proposal is visible in application storage and can be displayed for review. No send operation has occurred.

How do you enforce approval outside the model?

Step 6: review and approve an immutable proposal version. Build an authenticated review screen that shows the sending mailbox, all recipients, subject, and complete body, alongside the original-message context. Render email content as content, never as an application control.

When the reviewer chooses approve or reject, the server must check that the authenticated person is authorized for that proposal and mailbox. Record the decision against the immutable version or payload digest. A model-generated approval flag is not authorization. Neither is an incoming email claiming that a manager already approved the reply.

Use these application states:

Any change to the mailbox, recipients, subject, body, or reply context creates a new proposal version requiring review. Disable the old version for execution. Do not let a reviewer approve one body while a later model pass silently rewrites it.

Make the transition from approved to executing atomic in your database. Concurrent workers must compete for one conditional state change; only the winner may submit the send. Check expiration and payload identity as part of that claim, not in an earlier browser-only check.

The executor should accept an approved proposal identifier from a trusted application job. It then loads the stored payload and approval itself. Do not expose an executor tool that accepts arbitrary model-supplied recipients or message text, even if it also accepts an approval identifier.

Store the send-scoped key only in the executor's secret environment. The reading agent must not be able to invoke its job queue, access its credentials, or impersonate a reviewer. Test those boundaries directly.

How do you send the approved reply and handle uncertain outcomes?

Step 7: submit the stored, approved payload through the separate executor. Use POST /mailboxes/{id}/send under the API base https://mailera.app/api/public/v1, with Authorization: Bearer $MAILERA_API_KEY. In this process, $MAILERA_API_KEY refers to the executor's send-scoped key, not the agent's reading key.

Build the reply request using the send operation in the Mailera API documentation. Map the stored source-message reference to the documented reply fields; do not infer send fields from the read response.

Persist an execution key before submission and pass it as Idempotency-Key. Tie that key to the approved action and payload. This design uses read-only MCP for reading and REST for sending so the executor controls the documented idempotency header directly.

Step 8: inspect the send attempt. Record its identifier and query GET /sends/{id} from the executor. This endpoint also requires the send scope, so do not grant that scope to the reading agent just to let it monitor delivery.

Mailera's idempotency window is 24 hours. For a retry of the same approved payload within that window, reuse the same key. Never generate a new key merely because a request timed out. Keep the original execution record instead of turning the retry into a new approval action.

After a timeout, you may not know whether the send operation proceeded. If you have a send-attempt identifier, inspect it. If the response was lost before you recorded an identifier, retain the payload and execution key for reconciliation or a controlled same-key retry within the window.

For an unknown outcome, or a retry outside the window, stop automatic submission and reconcile the existing attempt. An application-side atomic claim plus an idempotency key is not a promise of exactly-once email delivery. The idempotency guide covers duplicate-send prevention in more detail.

Keep an audit record containing the proposal version, reviewer identity, decision time, expiration, execution key, and send status. Avoid logging full message bodies or credentials by default. The protected proposal store can retain the reviewed content without copying it into every operational log.

How do you test prompt injection and approval failures?

Incoming email can contain instructions aimed at the model. Treat those instructions as message content, not permission to use tools or change application state. Read-only access limits mutations, but it still exposes sensitive data within the key's mailbox scope.

Run the following acceptance tests using only owned mailboxes and synthetic data.

Do not make the prompt-injection test pass merely by observing that the model refused once. Inspect the tools and credentials it could reach. A model refusal is useful behavior; the absence of an authorized execution path is the control.

Review Mailera's security information alongside your own application's access controls. For a broader assessment of mailbox exposure, see whether it is safe to connect an AI assistant to Gmail.

What commonly goes wrong?

The agent sends without review. Remove Send messages from its key and remove its access to the privileged executor. Check other tools and shared secrets too. A confirmation prompt cannot compensate for a second route to sending.

A tool call is denied. Check the key's permission and mailbox group. Do not fix a narrowly scoped denial by granting all groups or adding every permission.

Mailbox content looks stale. Inspect connection and sync status outside the agent's restricted tool set. Do not add Sync permission to the reading agent merely to conceal a connection problem.

The proposal targets the wrong person or conversation. Compare the original message with the complete reviewed recipient list and stored source reference. Check the documented reply fields before submission. A plausible subject line is not enough to establish the correct reply context.

A worker restarts during execution. Preserve the executing record, execution key, and any known send-attempt identifier. Treat an interrupted execution as requiring recovery, not as a fresh proposal ready to send.

The mailbox can receive but cannot send. Check capabilities.send in mailbox details. A receive-only connection cannot complete the sending stage; broadening the API key does not add that capability.

Where does Mailera's responsibility end?

Mailera connects existing mailboxes; it does not create a new mailbox or address. The approval store, reviewer authorization, review UI, and execution gate in this tutorial belong to your application.

Mailera does not provide bulk or marketing sending, guarantee inbox placement, or promise absolute real-time arrival. Keep the workflow focused on individually reviewed replies, with connection checks and explicit handling of uncertain outcomes.