## 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:

```json
{
  "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:

```bash
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:

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

Review agent activity:

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