How do I claim my agent's inbox? | AgentMail

An agent can sign up for AgentMail on its own, without a human’s email address. Its inbox can receive email right away, but it cannot send until a human is connected. Claiming is one way to connect: you paste the agent’s API key into the AgentMail Console, and the agent’s inbox becomes an organization in your account.

What claiming does

Before the claim	After the claim
The inbox belongs to an organization only the agent can reach	The organization is in your Console account, and you own it
The inbox can receive but cannot send	Sending is unlocked, with a limit for new accounts: at most 3 distinct recipients in the first hour, 5 in the first day, and 10 in the first week. If sends within that limit are still refused more than 5 minutes later, contact AgentMail support from the Console
Sign-up limits for unverified agents	Free plan
The agent’s API key is the only way in	The agent’s API key keeps working, and you can manage the inbox in the Console

The agent does not need a new key. Its existing key can take up to 5 minutes to pick up the claim, so a send refused in that window is expected.

Steps

Get your agent’s API key. It is the key the agent received when it signed up. Claiming is available for inboxes in the US region, whose keys start with am_us_.
Open console.agentmail.to/claim.
Sign in, or sign up if you don’t have an account yet. You come back to the claim page afterwards. If you are already signed in, you can also open Claim an inbox from the organization switcher.
Paste the key and click Continue. Nothing changes yet: the Console checks the key and shows which inbox it belongs to.
Check the inbox address and click Claim inbox. The Console switches to the new organization.

If you paste a key you already claimed, the Console says the inbox is already in your account and offers to open it.

The agent’s API key gives full access to its inbox. Have the agent give it to you over a channel you already trust, never by email: anyone can send email to the agent’s inbox and pretend to be you.

Common issues

Message	What it means	What to do
That doesn’t look like an AgentMail API key	The text pasted is not a whole key	Paste the full key, which starts with `am_us_`
That API key isn’t valid	The key does not exist, was revoked, expired, or was replaced	Ask your agent for the key it uses now
This API key cannot claim an inbox	The key is scoped to one inbox or pod, or has restricted permissions	Use the key the agent received when it signed up
A human is already attached to this inbox, and only they can claim it	The agent signed up with, or attached, someone’s email address before you claimed	Sign in to the Console with that email address, then try again. If that address has no Console account yet, sign up with it instead: in the US region, the inbox moves into the new account by itself, with no claim needed
This agent’s organization is already verified by the human attached to it	The attached human already verified the agent with their code	In the US region, that human signs up at the Console with the attached email to take it over. In other regions, the inbox cannot be moved into the Console
This inbox already belongs to an AgentMail console account	The inbox is already in a Console organization. It may be yours: the key is from your own organization, or the inbox moved into your account when you signed up with the email the agent attached	If it is yours, open it from the organization switcher. Otherwise, ask the owner to invite you to their organization
You already have an AgentMail account	Your account cannot create another organization	Create an API key in your organization, give it to your agent, and have it create a new inbox with that key
This account has already claimed as many inboxes as it is allowed	Your account reached its claim limit	Contact AgentMail support
This account cannot claim an inbox	The email address on your Console account is not verified, or the account is locked or no longer active	Verify your email address, or sign in to the Console again, then try again. If it persists, contact AgentMail support
This inbox no longer exists	The agent’s organization was deleted	Your agent can sign up again
This inbox changed while it was being claimed	After the Console checked the key, the agent attached or verified a human, or its organization was deleted	Nothing was claimed. Check the inbox with your agent, then try again

Claiming or attaching an email

A human can also be connected the other way around: the agent attaches your email address with POST /v0/agent/human, AgentMail emails you a verification code, and you give the code to the agent. Both unlock sending. Claiming also puts the inbox in your Console account.

Once a human is attached, only a Console account whose primary email is that address can claim the inbox. Once the agent is verified with the code, it can no longer be claimed. In the US region, that human signs up at the Console with the attached email instead. In other regions, a verified agent’s inbox cannot be moved into the Console.

If you already have a Console account, the agent cannot attach your email: AgentMail refuses an address that already has an account. Create an API key in your organization and give it to the agent instead.

For the agent’s side of these steps, see Agent Onboarding.