OpenClaw Integration

OpenClaw is an open-source AI personal assistant framework. By integrating SpiderMail, your OpenClaw agents gain the ability to send, receive, read, and reply to emails from real Zoho, Google Workspace, and Outlook mailboxes.

What This Enables

Once installed, your agent can:

Check its inbox for new messages
Read and understand email content
Compose and send professional replies
Search through email history
Manage threads, stars, and labels
Use email templates for consistent branding
Write in markdown (auto-converted to HTML)
Act as a fully autonomous SDR (Sales Development Representative)

The agent's LLM does all classification, tone-matching, and composition — SpiderMail is just the pipe.

How Skills Work

OpenClaw agents discover capabilities through skills — structured markdown files that teach the LLM how to perform specific tasks.

Skill Structure

Each skill is a directory containing:

skills/
  spidermail/
    SKILL.md              # Agent instructions (read by the LLM)
    scripts/
      spidermail.py       # CLI script (executed by the agent)

SKILL.md Format

Every skill file has two parts:

1. YAML Frontmatter — Metadata for skill discovery:

---
name: spidermail
version: 1.1.0
description: Read, send, and reply to emails from assigned mailbox
triggers:
  - /email
  - /mail
  - check email
  - send email
requires_auth: true
requires_brand: true
---

2. Markdown Instructions — How the agent should behave:

# SpiderMail — Email for Agent SDRs

You have your own email mailbox. You can read your inbox,
search for messages, send new emails, and reply to existing ones.

## Available Operations

### 1. Check Inbox
**When the user says:** "check my email", "any new messages?"

```python
result = run("scripts/spidermail.py inbox --unread")

... (detailed instructions for each operation)

### Trigger Discovery

The agent loads all skills at startup and indexes their `triggers`. When a user message matches a trigger (either exact command like `/email` or natural language like "check my email"), the agent loads that skill's instructions.

### Security Model

- **Skills run in sandboxed containers** — scripts cannot access the host system
- **Authentication is per-agent** — each agent has its own credentials
- **API calls are authenticated** — skills use the SpiderIQ API with proper auth tokens
- **No credential exposure** — secrets are injected via environment variables, never hardcoded

## Installation

### 1. Get the Skill

The SpiderMail skill is available from the [opvsHUB skills repository](https://github.com/martinshein/opvsHUB). Clone or download the `skills/spidermail` directory into your OpenClaw skills folder.

Your skill directory should look like:

skills/ spidermail/ SKILL.md scripts/ spidermail.py

### 2. Configure the Agent's Email

Set the `AGENT_EMAIL` environment variable for your agent:

```bash
export AGENT_EMAIL="alice@company.com"

3. Register the Mailbox

Before the agent can use a mailbox, register it with SpiderMail:

curl -X POST https://spideriq.ai/api/v1/mail/mailboxes \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <client_id>:<api_key>:<api_secret>" \
  -d '{
    "email_address": "alice@company.com",
    "display_name": "Alice Smith",
    "provider": "zoho",
    "imap_host": "imap.zoho.com",
    "imap_port": 993,
    "imap_username": "alice@company.com",
    "imap_password": "your-app-password",
    "smtp_host": "smtp.zoho.com",
    "smtp_port": 587,
    "smtp_username": "alice@company.com",
    "smtp_password": "your-app-password"
  }'

4. Test Connectivity

Verify the mailbox can connect:

curl -X POST https://spideriq.ai/api/v1/mail/mailboxes/alice@company.com/test \
  -H "Authorization: Bearer <client_id>:<api_key>:<api_secret>"

Expected response:

{
  "email_address": "alice@company.com",
  "imap_ok": true,
  "smtp_ok": true
}

How It Works

User: "Check my email"
  ↓
OpenClaw Agent (loads SKILL.md, matches trigger)
  ↓
Executes: scripts/spidermail.py inbox --unread
  ↓
API Call: GET /api/v1/mail/inbox?email=...
  ↓
SpiderIQ API → Response
  ↓
Agent formats and presents to user

Read operations (inbox, search, thread) hit the API directly — instant responses.

Write operations (send, reply, forward) are queued and processed within seconds.

Background polling — new inbound emails are fetched via IMAP every 5 minutes automatically.

CLI Reference

Command	Description
`spidermail.py inbox [--unread] [--limit N]`	List inbox messages
`spidermail.py read <id>`	Read full message
`spidermail.py thread <thread_id>`	View conversation thread
`spidermail.py search <query>`	Full-text search
`spidermail.py send <to> <subject> <body> [--template NAME]`	Send new email
`spidermail.py reply <id> <body> [--all] [--template NAME]`	Reply to message
`spidermail.py forward <id> <to> <body>`	Forward message
`spidermail.py star <id>`	Star a message
`spidermail.py unstar <id>`	Unstar a message
`spidermail.py mark-read <id>`	Mark as read
`spidermail.py mark-unread <id>`	Mark as unread
`spidermail.py label <id> <label> [label2 ...]`	Set labels

Email Templates (v2.52.0)

SpiderMail supports Jinja2-based email templates for consistent, professional messaging.

Template Types

Type	Description	Use Case
`signature`	Appended to email body	Professional sign-offs
`header`	Prepended to email body	Branded headers
`layout`	Wraps body with `{{ body }}` slot	Full email structure
`full`	Complete standalone template	Marketing emails

Creating Templates

curl -X POST https://spideriq.ai/api/v1/mail/templates \
  -H "Authorization: Bearer <credentials>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "sdr-signature",
    "template_type": "signature",
    "html_source": "<p>Best regards,<br>{{ sender_name }}<br>{{ company }}</p>"
  }'

Setting Mailbox Defaults

Each mailbox can have a default template automatically applied:

curl -X PATCH https://spideriq.ai/api/v1/mail/mailboxes/alice@company.com \
  -H "Authorization: Bearer <credentials>" \
  -H "Content-Type: application/json" \
  -d '{
    "default_template_name": "sdr-signature",
    "template_variables": {
      "sender_name": "Alice Smith",
      "company": "Acme Corp"
    }
  }'

Agent Usage

Agents use templates in two ways:

Automatic — If a mailbox has a default template, it's applied to all outgoing emails
Explicit — Specify a template name with --template:

python scripts/spidermail.py send bob@example.com "Hello" "Your message" --template "professional-layout"

Markdown Support (v2.52.0)

Agents can write emails in plain markdown — SpiderMail automatically converts to HTML:

python scripts/spidermail.py send bob@example.com "Update" "# Status Update

Here's what we accomplished:

- **Feature A** launched successfully
- Bug fixes deployed
- Performance improved by *30%*

Let me know if you have questions!"

Supported Syntax

Markdown	Result
`bold`	bold
`italic`	italic
`# Heading`	Heading
`- item`	Bullet list
`1. item`	Numbered list
`code`	Inline code
`[link](url)`	Clickable link

Use Cases

Autonomous SDR

"Check my inbox for any prospect replies, read them, and draft thoughtful responses."

The agent checks unread messages, reads each one, understands context from the thread, and composes personalized replies.

Lead Qualification

"Search for emails mentioning 'pricing' or 'demo' and label them as hot leads."

The agent searches, reads relevant messages, and labels them for follow-up.

Email Triage

"Check my email. Summarize what's important and star anything from prospects."

The agent scans the inbox, provides a summary, and manages flags.

Supported Email Providers

Provider	IMAP Host	SMTP Host
Zoho	`imap.zoho.com:993`	`smtp.zoho.com:587`
Google Workspace	`imap.gmail.com:993`	`smtp.gmail.com:587`
Outlook / Office 365	`outlook.office365.com:993`	`smtp.office365.com:587`

Limitations

No attachment support — SpiderMail cannot send or view email attachments
Labels replace, not append — The label command replaces all labels on a message
5-minute polling delay — Inbound emails appear after the next IMAP poll cycle
Plain text primary — HTML is auto-generated from markdown when needed

Resources

SpiderMail API Reference — Job submission docs
Email Guide — Setup and usage guide
opvsHUB Skills Repository — All available skills
OpenClaw GitHub — Agent framework

What This Enables​

How Skills Work​

Skill Structure​

SKILL.md Format​

3. Register the Mailbox​

4. Test Connectivity​

How It Works​

CLI Reference​

Email Templates (v2.52.0)​

Template Types​

Creating Templates​

Setting Mailbox Defaults​

Agent Usage​

Markdown Support (v2.52.0)​

Supported Syntax​

Use Cases​

Autonomous SDR​

Lead Qualification​

Email Triage​

Supported Email Providers​

Limitations​

Resources​