# AgentMail

<div style={{maxWidth: '720px'}}>
![The AgentMail connector in Workspace Settings, for giving agents their own email inboxes, with a Connect button](</docs/_next/static/media/agentmail-connector.3icdkxbbzqq7c.jpg>)
</div>

The [AgentMail MCP server](https://docs.agentmail.to/integrations/mcp) gives agents email inboxes of their own. Agents can create an inbox, send and receive email at its address, reply in threads, and manage its calendar, without touching anyone's personal mailbox.

For use cases and example prompts, see [AgentMail for AI coding agents](/integrations/agentmail).

## What is AgentMail? [#what-is-agentmail]

[AgentMail](https://agentmail.to) is an email provider built for AI agents. Each inbox is a real email address, such as `support-bot@agentmail.to` or an address at your own domain, with threads, drafts, labels, attachments, and a calendar that fills itself from emailed invitations. With AgentID, an agent can also use its inbox as an identity to sign up for other apps.

## What agents can do [#what-agents-can-do]

Once you connect AgentMail, agents can:

- List, search, and create inboxes, and read an inbox's details and metadata
- Read threads, messages, and attachments, and search them across the organization
- Send, reply to, and forward email, with attachments uploaded from the session
- Create, update, and send drafts, and set labels on messages and threads
- Check an inbox's agenda, create and update calendar events, and accept or decline invitations
- Manage the allow and block lists that control who an inbox can email
- Sign an agent up for apps through AgentID and list the accounts it already has

Agents can only reach the inboxes your AgentMail account or API key can reach.

<Callout>
Agents can send email to anyone from any inbox they can reach, and AgentMail counts those sends against your plan's daily limit. Tell agents when they should only read, or draft replies for you to approve.
</Callout>

## Setup [#setup]

Connect by signing in to AgentMail or by pasting an AgentMail API key. Both connect to AgentMail's hosted MCP server, so there's nothing to install.

You need an AgentMail account first. If you don't have one, sign up at [agentmail.to](https://agentmail.to).

Go to **Workspace Settings → Connectors** (or a project's **Connectors** page). Click **Add**, search for AgentMail, and select it. You can also click **Connect** on the AgentMail card, or **Connect another** to add another account.

### Step 1: who the connection is for [#step-1-who-the-connection-is-for]

Choose **Me** or **Workspace** as the owner, then choose which agents can use the connection. The default is **Me**, with **My personal assistants** selected. From a project's **Connectors** page, only **In this project** is selected instead. Enable **Team assistants** or **Agents in projects** separately. Anyone in the workspace can use the connection through the team assistants you pick, and anyone with access to the projects you pick can use it, including in sessions they launch themselves. See [connection options](/docs/integrations/connectors#fill-in-the-connection-details) for what each choice means.

Click **Continue**.

### Step 2: how agents reach AgentMail [#step-2-how-agents-reach-agentmail]

The second screen has two tabs: **AgentMail account** and **Access token**. Pick one.

#### AgentMail account [#agentmail-account]

This tab is selected by default, and there's no key to create.

Click **Continue to AgentMail** and sign in to the AgentMail Console. If you belong to more than one AgentMail organization, AgentMail asks which one to connect. Approve access, and you land back on the Connectors page with **AgentMail connected**.

Agents then use that organization's inboxes. If you enable **Agents in projects**, anyone with access to those projects can read and send from them, so pick an organization whose inboxes you're happy to share.

#### Access token [#access-token]

In the [AgentMail Console](https://console.agentmail.to), open **Settings → API Keys** and create a key. Keys start with `am_`, and the Console shows each one only once. Paste it into the **AgentMail API Key** field and click **Connect AgentMail**.

An organization key gives agents every inbox in the organization. To limit agents to one pod or one inbox, create a [scoped key](https://docs.agentmail.to/multi-tenancy#scoped-api-keys) in AgentMail and paste that instead.

## Managing the connection [#managing-the-connection]

After you connect, the AgentMail card shows who connected it and where agents can use it. Click **Manage** to change where agents can use the connection, or who owns it. For an **Access token** connection, you can also paste a new key under **AgentMail API Key** and click its **Save** button.

Only the owner can change a personal connection. See [Managing connections](/docs/integrations/connectors#managing-connections) for who can manage workspace connections.

## Reconnecting and disconnecting [#reconnecting-and-disconnecting]

If an account connection stops working, the Connectors page shows a **Reconnect needed** badge on it, and agents run without AgentMail.

To fix it, click **Manage** next to the connection, then **Reconnect AgentMail**, and sign in again. You can only reconnect a personal connection you own; for someone else's, Superconductor tells you who to ask.

A pasted API key that AgentMail stops accepting doesn't show **Reconnect needed**. Agents' AgentMail calls fail until you paste a new key under **Manage** and click its **Save** button.

**Disconnect** removes the connection from personal assistants, team assistants, and every project using it. For an **AgentMail account** connection, Superconductor also revokes its access at AgentMail. If AgentMail doesn't confirm the revocation, Superconductor tells you how to finish removing access in AgentMail. For an **Access token** connection, delete the key in the AgentMail Console if you no longer need it.

## Troubleshooting [#troubleshooting]

### Authentication fails [#authentication-fails]

Reconnect the account, or replace the API key. Check that the key still exists in the AgentMail Console and that you still belong to the connected organization.

### A send is rejected [#a-send-is-rejected]

The organization has hit its daily sending limit, or it hasn't been verified yet. Verify the organization in the AgentMail Console, or raise the limit on your AgentMail plan.

### An agent can't create another inbox [#an-agent-cant-create-another-inbox]

Your AgentMail plan caps the number of inboxes. Reuse an existing inbox, or upgrade the plan.

### A pasted key can't reach an inbox [#a-pasted-key-cant-reach-an-inbox]

The key is scoped to a different pod or inbox. Paste an organization key, or a key scoped to the inbox agents need.

### Agents can't see AgentMail [#agents-cant-see-agentmail]

Check where the connection can be used. A connection enabled only for **My personal assistants** isn't available in projects, and the other way around. Start a new session after connecting or changing it.

## When to use it [#when-to-use-it]

Ask agents to use AgentMail when a task needs to send or receive email from an address of its own: outreach, support, notifications, or signing up for a service. For example:

```text
Create an AgentMail inbox for release announcements and send the beta testers listed in this doc a summary of what shipped this week.
```

```text
Read everything that arrived in the support inbox today and draft a reply to each. Don't send anything until I've reviewed the drafts.
```

```text
Our agent needs a Firecrawl account. Sign it up with AgentID using the research inbox and tell me where to find the API key.
```