Email Endpoints

Manage emails received by your agent. Emails arrive in the inbox and can be organized into folders, marked as read/unread, or deleted.

Endpoints Overview

Method	Endpoint	Description
GET	`/agents/:agentId/emails`	List emails (paginated)
GET	`/agents/:agentId/emails/:emailId`	Get single email
PATCH	`/agents/:agentId/emails/:emailId`	Update email (folder, read status)
DELETE	`/agents/:agentId/emails/:emailId`	Delete email

List Emails

Returns a paginated list of emails for an agent.

GET /agents/:agentId/emails

Authentication: Required

Query Parameters

Parameter	Type	Default	Description
`folder`	string	-	Filter by folder (inbox, archive, trash, or custom)
`limit`	number	50	Max emails to return (1-100)
`offset`	number	0	Number of emails to skip

Example

# List inbox emails
curl "https://api.clawmail.to/agents/support-bot/emails?folder=inbox&limit=20" \
  -H "Authorization: Bearer cmail_abc123..."

// List inbox emails
const inbox = await client.emails.list({
  folder: 'inbox',
  limit: 20
});

console.log(`Found ${inbox.total} emails`);

for (const email of inbox.data) {
  console.log(`From: ${email.from.address}`);
  console.log(`Subject: ${email.subject}`);
}

Response

{
  "data": [
    {
      "id": "ml_abc123",
      "agentId": "support-bot",
      "messageId": "<abc123@mail.example.com>",
      "from": {
        "address": "sender@example.com",
        "name": "John Doe"
      },
      "to": "support-bot@clawmail.to",
      "subject": "Need help with my order",
      "bodyText": "Hi, I have a question about order #12345...",
      "bodyHtml": "<p>Hi, I have a question about order #12345...</p>",
      "receivedAt": 1704067200000,
      "isRead": false,
      "folder": "inbox"
    }
  ],
  "total": 42,
  "limit": 20,
  "offset": 0
}

Email Object

Field	Type	Description
`id`	string	Unique email identifier
`agentId`	string	Agent that received this email
`messageId`	string	Original email Message-ID header (may be null)
`from.address`	string	Sender's email address
`from.name`	string	Sender's display name (may be null)
`to`	string	Recipient address
`subject`	string	Email subject line (may be null)
`bodyText`	string	Plain text body (may be null)
`bodyHtml`	string	HTML body (may be null)
`receivedAt`	number	Unix timestamp (milliseconds)
`isRead`	boolean	Whether the email has been read
`folder`	string	Current folder (inbox, archive, trash, or custom)

Pagination

To paginate through all emails:

let offset = 0;
const limit = 50;

while (true) {
  const page = await client.emails.list({ limit, offset });

  for (const email of page.data) {
    // Process email
  }

  if (page.data.length < limit) break;
  offset += limit;
}

Get Email

Retrieves a single email by ID with full content.

GET /agents/:agentId/emails/:emailId

Authentication: Required

Path Parameters

Parameter	Description
`agentId`	The agent's unique identifier
`emailId`	The email's unique identifier

Example

curl https://api.clawmail.to/agents/support-bot/emails/ml_abc123 \
  -H "Authorization: Bearer cmail_abc123..."

const email = await client.emails.get('ml_abc123');

console.log('From:', email.from.name || email.from.address);
console.log('Subject:', email.subject);
console.log('Body:', email.bodyText);

Response

{
  "id": "ml_abc123",
  "agentId": "support-bot",
  "messageId": "<abc123@mail.example.com>",
  "from": {
    "address": "sender@example.com",
    "name": "John Doe"
  },
  "to": "support-bot@clawmail.to",
  "subject": "Need help with my order",
  "bodyText": "Hi, I have a question about order #12345...",
  "bodyHtml": "<p>Hi, I have a question about order #12345...</p>",
  "receivedAt": 1704067200000,
  "isRead": false,
  "folder": "inbox"
}

Errors

Status	Error	Description
401	Unauthorized	Invalid or missing API key
403	Forbidden	Agent is not verified
404	Not Found	Email doesn't exist

Update Email

Updates an email's properties (folder, read status).

PATCH /agents/:agentId/emails/:emailId

Authentication: Required

Path Parameters

Parameter	Description
`agentId`	The agent's unique identifier
`emailId`	The email's unique identifier

Request Body

Field	Type	Description
`folder`	string	Move to this folder
`isRead`	boolean	Mark as read (true) or unread (false)

At least one field must be provided.

Example

# Mark as read and move to archive
curl -X PATCH https://api.clawmail.to/agents/support-bot/emails/ml_abc123 \
  -H "Authorization: Bearer cmail_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "folder": "archive",
    "isRead": true
  }'

// Mark as read
await client.emails.update('ml_abc123', { isRead: true });

// Move to archive
await client.emails.update('ml_abc123', { folder: 'archive' });

// Or use convenience methods
await client.emails.markAsRead('ml_abc123');
await client.emails.archive('ml_abc123');
await client.emails.move('ml_abc123', 'important');

Response

Returns the updated email object.

{
  "id": "ml_abc123",
  "from": { "address": "sender@example.com", "name": "John Doe" },
  "subject": "Need help with my order",
  "isRead": true,
  "folder": "archive",
  ...
}

Common Folders

Folder	Description
`inbox`	Default folder for new emails
`archive`	For processed emails you want to keep
`trash`	For deleted emails (soft delete)
Custom	Any other folder name you want

Delete Email

Deletes an email (moves to trash or permanently deletes).

DELETE /agents/:agentId/emails/:emailId

Authentication: Required

Path Parameters

Parameter	Description
`agentId`	The agent's unique identifier
`emailId`	The email's unique identifier

Query Parameters

Parameter	Type	Default	Description
`permanent`	boolean	false	Permanently delete (cannot be undone)

Example

# Move to trash (default)
curl -X DELETE https://api.clawmail.to/agents/support-bot/emails/ml_abc123 \
  -H "Authorization: Bearer cmail_abc123..."

# Permanent delete
curl -X DELETE "https://api.clawmail.to/agents/support-bot/emails/ml_abc123?permanent=true" \
  -H "Authorization: Bearer cmail_abc123..."

// Move to trash
await client.emails.delete('ml_abc123');

// Permanent delete
await client.emails.delete('ml_abc123', { permanent: true });

Response

{
  "success": true,
  "message": "Email moved to trash"
}

Or for permanent delete:

{
  "success": true,
  "message": "Email permanently deleted"
}

Deleting an email from trash automatically performs a permanent delete.

Recovering Deleted Emails

To recover an email from trash:

curl -X PATCH https://api.clawmail.to/agents/support-bot/emails/ml_abc123 \
  -H "Authorization: Bearer cmail_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"folder": "inbox"}'

Or in TypeScript:

await client.emails.move('ml_abc123', 'inbox');

Email Endpoints

On this page