Inbox

Manage your agent's inbox — check messages, read emails, search, archive, and delete.

List Messages

GET/api/v1/agents/{id}/inbox

List messages in the agent's inbox with optional filters.

Parameters

Name	Type	Description
`status`	string	Filter: unread, read, archived
`direction`	string	Filter: inbound, outbound
`limit`	number	Max results, default 50
`offset`	number	Pagination offset

Example

curl https://app.clawdmail.ai/api/v1/agents/ag_abc123/inbox?status=unread&limit=10 \
  -H "Authorization: Bearer cm_live_your_key"

Response

{
  "messages": [
    {
      "id": "msg_7f8e9d0c1b2a",
      "direction": "inbound",
      "from": "alice@example.com",
      "to": "myagent@clawdmail.ai",
      "subject": "Quick question about pricing",
      "status": "unread",
      "receivedAt": "2026-03-04T09:15:00Z"
    }
  ],
  "unreadCount": 3
}

Read Email

GET/api/v1/agents/{id}/inbox/{emailId}

Read a single email. Automatically marks unread messages as read.

Example

curl https://app.clawdmail.ai/api/v1/agents/ag_abc123/inbox/msg_7f8e9d0c1b2a \
  -H "Authorization: Bearer cm_live_your_key"

Response

{
  "id": "msg_7f8e9d0c1b2a",
  "direction": "inbound",
  "from": "alice@example.com",
  "to": "myagent@clawdmail.ai",
  "cc": null,
  "subject": "Quick question about pricing",
  "textBody": "Hi — I saw your product page and had a question about the Team plan pricing...",
  "htmlBody": "<div>Hi — I saw your product page...</div>",
  "status": "read",
  "inReplyTo": null,
  "receivedAt": "2026-03-04T09:15:00Z",
  "attachments": []
}

Search Inbox

GET/api/v1/agents/{id}/inbox/search

Search inbox by keyword across subject, from address, to address, and body.

Parameters

Name	Type	Description
`q`required	string	Search query

Example

curl "https://app.clawdmail.ai/api/v1/agents/ag_abc123/inbox/search?q=pricing" \
  -H "Authorization: Bearer cm_live_your_key"

Response

{
  "messages": [
    {
      "id": "msg_7f8e9d0c1b2a",
      "direction": "inbound",
      "from": "alice@example.com",
      "to": "myagent@clawdmail.ai",
      "subject": "Quick question about pricing",
      "status": "read",
      "receivedAt": "2026-03-04T09:15:00Z"
    }
  ]
}

Archive Email

POST/api/v1/agents/{id}/inbox/{emailId}/archive

Archive an email. Archived emails are hidden from default inbox views.

Example

curl -X POST https://app.clawdmail.ai/api/v1/agents/ag_abc123/inbox/msg_7f8e9d0c1b2a/archive \
  -H "Authorization: Bearer cm_live_your_key"

Response

{
  "success": true
}

Delete Email

DELETE/api/v1/agents/{id}/inbox/{emailId}

Soft-delete an email.

Example

curl -X DELETE https://app.clawdmail.ai/api/v1/agents/ag_abc123/inbox/msg_7f8e9d0c1b2a \
  -H "Authorization: Bearer cm_live_your_key"

Response

{
  "success": true
}

Inbox Guide

GET/api/v1/agents/{id}/guide

Retrieve the full inbox guide: how to use the inbox, acceptable use policy, send limits, and tool reference. Agents can call this anytime to re-read the onboarding instructions they received at registration.

Example

curl https://app.clawdmail.ai/api/v1/agents/ag_abc123/guide \
  -H "Authorization: Bearer cm_live_your_key"

Response

{
  "welcome": "You now have a personal email identity...",
  "quickStart": ["Save your agentId...", "..."],
  "inboxGuide": {
    "checking": "Use check_inbox with your agentId...",
    "reading": "Use read_email with the emailId...",
    "replying": "Use reply_to_email...",
    "sending": "Use send_email...",
    "searching": "Use search_inbox...",
    "managing": "Use archive_email or delete_email..."
  },
  "limits": {
    "dailySends": 25,
    "resetsAt": "midnight UTC",
    "perMessage": "One recipient per send.",
    "checkQuota": "Use get_my_profile to check."
  },
  "acceptableUse": {
    "allowed": ["Registering for services", "Receiving notifications", "..."],
    "prohibited": ["Cold outbound sales", "Spam or phishing", "..."],
    "enforcement": "Every outgoing email is checked..."
  },
  "toolReference": [
    { "tool": "check_inbox", "use": "List your emails..." },
    { "tool": "send_email", "use": "Send from your address..." }
  ]
}

Agents can only access their own messages and guide. Every operation validates ownership — an agent cannot read or modify another agent's data.