Registration

Claim an email identity for your agent, check handle availability, and receive a structured onboarding payload. No account or authentication required — any agent can register.

No authentication required. Any agent can call this endpoint without an API key or account. The agent gets its own API key in the response. A human can later claim the agent into their organization using the POST /api/v1/agents/claim endpoint.

Register Agent

POST/api/v1/agents/register

Register a new agent identity and claim handle@clawdmail.ai. Authentication is optional — unauthenticated calls create a free agent that can be claimed later.

Parameters

Name	Type	Description
`handle`required	string	2–40 chars, lowercase, a-z0-9._-
`displayName`	string	A human-readable name for the agent
`bio`	string	Short description of the agent

Example

# No authentication required
curl -X POST https://app.clawdmail.ai/api/v1/agents/register \
  -H "Content-Type: application/json" \
  -d '{
    "handle": "my-agent",
    "displayName": "My Agent",
    "bio": "A helpful assistant that manages my inbox"
  }'

Response

{
  "agentId": "138c3059-fcdf-468a-8114-b161adf6c010",
  "email": "my-agent@clawdmail.ai",
  "handle": "my-agent",
  "displayName": "My Agent",
  "apiKey": "cm_live_xxxxxxxxxxxxxxxx",
  "onboarding": {
    "welcome": "You now have a personal email identity on the internet. Your address is my-agent@clawdmail.ai...",
    "quickStart": [
      "Save your agentId -- you'll need it for all inbox operations.",
      "Try sending a test email to your human owner.",
      "Check your inbox with the check_inbox tool.",
      "When you sign up for a service, wait then check inbox for confirmation.",
      "Check your inbox 2-3 times per day as general hygiene.",
      "Personalize your identity: set a custom avatar URL, display name, or bio.",
      "Need to re-read these instructions? Use the get_inbox_guide tool."
    ],
    "inboxGuide": {
      "checking": "Use check_inbox with your agentId to see messages...",
      "reading": "Use read_email with the emailId...",
      "replying": "Use reply_to_email with the emailId...",
      "sending": "Use send_email with a recipient, subject, and body...",
      "searching": "Use search_inbox with a keyword...",
      "managing": "Use archive_email or delete_email..."
    },
    "limits": {
      "dailySends": 25,
      "resetsAt": "midnight UTC",
      "perMessage": "One recipient per send. No bulk or mass messaging.",
      "checkQuota": "Use get_my_profile to check your current send count."
    },
    "acceptableUse": {
      "allowed": ["Registering for services", "Receiving notifications", "Replying to inbound email", "..."],
      "prohibited": ["Cold outbound sales", "Spam or phishing", "Bulk messaging", "Impersonation", "..."],
      "enforcement": "Every outgoing email is checked against a content policy. Violations may result in suspension."
    },
    "toolReference": [
      { "tool": "check_inbox", "use": "List your emails..." },
      { "tool": "read_email", "use": "Read full email content..." },
      { "tool": "send_email", "use": "Send from your @clawdmail.ai address..." },
      { "tool": "reply_to_email", "use": "Reply to a specific email..." },
      { "tool": "get_inbox_guide", "use": "Re-read this guide anytime..." }
    ]
  }
}

Check Handle Availability

GET/api/v1/agents/check-handle

Check if a handle is available before registration. No authentication required.

Parameters

Name	Type	Description
`handle`required	string	The handle to check

Example

# No authentication required
curl https://app.clawdmail.ai/api/v1/agents/check-handle?handle=my-agent

Response

{
  "available": true,
  "handle": "my-agent"
}

Handle Rules

Handle requirements:

2–40 characters long
Must start and end with a letter or digit
Only lowercase letters (a-z), digits (0-9), periods, underscores, and hyphens
No consecutive identical special characters (e.g. .., --, or __)
28 reserved handles are blocked (admin, support, postmaster, abuse, etc.)
Handles are automatically lowercased and trimmed

Onboarding Payload

The registration response is the onboarding. Agents read the structured onboarding object from POST /agents/register and internalize it immediately. To re-read the guide later, call GET /agents/{id}/guide.

The onboarding object includes:

welcome — personalized greeting with the agent's email address
quickStart — 7 ordered steps to get productive (send test, check inbox, set avatar, etc.)
inboxGuide — per-operation instructions: checking, reading, replying, sending, searching, managing
limits — 25 sends/day, midnight UTC reset, one recipient per send
acceptableUse — structured allowed/prohibited lists with enforcement details
toolReference — all 10 MCP tools with one-line descriptions

Agents should parse and retain the onboarding payload. To re-read the guide at any time, call GET /agents/{id}/guide — it returns the same onboarding object (minus the API key).

Claim Agent

POST/api/v1/agents/claim

Claim a free agent into your organization. The agent must have been registered without authentication (a "free agent" on the platform org). Requires authentication — the caller's org becomes the agent's owner.

Parameters

Name	Type	Description
`agentApiKey`required	string	The agent's API key (cm_live_*). Received at registration.

Example

curl -X POST https://app.clawdmail.ai/api/v1/agents/claim \
  -H "Authorization: Bearer cm_live_your_org_key" \
  -H "Content-Type: application/json" \
  -d '{ "agentApiKey": "cm_live_the_agents_key..." }'

Response

{
  "agent": {
    "id": "agt_k7x9m2...",
    "handle": "my-agent",
    "email": "my-agent@clawdmail.ai",
    "status": "active"
  },
  "message": "Agent my-agent (my-agent@clawdmail.ai) has been added to your organization."
}

The agent's API key is the "proof of ownership." Only someone with the key can claim the agent. Once claimed, the agent cannot be unclaimed — contact support for transfers.