clawMail Skill

You are an email management agent with multi-account IMAP/SMTP support. You can
fetch, read, search, process, compose, send, reply, forward, move, and manage
emails, drafts, and folders across multiple email accounts.

Multi-Account Model

• - Account profiles: Each account has its own IMAP/SMTP credentials, mailboxes,

fetch limits, archival settings, and processing rules.

• - Default account: One account is designated as the default. Any script invoked

without --account uses the default automatically.

• - SMTP fallback: If an account's SMTP server fails, the system automatically

retries via a configured fallback relay.

• - IMAP Outbox: Messages are staged in a temporary Outbox folder before SMTP

delivery. If SMTP fails, the message stays in Outbox for retry by the heartbeat.

• - Per-account + global rules: Each account has its own rules, plus global rules

that apply to all accounts.

• - OAuth2: Accounts can use OAuth2 (XOAUTH2) authentication instead of passwords.
• Dated-folder archival: archive_mail.py and the heartbeat honor per-account

archive_root/archive_frequency defaults so messages routed to the archive action land in folders such as Archive-202603, Archive-W09, or Archive-20260315.

Security

• - TLS 1.2+: All IMAP and SMTP connections enforce TLS 1.2 or higher.
• Hardened ciphers: Only ECDHE+AESGCM, ECDHE+CHACHA20, DHE+AESGCM, and

DHE+CHACHA20 cipher suites are allowed. Weak ciphers (MD5, RC4, 3DES, DSS) are explicitly blocked.

• - Certificate verification: Hostname checking and certificate validation are

always enabled.

• - RFC 5322 compliance: All outgoing emails include required Date, Message-ID,

and MIME-Version headers automatically.

• - Secure credential storage: Passwords in config support 1Password CLI

(op://vault/item/field), macOS Keychain (keychain://service/account), and environment variables (env://VAR_NAME).

Available Scripts

All scripts are in the scripts/ directory. Run with
python3 scripts/<name>.py from the skill root. Every script accepts
--account <name> to target a specific account.

Core Scripts

Script	Purpose
INLINECODE14	Fetch emails from an IMAP folder
INLINECODE15

Read/render an email by Message-ID; save attachments to disk | | scripts/search_mail.py | Search emails by subject, sender, body, date, flags | | scripts/send_mail.py | Send rich HTML emails via SMTP (Outbox + fallback); attach files | | scripts/compose_mail.py | Compose rich HTML emails from templates; attach files | | scripts/reply_mail.py | Reply to an email with original-message quoting | | scripts/forward_mail.py | Forward an email inline-quoted or with attachments | | scripts/draft_mail.py | Save, list, resume, or send drafts via IMAP Drafts folder | | scripts/process_mail.py | Run emails through the rule-based processing pipeline | | scripts/manage_folders.py | List, create, delete, rename, and move IMAP folders | | scripts/move_mail.py | Move emails between IMAP folders (batch support) | | scripts/heartbeat.py | Run a full heartbeat cycle (drains Outbox, fetches, processes) | | scripts/idle_monitor.py | Monitor a mailbox via IMAP IDLE (push notifications) | | scripts/retry_send.py | Retry sending messages stuck in the IMAP Outbox | | scripts/calendar_invite.py | Compose and send iCalendar meeting invitations | | scripts/mail_merge.py | Batch personalised sends from template + CSV/JSON data | | scripts/thread_mail.py | Group messages into conversation threads | | scripts/archive_mail.py | Auto-archive old messages into dated folders (daily/weekly/monthly/yearly) |

Library Modules

Module	Purpose
INLINECODE32	IMAP client with IDLE, search, folder management, TLS 1.2+
INLINECODE33

SMTP client with TLS 1.2+, RFC 5322, OAuth2, MIME building | | scripts/lib/composer.py | Rich HTML email composer with templates, reply, forward | | scripts/lib/processor.py | Rule-based processing pipeline with webhook actions | | scripts/lib/account_manager.py | Multi-account manager with SMTP fallback and Outbox | | scripts/lib/outbox.py | IMAP Outbox — temporary folder for reliable delivery | | scripts/lib/credential_store.py | Secure credential storage (1Password, Keychain, env) | | scripts/lib/pool.py | Connection pool for IMAP/SMTP reuse | | scripts/lib/send_queue.py | Legacy file-backed send queue (superseded by Outbox) | | scripts/lib/smime.py | S/MIME signing and encryption | | scripts/lib/oauth2.py | OAuth2 (XOAUTH2) token management | | scripts/lib/models.py | Data models (EmailMessage, EmailAddress, etc.) |

Reference Documents

Reference	When to read
INLINECODE44	API overview, all script arguments and output formats
INLINECODE45

Available email templates and template variables | | references/RULES.md | How to configure processing rules | | ROADMAP.md | Feature roadmap and progress tracker |

Quick Start

Fetching Mail

CODEBLOCK0

Sending Rich Emails

Messages are staged in a temporary IMAP Outbox folder, sent via SMTP
(with automatic fallback), then removed from Outbox on success.

CODEBLOCK1

Replying and Forwarding

CODEBLOCK2

Searching Emails

CODEBLOCK3

Working with Drafts

CODEBLOCK4

Outbox & Send Retry

CODEBLOCK5

Heartbeat Cycle

The heartbeat drains each account's Outbox, then fetches and processes mail:

CODEBLOCK6

Archiving Old Messages

CODEBLOCK7

Archiving honors archive_root / archive_frequency settings (defaults: Archive, monthly). The heartbeat and any rule with the archive action move the message into folders named Archive-202603, Archive-W09, or Archive-20260315 based on the configured cadence.

Calendar Invitations

CODEBLOCK8

Mail Merge

CODEBLOCK9

Configuration

Create a config.yaml from assets/config.example.yaml:

CODEBLOCK10

You can also define archive_root (e.g., Archive) and archive_frequency (daily, weekly, monthly, yearly) either globally or per- account. These defaults drive both the archive_mail.py script and the heartbeat's handling of the archive rule action so that archived messages consistently live under folders like Archive-202603, Archive-W09, or Archive-20260315.

Secure Credential Storage

Passwords in config support four backends:

Scheme	Backend	Example
INLINECODE70	1Password CLI	INLINECODE71
INLINECODE72

macOS Keychain | "keychain://imap.gmail.com/alice" |
| env:// | Environment variable | "env://GMAIL_APP_PASSWORD" |
| (plain text) | Literal value | "my-password" (logs a warning) |

OAuth2 Authentication (Gmail, Outlook 365)

For providers that require OAuth2, set auth: oauth2 on the IMAP/SMTP block:

CODEBLOCK11

Legacy Single-Account Config

Flat imap: / smtp: at root is automatically treated as a single account
named "default".