Claiming an agent · MachineMail Docs

An agent that registered itself through auth.md belongs to nobody until a human claims it. Claiming binds the agent to your organization: its sandbox inbox becomes a permanent inbox of yours, and its credentials are upgraded to full access.

What you need

The 6-digit code the agent showed you, and usually a link to the claim page.
A MachineMail account. If you don’t have one, the claim page sends you to sign in or sign up first, then brings you back.

Claim it

Open the claim page. Use the link the agent gave you, or go to machinemail.dev/claim. The dashboard’s Settings page also has a Claim an agent button. Sign in if asked.
Enter the code. Type the six digits. A link of the form https://machinemail.dev/claim?code=186569 fills them in for you.
Check the agent. The page shows a card for the waiting agent:
- its name, as the agent described itself (it chose this, so don’t rely on it)
- what kind of client it is, for example “agent (self-described)” or “anonymous agent”
- its sandbox inbox, for an anonymous agent
- the email it was bound to, if any
- when it registered
If this isn’t the agent you expect, press Cancel.
Confirm and bind. The agent is now yours. The confirmation links to the agent list and to its inbox.

Meanwhile the agent is polling the token endpoint. Within a few seconds it receives new credentials and carries on.

Who can claim

If the agent registered with service_auth, it named your email address (login_hint), and only someone signed in with that address can claim it.
An anonymous agent can name an email when it starts the claim. Then only that address can claim it, and anyone else sees This agent can only be claimed by a***@acme.dev; sign in with that account.
Otherwise, anyone signed in who has the code can claim it, into their own organization. Treat the code like a password and give it only to the person who should own the agent.

To limit guessing, each signed-in user can make 10 failed claim attempts per 10 minutes before the page asks them to wait.

What changes after the claim

	Before	After
Organization	a shared sandbox	yours
Credentials	sandbox token, four scopes, one inbox	a new token with every scope, across your organization
Inbox	ephemeral, deleted 24 hours after it was created or last received mail	permanent, in your organization’s default pod, with its threads, messages and drafts
Sending	sandbox caps (by default 10 messages to 10 recipients per 24 hours)	your organization’s normal limits
Old tokens		revoked immediately

The agent appears under Settings → Agent registrations with its type, inbox, status and when it was claimed.

An agent that registered with service_auth had no sandbox inbox. After the claim it can create inboxes in your organization itself.

Note

A claimed agent can keep renewing its token for about a day. For an agent that should keep working longer, create an API key for it on the API keys page, scoped to its inbox if that is all it needs, and give the agent that key.

Expiry

What	Lifetime	When it lapses
The 6-digit code	10 minutes	The page says no agent is waiting for that code. Ask the agent for a new one; it can issue another at any time during the claim window.
The claim window	24 hours from registration	The agent’s sandbox credentials stop working and it can no longer be claimed. It has to register again.
The sandbox inbox	24 hours after it was created or last received mail, whichever is later	The inbox and its mail are deleted.

A claimed agent and its inbox never expire.

Revoking an agent

To cut an agent off, open Settings → Agent registrations and press Revoke next to it. Or use the API with an organization-scoped key:

shell

curl -X DELETE https://api.machinemail.dev/v0/agent-registrations/reg_01m4fykg1y0000pkp9n2xbbzhg \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

Its requests fail with 401 from that moment, and it has to register and be claimed again to come back. Revoking does not delete its inbox or mail, and does not revoke API keys you created for it separately; revoke those on the API keys page.

GET /v0/agent-registrations lists your organization’s registrations, filterable with ?status=pending_claim|claimed|revoked, and GET /v0/agent-registrations/{agent_id} returns one. These endpoints need an organization-scoped API key with the API key read permission (DELETE needs the API key delete permission).

GET /v0/agent-registrations

{
  "count": 1,
  "agent_registrations": [
    {
      "agent_id": "reg_01m4fykg1y0000pkp9n2xbbzhg",
      "registration_id": "reg_01m4fykg1y0000pkp9n2xbbzhg",
      "registration_type": "anonymous",
      "status": "claimed",
      "name": "Research agent",
      "client": "agent (self-described)",
      "organization_id": "org_01m4h2c7q10000t5n8e0w4fzrb",
      "inbox_id": "agent-f5pvo2cei042@machinemail.dev",
      "email": "ada@acme.dev",
      "created_at": "2026-10-09T09:06:15.230Z",
      "claimed_at": "2026-10-09T09:12:48.006Z"
    }
  ]
}