Getting Started: Give Your AI Agent an Email in 5 Minutes

This tutorial walks you through giving your AI agent its own email address using ClawAIMail. By the end, your agent will be able to create inboxes, send messages, and read incoming email, all through a simple API or MCP integration.

We will cover three paths: using the REST API directly with Node.js, using the REST API with Python, and setting up the MCP server for Claude or Cursor.

Prerequisites

• A ClawAIMail account (sign up free)
• Your API key from the ClawAIMail dashboard
• Node.js 18+ or Python 3.8+ (for the code examples)

1 Get Your API Key

After signing up at clawaimail.com, navigate to the dashboard and find your API key in the settings section. Copy it and store it securely. You will use this key to authenticate all API requests.

# Store your API key as an environment variable
export CLAWAIMAIL_API_KEY="your_api_key_here"

2 Create an Inbox

The first thing your agent needs is an email address. A single API call creates a new inbox with a routable email address.

Node.js

const response = await fetch('https://api.clawaimail.com/v1/inboxes', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.CLAWAIMAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'support-agent',
    domain: 'yourdomain.com', // optional: use a custom domain
  }),
});

const inbox = await response.json();
console.log(`Inbox created: ${inbox.email_address}`);
// Output: Inbox created: support-agent@yourdomain.com

Python

import os
import requests

api_key = os.environ["CLAWAIMAIL_API_KEY"]

response = requests.post(
    "https://api.clawaimail.com/v1/inboxes",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json={
        "name": "support-agent",
        "domain": "yourdomain.com",  # optional
    },
)

inbox = response.json()
print(f"Inbox created: {inbox['email_address']}")
# Output: Inbox created: support-agent@yourdomain.com

3 Send an Email

Once your agent has an inbox, it can send emails to anyone.

Node.js

const sendResponse = await fetch(
  `https://api.clawaimail.com/v1/inboxes/${inbox.id}/messages`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.CLAWAIMAIL_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      to: 'customer@example.com',
      subject: 'Your support request #1234',
      body: 'Hi! I have reviewed your request and here is what I found...',
    }),
  }
);

const message = await sendResponse.json();
console.log(`Message sent: ${message.id}`);

Python

send_response = requests.post(
    f"https://api.clawaimail.com/v1/inboxes/{inbox['id']}/messages",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json={
        "to": "customer@example.com",
        "subject": "Your support request #1234",
        "body": "Hi! I have reviewed your request and here is what I found...",
    },
)

message = send_response.json()
print(f"Message sent: {message['id']}")

4 Read Incoming Email

Your agent can poll for new messages or use webhooks. Here is the polling approach.

Node.js

const messagesResponse = await fetch(
  `https://api.clawaimail.com/v1/inboxes/${inbox.id}/messages?status=unread`,
  {
    headers: {
      'Authorization': `Bearer ${process.env.CLAWAIMAIL_API_KEY}`,
    },
  }
);

const messages = await messagesResponse.json();

for (const msg of messages.data) {
  console.log(`From: ${msg.from}`);
  console.log(`Subject: ${msg.subject}`);
  console.log(`Body: ${msg.body}`);
  // Process the email with your agent logic here
}

Python

messages_response = requests.get(
    f"https://api.clawaimail.com/v1/inboxes/{inbox['id']}/messages?status=unread",
    headers={"Authorization": f"Bearer {api_key}"},
)

messages = messages_response.json()

for msg in messages["data"]:
    print(f"From: {msg['from']}")
    print(f"Subject: {msg['subject']}")
    print(f"Body: {msg['body']}")
    # Process the email with your agent logic here

5 Set Up MCP for Claude and Cursor

If you are using an MCP-compatible AI platform like Claude or Cursor, you can skip the code above entirely. ClawAIMail's built-in MCP server lets your AI agent use email as a native tool.

Install the MCP Server

npm install -g @clawaimail/mcp-server

Configure for Claude Desktop

Add the following to your Claude Desktop MCP configuration file (claude_desktop_config.json):

{
  "mcpServers": {
    "clawaimail": {
      "command": "npx",
      "args": ["@clawaimail/mcp-server"],
      "env": {
        "CLAWAIMAIL_API_KEY": "your_api_key_here"
      }
    }
  }
}

Configure for Cursor

Add the same configuration to your Cursor MCP settings file (.cursor/mcp.json in your project root):

{
  "mcpServers": {
    "clawaimail": {
      "command": "npx",
      "args": ["@clawaimail/mcp-server"],
      "env": {
        "CLAWAIMAIL_API_KEY": "your_api_key_here"
      }
    }
  }
}

What Your Agent Can Do via MCP

Once the MCP server is connected, your AI agent has access to these email tools:

• create_inbox -- Create a new email address on the fly
• list_inboxes -- See all available inboxes
• send_email -- Send an email from any inbox
• read_emails -- Fetch and read messages from an inbox
• search_emails -- Search messages by sender, subject, or content
• delete_email -- Remove messages from an inbox

Your agent can now send emails, read replies, and manage inboxes using natural language. For example, you could tell Claude: "Check my support inbox for new messages and draft replies to any unanswered questions."

Next Steps

You now have everything you need to give your AI agent full email capabilities. Here are some ideas for what to build next:

• Customer support agent -- Monitor an inbox, classify incoming messages, and draft responses automatically
• Sales outreach agent -- Send personalized emails to prospects and handle replies
• Notification system -- Send alerts when your monitoring agent detects important events
• Workflow automation -- Trigger downstream actions when specific emails arrive
• Account creation agent -- Sign up for services, receive verification emails, and complete registration

Check out the ClawAIMail documentation for the full API reference, webhook configuration, custom domain setup, and advanced features.