Send Endpoints

Send emails from your agent and track sent messages. Emails are delivered via Resend.

Endpoints Overview

Method	Endpoint	Description
POST	`/agents/:agentId/send`	Send an email
GET	`/agents/:agentId/sent`	List sent emails

Send Email

Sends an email from your agent's address.

POST /agents/:agentId/send

Authentication: Required

Path Parameters

Parameter	Description
`agentId`	The agent's unique identifier

Request Body

Field	Type	Required	Description
`to`	string \| string[]	Yes	Recipient email(s)
`subject`	string	Yes	Email subject line
`text`	string	One of text/html	Plain text body
`html`	string	One of text/html	HTML body
`replyTo`	string	No	Reply-to address

At least one of text or html must be provided. For best compatibility, include both.

Example

# Simple text email
curl -X POST https://api.clawmail.to/agents/support-bot/send \
  -H "Authorization: Bearer cmail_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "customer@example.com",
    "subject": "Order Confirmation",
    "text": "Your order #12345 has been confirmed!"
  }'

// Simple text email
const result = await client.send.email({
  to: 'customer@example.com',
  subject: 'Order Confirmation',
  text: 'Your order #12345 has been confirmed!'
});

console.log('Sent:', result.id);

HTML Email Example

curl -X POST https://api.clawmail.to/agents/support-bot/send \
  -H "Authorization: Bearer cmail_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "customer@example.com",
    "subject": "Order Confirmation",
    "html": "<h1>Order Confirmed!</h1><p>Your order <strong>#12345</strong> has been confirmed.</p>",
    "text": "Order Confirmed!\n\nYour order #12345 has been confirmed."
  }'

await client.send.email({
  to: 'customer@example.com',
  subject: 'Order Confirmation',
  html: `
    <h1>Order Confirmed!</h1>
    <p>Your order <strong>#12345</strong> has been confirmed.</p>
  `,
  text: 'Order Confirmed!\n\nYour order #12345 has been confirmed.'
});

Multiple Recipients

curl -X POST https://api.clawmail.to/agents/support-bot/send \
  -H "Authorization: Bearer cmail_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["admin@example.com", "manager@example.com"],
    "subject": "Daily Report",
    "text": "Here is the daily report..."
  }'

await client.send.email({
  to: ['admin@example.com', 'manager@example.com'],
  subject: 'Daily Report',
  text: 'Here is the daily report...'
});

With Reply-To

curl -X POST https://api.clawmail.to/agents/support-bot/send \
  -H "Authorization: Bearer cmail_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "subject": "Support Ticket #456",
    "text": "Your support ticket has been created.",
    "replyTo": "support@example.com"
  }'

await client.send.email({
  to: 'user@example.com',
  subject: 'Support Ticket #456',
  text: 'Your support ticket has been created.',
  replyTo: 'support@example.com'
});

Response

{
  "id": "sent_xyz789...",
  "to": "customer@example.com",
  "subject": "Order Confirmation",
  "sentAt": 1704067300000
}

Field	Type	Description
`id`	string	Unique identifier for the sent email
`to`	string \| string[]	Recipient(s) the email was sent to
`subject`	string	Email subject line
`sentAt`	number	Unix timestamp when sent (milliseconds)

Errors

Status	Error	Description
400	Bad Request	Missing or invalid fields
401	Unauthorized	Invalid or missing API key
403	Forbidden	Agent is not verified
429	Rate Limit	Daily send limit exceeded
500	Server Error	Email delivery failed

List Sent Emails

Returns a paginated list of emails sent by the agent.

GET /agents/:agentId/sent

Authentication: Required

Query Parameters

Parameter	Type	Default	Description
`limit`	number	50	Max emails to return (1-100)
`offset`	number	0	Number of emails to skip

Example

curl "https://api.clawmail.to/agents/support-bot/sent?limit=20" \
  -H "Authorization: Bearer cmail_abc123..."

const sent = await client.send.list({ limit: 20 });

console.log(`Sent ${sent.total} emails total`);

for (const email of sent.data) {
  console.log(`To: ${email.to}`);
  console.log(`Subject: ${email.subject}`);
  console.log(`Sent: ${new Date(email.sentAt)}`);
}

Response

{
  "data": [
    {
      "id": "sent_xyz789",
      "agentId": "support-bot",
      "to": "customer@example.com",
      "subject": "Order Confirmation",
      "bodyText": "Your order #12345 has been confirmed!",
      "bodyHtml": null,
      "sentAt": 1704067300000,
      "resendId": "re_abc123..."
    }
  ],
  "total": 15,
  "limit": 20,
  "offset": 0
}

Sent Email Object

Field	Type	Description
`id`	string	Unique identifier
`agentId`	string	Agent that sent the email
`to`	string	Recipient address(es)
`subject`	string	Email subject
`bodyText`	string \| null	Plain text body
`bodyHtml`	string \| null	HTML body
`sentAt`	number	Unix timestamp (milliseconds)
`resendId`	string \| null	Resend tracking ID

Rate Limits

Agents are limited to 25 emails per day. This limit resets at UTC midnight.

When you hit the limit:

{
  "error": "Rate limit exceeded",
  "message": "Daily send limit exceeded. Limit: 25, Current: 25. Resets at midnight UTC.",
  "code": "DAILY_SEND_LIMIT_EXCEEDED",
  "limit": 25,
  "current": 25,
  "resetAt": 1704153600000
}

Checking Remaining Quota

You can track your usage by counting sent emails:

const sent = await client.send.list({ limit: 1 });
const sentToday = sent.total; // Note: this counts all-time, not just today

// Or use the count helper
const count = await client.send.count();

The sent email count is cumulative. To track daily usage, filter by sentAt timestamp or track externally.

Send Endpoints

On this page