Quick Start

Get up and running with ClawMail in 5 steps. By the end, you'll have an agent with its own email address that can send and receive emails.

Prerequisites

A deployed ClawMail API (Cloudflare Workers)
Node.js 18+ (for TypeScript examples)
Your API base URL (e.g., https://api.clawmail.to)

Step 1: Install the Client

npm install @clawmail/client

pnpm add @clawmail/client

yarn add @clawmail/client

Step 2: Create an Agent

Create your first agent. This gives you a unique email address and API key.

curl -X POST https://api.clawmail.to/agents \
  -H "Content-Type: application/json" \
  -d '{
    "id": "my-first-agent",
    "name": "My First Agent"
  }'

Response:

{
  "agent": {
    "id": "my-first-agent",
    "email": "my-first-agent@clawmail.to",
    "name": "My First Agent",
    "createdAt": 1704067200000
  },
  "apiKey": "mltk_abc123..."
}

import { ClawMailClient } from '@clawmail/client';

// Create an unauthenticated client for agent creation
const client = new ClawMailClient({
  baseUrl: 'https://api.clawmail.to'
});

// Create a new agent
const result = await client.agents.create({
  id: 'my-first-agent',
  name: 'My First Agent'
});

console.log('Email:', result.agent.email);
console.log('API Key:', result.apiKey);

Save your API key! It's only shown once during creation. If lost, you'll need to rotate to a new key.

Step 3: Check Your Email Address

Your agent now has an email address. Anyone can send emails to this address.

curl https://api.clawmail.to/agents/my-first-agent \
  -H "Authorization: Bearer mltk_abc123..."

Response:

{
  "id": "my-first-agent",
  "email": "my-first-agent@clawmail.to",
  "name": "My First Agent",
  "createdAt": 1704067200000
}

// Create an authenticated client
const client = new ClawMailClient({
  baseUrl: 'https://api.clawmail.to',
  apiKey: 'mltk_abc123...',
  agentId: 'my-first-agent'
});

const agent = await client.agents.get();
console.log('Email address:', agent.email);
// Output: my-first-agent@clawmail.to

Step 4: Send Your First Email

Send an email from your agent to any address.

curl -X POST https://api.clawmail.to/agents/my-first-agent/send \
  -H "Authorization: Bearer mltk_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "recipient@example.com",
    "subject": "Hello from ClawMail!",
    "text": "This is my first email sent via ClawMail."
  }'

Response:

{
  "id": "sent_xyz789...",
  "sentAt": 1704067300000
}

const result = await client.send.email({
  to: 'recipient@example.com',
  subject: 'Hello from ClawMail!',
  text: 'This is my first email sent via ClawMail.'
});

console.log('Email sent!', result.id);

Step 5: Read Incoming Emails

Check your inbox for any emails sent to your agent's address.

curl https://api.clawmail.to/agents/my-first-agent/emails \
  -H "Authorization: Bearer mltk_abc123..."

Response:

{
  "data": [
    {
      "id": "ml_abc123",
      "from": {
        "address": "sender@example.com",
        "name": "John Doe"
      },
      "subject": "Hello!",
      "bodyText": "This is a test email.",
      "receivedAt": 1704067400000,
      "isRead": false,
      "folder": "inbox"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

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

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

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

  // Mark as read and archive
  await client.emails.archive(email.id);
}

Next Steps

You now have a working ClawMail agent! Here's what to explore next:

API Reference - Full REST API documentation
TypeScript Client - Complete SDK reference
Error Handling - Handle errors gracefully

Full Working Example

Here's a complete script that creates an agent and processes emails:

import { ClawMailClient } from '@clawmail/client';

const BASE_URL = 'https://api.clawmail.to';

async function main() {
  // 1. Create an agent
  const unauthClient = new ClawMailClient({ baseUrl: BASE_URL });

  const { agent, apiKey } = await unauthClient.agents.create({
    id: 'demo-agent',
    name: 'Demo Agent'
  });

  console.log('Created agent:', agent.email);

  // 2. Create authenticated client
  const client = new ClawMailClient({
    baseUrl: BASE_URL,
    apiKey,
    agentId: agent.id
  });

  // 3. Send a test email
  await client.send.email({
    to: 'test@example.com',
    subject: 'Hello from Demo Agent',
    text: 'This email was sent by my ClawMail agent!'
  });

  console.log('Sent test email');

  // 4. Check inbox (you'd need to receive an email first)
  const inbox = await client.emails.list({ folder: 'inbox' });
  console.log(`Inbox has ${inbox.total} emails`);

  // 5. Process any emails
  for (const email of inbox.data) {
    console.log(`Processing: ${email.subject}`);

    // Reply to the email
    await client.send.reply(email, {
      text: 'Thanks for your email! This is an automated reply.'
    });

    // Archive after processing
    await client.emails.archive(email.id);
  }
}

main().catch(console.error);

Quick Start

On this page