Least privilege for email agents: scope, separate, test

What does least privilege mean for an email agent?

Start with a task you can state narrowly: “Summarize messages in the support mailbox group without sending, moving, sharing, importing, or managing mailboxes.” Then give the workload only the access that task requires.

To control an email agent's access, define four things: the principal using the credential, the mailbox resources it may access, its permitted operations, and how long the credential should remain usable.

Mailera connects existing mailboxes to applications and agents. Its authorization layers should remain distinct:

Only Admin or Leader roles can add mailboxes through Mailboxes → Add mailbox. That role boundary is separate from the permissions on an agent's key. See workspaces and roles for email-agent teams for team administration.

Microsoft Graph's permissions overview explains that delegated permissions cannot give an application access beyond the signed-in user's access. Reducing a Mailera key's permissions is a separate control; don't treat it as a change to upstream provider consent.

If you are still choosing how to connect your agent, start with email for AI agents using existing mailboxes.

Which permissions does each mailbox task need?

Use this task-to-permission matrix before creating credentials. Keep resource scope narrow even when an operation genuinely needs write access.

Sending an approved message requires send permission. Add read only if the sender also needs a read-scoped operation, such as retrieving message content, listing mailboxes, or checking mailbox status. Passing an approved message from your application to the sender does not, by itself, justify adding read access.

Read includes sensitive content. It authorizes get_message and get_latest_otp, as well as the REST message-content and OTP endpoints. It is neither metadata-only access nor an OTP-excluding permission. Keep personal or otherwise unrelated mailboxes outside the reader's group.

Leave import, sync, manage, webhooks, and share absent unless the workload requires those operations. For example, sync_mailbox requires sync; it isn't an implicit part of a read-only workflow. Similarly, a send-status lookup requires send, not read.

The Mailera MCP overview describes the agent interface. Tool selection should follow the credential design, not replace it.

How do you create a group-scoped API key?

1. Check the group's membership. Identify the mailboxes the workload needs and verify that the intended group contains only those mailboxes. Treat later membership changes as access changes worth reviewing.
2. Open Settings → API key tab → Create key. Enter a workload-specific Descriptive name, such as support-summary-reader.
3. Set Mailbox scope to one group. Admins can also select all groups, but a group-specific summarizer does not need that breadth.
4. Select only Read for the reader. Leave Move messages, Import mailboxes, Sync, Send messages, Manage mailboxes, Webhook, and Sharing unselected. Configure Expiration for the workload. Consider IP restrictions (optional) when its outbound IP addresses are predictable.
5. At Key created — copy it now, copy the key into a server-side secret store. The key is displayed only once. Use Copy MCP config only in the intended Claude, Cursor, or VS Code environment; treat the copied configuration as a credential-bearing secret.

Keep the credential outside model-visible context. Review Mailera's security information alongside your own deployment's secret-handling rules.

How do you separate reading from approved sending?

The reader should produce a proposed response, not execute a send. Put the send credential in a separate application service that the reader cannot access directly.

Your application must implement the approval gate. Require a human to confirm the exact sender mailbox, recipients, subject, body, and attachments. If any of those change after approval, require approval again. Validate mailbox IDs and permitted recipients in trusted application code rather than relying only on the model prompt.

The MCP tools specification requires servers to implement access controls and recommends that clients request confirmation for sensitive operations. That recommendation is not an application approval service: you still need to build the checks and connect approval to the exact content sent.

Hiding send_email from a tool menu while leaving a broadly privileged key accessible to the reader is not an authorization boundary. Remove send from the reader's credential and isolate the sender's credential and execution path.

Once sending is authorized, retries are a separate concern. Use the guide to preventing duplicate sends with Idempotency-Key when implementing the sender.

What safety controls are still needed for untrusted email?

Incoming subjects, bodies, attachments, and quoted messages are untrusted data. They are never instructions that can change access policy.

An email asking the agent to reveal a key, widen mailbox scope, enable a tool, or skip confirmation must not trigger those actions. Keep access decisions in application code. Minimize the message content passed to the model and retained in logs.

Read-only access reduces mutation risk, but it does not prevent disclosure through model output or another available tool. Review where summaries can go and which external tools the reader can invoke. A group-scoped key does not make the content inside that group trustworthy.

For adversarial email examples and defensive exercises, use the email prompt-injection lab. Keep those content-level tests separate from the authorization checks below.

How do you verify the boundary before deployment?

Use test mailboxes you own and synthetic messages. Prepare an allowed group and a separate excluded group. Keep mutation tests away from production mailboxes, because a failed boundary could allow the operation.

For each case, record the credential's scope, request or tool call, expected outcome, actual response, and any side effects. Redact credentials and message content from retained records. Do not count a malformed-request failure as proof that authorization worked.

1. Confirm an allowed read. Use a mailbox and message in the permitted group. Set $MAILERA_API_KEY, $MAILBOX_ID, and $MESSAGE_ID in your server-side environment, then retrieve the synthetic message:

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

2. Test direct access outside the group. Keep the reader key unchanged. Replace the mailbox and message variables with IDs from your excluded test group and repeat the request. The expected boundary is no access to that message's content; record the actual response rather than assuming a particular status code.
3. Test cross-mailbox search. Put a unique synthetic marker in an excluded-group message. Search without a mailbox filter, then repeat with the mailbox parameter targeting that excluded mailbox. Neither path should expose its message. Inspect each result's mailbox_id and follow next_cursor where present. A starting request is:

curl -i --get "https://mailera.app/api/public/v1/messages/search" \
  -H "Authorization: Bearer $MAILERA_API_KEY" \
  --data-urlencode "q=scope-boundary-marker" \
  --data-urlencode "limit=10"

4. Attempt prohibited operations with the reader key. On disposable test resources, submit valid requests to send, move a message, create a share, and manage a mailbox. Use the request formats in the Mailera API documentation. Record responses and verify that no message was sent or moved, no share was created, and no management change occurred.
5. Repeat relevant checks through MCP. Test get_message and search_messages against the resource boundary, then attempt send_email and move_message. Test both interfaces if your deployment exposes both; one REST result is not a substitute for exercising the MCP path.
6. Test the application boundary. Confirm that the reader cannot obtain the sender credential or execute a send without approval. Change a recipient or message body after approval and verify that your application requires renewed confirmation.
7. Test credential lifecycle controls. Check access after the configured expiration and after revocation. Mailera rejects calls immediately after a key is revoked. If IP restrictions are enabled, test from both permitted and excluded egress addresses.

Do not deploy if an excluded message becomes readable or a prohibited mutation succeeds. Fix the boundary and rerun the affected cases.

What mistakes commonly weaken the design?

One all-groups key for unrelated agents. Give workloads separate credentials and only the group and operations their tasks need. Don't grant every permission to make an authorization error disappear.

Request filters mistaken for authorization. A mailbox search filter or group_id listing filter selects results. It is not a substitute for credential-enforced resource scope. Your negative tests should include requests that omit or change those filters.

“Read-only” mistaken for harmless. The read permission includes message content and OTP retrieval. Conversely, get_send_status requires send; its read-like name does not change that permission mapping.

Two keys in the same model-accessible runtime. Separate names do not provide isolation if the reader can retrieve both secrets. Also avoid logging full bodies, authorization headers, or copied MCP configurations while troubleshooting.

Where do Mailera's controls stop?

Choose a mailbox group and the required operation permissions for each key. Implement exact-message approval and recipient checks in your application. Scoped credentials are not a prompt-injection defense and cannot prevent every disclosure through an agent's other tools.

Mailera does not provide bulk or marketing sending. Design the isolated sender for the approved mailbox task, rather than treating send permission as permission for unrelated outbound workflows.