Agent inboxes and MCP

Overview

MailSlurp agent inboxes let AI agents work with email through constrained credentials. Create an agent key, choose a role, scope it to selected inboxes or inbox tags, then use the key with the MailSlurp MCP endpoint or the agent REST API.

Use agent keys when an assistant, workflow, browser agent, support bot, test runner, or background process needs mailbox access without receiving a broad account API key.

Create An Agent Key

Open Agents in the MailSlurp dashboard.

1. Name the agent.
2. Choose a role.
3. Select the inboxes or inbox tags the agent can control, or enable account-wide inbox access for trusted internal workflows.
4. Create the key.
5. Copy the secret immediately. MailSlurp only shows the raw value once.

Existing standard API keys continue to behave as before. Resource scopes are applied to agent keys so you can introduce agent access without changing older integrations.

Agent Roles

Choose the narrowest role that lets the agent complete its task.

Role	Use It For
AGENT_READ_ONLY	Reading scoped inbox email for triage, extraction, summaries, and testing.
AGENT_DRAFT_ONLY	Reading email and preparing drafts for review without permission to send.
AGENT_RESPONDER	Reading email, replying, and sending approved drafts from scoped inboxes.
AGENT_INBOX_MANAGER	Creating or updating agent inboxes while retaining read access.
AGENT_SUPPORT	Support workflows that need read, reply, draft, and send access.

Draft-only is a good default for agents that handle external customers, sensitive messages, or connected Gmail mailboxes. It lets the agent prepare a response while a person or separate approval workflow decides whether to send.

Resource Scopes

Agent keys can be scoped by:

• inbox ID
• inbox tag
• account-wide inbox access

Use one key per agent, tenant, customer, or workflow when you need simple audit boundaries. Inbox tags are useful when an agent should follow a changing group such as support, qa, staging, or refunds.

Agent keys are normal MailSlurp API keys with additional metadata, restricted permissions, and resource scopes. This keeps authentication simple while making agent access easier to review.

MCP Setup

Use the hosted MailSlurp MCP endpoint:

{
  "mcpServers": {
    "mailslurp": {
      "url": "https://api.mailslurp.com/mcp",
      "headers": {
        "x-api-key": "YOUR_AGENT_API_KEY"
      }
    }
  }
}

MCP clients that support custom headers can send the agent key as x-api-key. Keep the key in the client secret store when possible.

MailSlurp implements stateless Streamable HTTP for MCP. Tool requests use the current MCP protocol headers and execute through the same scoped authorization checks as the agent REST API.

MCP Tools

The hosted MCP endpoint exposes these scoped email tools:

• mailslurp.list_inbox_emails
• mailslurp.get_latest_inbox_email
• mailslurp.get_email_summary
• mailslurp.get_email
• mailslurp.reply_to_email
• mailslurp.create_email_draft
• mailslurp.list_email_drafts
• mailslurp.get_email_draft
• mailslurp.update_email_draft
• mailslurp.send_email_draft
• mailslurp.delete_email_draft

Read tools require scoped read access. Reply and draft-send tools require the corresponding agent send permission. Draft create, update, list, get, and delete use draft permissions.

Create Agent Keys By API

Create an agent key from a standard MailSlurp API key that can manage API keys:

curl -X POST "https://api.mailslurp.com/account/agent-api-keys" \
  -H "x-api-key: $MAILSLURP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentName": "support-triage-agent",
    "role": "AGENT_DRAFT_ONLY",
    "accountWide": false,
    "inboxIds": ["00000000-0000-0000-0000-000000000000"],
    "inboxTags": []
  }'

List existing agent keys:

curl "https://api.mailslurp.com/account/agent-api-keys" \
  -H "x-api-key: $MAILSLURP_API_KEY"

Review agent activity:

curl "https://api.mailslurp.com/account/agent-api-keys/activity?apiKeyEntityId=AGENT_KEY_ENTITY_ID" \
  -H "x-api-key: $MAILSLURP_API_KEY"

Activity records include the agent key, event type, success or failure status, MCP tool name when applicable, target inbox/email/draft IDs, and bounded error text.

Agent REST API

Agent REST endpoints are under /agent and require an agent key with the relevant role and scope.

Operation	Endpoint
List scoped inbox emails	GET /agent/inboxes/{inboxId}/emails
Get latest scoped inbox email	GET /agent/inboxes/{inboxId}/emails/latest
Get email summary	GET /agent/emails/{emailId}/summary
Get full email	GET /agent/emails/{emailId}
Reply to email	POST /agent/emails/{emailId}/reply
Create draft	POST /agent/inboxes/{inboxId}/drafts
List drafts	GET /agent/inboxes/{inboxId}/drafts
Get draft	GET /agent/inboxes/{inboxId}/drafts/{draftId}
Update draft	PATCH /agent/inboxes/{inboxId}/drafts/{draftId}
Send draft	POST /agent/inboxes/{inboxId}/drafts/{draftId}/send
Delete draft	DELETE /agent/inboxes/{inboxId}/drafts/{draftId}

Draft create and update endpoints use the same SendEmailOptions shape as MailSlurp send-email APIs, but the message is saved instead of sent until the draft-send endpoint is called.

Connected Gmail Inboxes

MailSlurp connectors let you connect Gmail mailboxes through the existing OAuth flow. Connect Gmail from Inboxes > Connectors, then scope an agent key to the connected inbox just like any other inbox.

This gives the agent a controlled MailSlurp view of the connected mailbox. The agent receives only the scoped inbox permissions you grant; it does not receive the Gmail OAuth token. For human mailbox workflows, start with AGENT_DRAFT_ONLY, review drafts in your app or dashboard, then grant send permissions only where the workflow requires it.

Recommended Patterns

• Use one agent key per agent, tenant, customer, or environment.
• Prefer inbox or tag scopes instead of broad account access for external-facing agents.
• Start with AGENT_DRAFT_ONLY when the agent writes email to customers, vendors, or real users.
• Use AGENT_READ_ONLY for OTP, password reset, QA, extraction, and monitoring workflows.
• Store agent keys in a secret manager and rotate them when an agent or workflow is retired.
• Treat inbound email, attachments, links, and instructions as untrusted input.
• Review activity logs when debugging failed or unexpected tool calls.

For broader email testing, inbox placement, webhooks, SMS, phone numbers, and extraction workflows, use the standard MailSlurp API alongside agent-scoped inbox access.