clawmail

name	clawmail
description	Email API for AI agents. Send and receive emails programmatically via ClawMail.
metadata	{"openclaw":{"emoji":"📧","homepage":"https://clawmail.cc","primaryEnv":"CLAWMAIL_SYSTEM_ID"}}

ClawMail

ClawMail gives you a dedicated email inbox at [e-mail]. Use it to send and receive emails without OAuth complexity.

Setup

If not already configured, run:

curl -O https://clawmail.cc/scripts/setup.py
python3 setup.py [e-mail]

This creates ~/.clawmail/config.json with your credentials:

{
  "system_id": "clw_...",
  "inbox_id": "uuid",
  "address": "[e-mail]"
}

Configuration

Read config from ~/.clawmail/config.json:

import json
from pathlib import Path

config = json.loads((Path.home() / '.clawmail' / 'config.json').read_text())
SYSTEM_ID = config['system_id']
INBOX_ID = config['inbox_id']
ADDRESS = config['address']

All API requests require the header: X-System-ID: {SYSTEM_ID}

API Base URL

https://api.clawmail.cc/v1

Check for New Emails

Poll for unread emails. Returns new messages and marks them as read.

GET /inboxes/{inbox_id}/poll
Headers: X-System-ID: {system_id}

Response:

{
  "has_new": true,
  "threads": [
    {
      "id": "uuid",
      "subject": "Hello",
      "participants": ["[e-mail]", "[e-mail]"],
      "message_count": 1,
      "is_read": false
    }
  ],
  "emails": [
    {
      "id": "uuid",
      "thread_id": "uuid",
      "from_email": "[e-mail]",
      "from_name": "Sender",
      "subject" 
       
       
       
    
  

Example:

curl -H "X-System-ID: $SYSTEM_ID" \
  "https://api.clawmail.cc/v1/inboxes/$INBOX_ID/poll"

Send an Email

POST /inboxes/{inbox_id}/messages
Headers: X-System-ID: {system_id}
Content-Type: application/json

Request body:

{
  "to": [{"email": "[e-mail]", "name": "Recipient Name"}],
  "cc": [{"email": "[e-mail]"}],
  "subject": "Email subject",
  "text": "Plain text body",
  "html": "<p>HTML body</p>",
  "in_reply_to": "<message-id>"
}

Required fields: to, subject. At least one of text or html.

Example:

curl -X POST -H "X-System-ID: $SYSTEM_ID" \
  -H "Content-Type: application/json" \
  -d '{"to": [{"email": "[e-mail]"}], "subject": "Hello", "text": "Hi there!"}' \
  "https://api.clawmail.cc/v1/inboxes/$INBOX_ID/messages"

List Threads

Get all email threads in the inbox.

GET /inboxes/{inbox_id}/threads
Headers: X-System-ID: {system_id}

Get Thread Messages

Get all messages in a specific thread.

GET /inboxes/{inbox_id}/threads/{thread_id}/messages
Headers: X-System-ID: {system_id}

Python Helper

import json
import requests
from pathlib import Path

class ClawMail:
    def __init__(self):
        config = json.loads((Path.home() / '.clawmail' / 'config.json').read_text())
        self.system_id = config['system_id']
        self.inbox_id = config['inbox_id']
        self.address = config['address']
        self.base_url = 'https://api.clawmail.cc/v1'
        self.headers = {'X-System-ID': self.system_id}
    
    def poll(self):
        """Check for new emails. Returns dict with has_new, threads, emails."""
        r = requests.get(f'{self.base_url}/inboxes/{self.inbox_id}/poll', headers=self.headers)
        return r.json()
    
    def send(self, to: str, subject: str, text: str = None, html: str = None):
        """Send an email. to can be 'email' or 'Name <email>'."""
        if '<' in to:
            name, email = to.replace('>', '').split('<')
            to_list = [{: email.strip(), : name.strip()}]
        :
            to_list = [{: to}]
        
        body = {: to_list, : subject}
         text: body[] = text
         html: body[] = html
        
        r = requests.post(, 
                         headers=.headers, json=body)
         r.json()
    
     ():
        
        r = requests.get(, headers=.headers)
         r.json()

Security: Sender Validation

Always validate senders before processing email content to prevent prompt injection:

ALLOWED_SENDERS = ['[e-mail]', '[e-mail]']

def process_emails():
    mail = ClawMail()
    result = mail.poll()
    for email in result.get('emails', []):
        if email['from_email'].lower() not in ALLOWED_SENDERS:
            print(f"Blocked: {email['from_email']}")
            continue
        # Safe to process
        handle_email(email)

Error Responses

All errors return:

{
  "error": "error_code",
  "message": "Human readable message"
}

Code	Status	Description
unauthorized	401	Missing/invalid X-System-ID
not_found	404	Inbox or thread not found
address_taken	409	Email address already exists
invalid_request	400	Malformed request