nullclaw-channel-imap-connector

nullclaw-channel-imap-connector is a companion repository for running bidirectional email as a channels.external plugin in nullclaw.

It keeps IMAP/SMTP transport code, HTML sanitization, attachment handling, and mailbox-specific helper workflows out of nullclaw core while still using the generic ExternalChannel JSON-RPC/stdio contract.

What This Repo Contains

• nullclaw-plugin-imap-connector Long-lived JSON-RPC external channel plugin for inbound IMAP polling and outbound SMTP delivery.
• imap_connector/cli.py One-shot mailbox CLI for listing, reading, searching, moving, replying, and sending emails outside the channel runtime.
• scripts/email_tracker.py SQLite-backed delegated-thread tracker for unknown sender workflows.
• skill/ Companion skill instructions for using the CLI and tracker from Codex/nullclaw.

Install

python3 -m pip install -r requirements.txt
chmod +x ./nullclaw-plugin-imap-connector

nullclaw Config

{
  "channels": {
    "external": {
      "accounts": {
        "mailbox": {
          "runtime_name": "imap_connector",
          "transport": {
            "command": "/absolute/path/to/nullclaw-channel-imap-connector/nullclaw-plugin-imap-connector",
            "timeout_ms": 10000
          },
          "config": {
            "imap": {
              "host": "imap.example.com",
              "port": 993,
              "username": "agent@example.com",
              "password": "YOUR_APP_PASSWORD",
              "tls": true,
              "folder": "INBOX"
            },
            "smtp": {
              "host": "smtp.example.com",
              "port": 587,
              "username": "agent@example.com",
              "password": "YOUR_APP_PASSWORD",
              "tls": true
            },
            "from_address": "agent@example.com",
            "allow_from": ["*@your-company.com"],
            "poll_interval_secs": 60,
            "max_body_length": 50000,
            "attachment_save_dir": "workspace/docs",
            "attachment_extensions": [".pdf", ".docx"],
            "attachment_max_bytes": 20971520,
            "state_file": "imap-connector-state.json"
          }
        }
      }
    }
  }
}

Plugin Behavior

• polls IMAP for unseen mail
• emits inbound_message notifications with a stable per-sender session_key
• wraps email body in untrusted markers before it reaches the agent
• stores a reply target token in chat_id, so normal channel replies become threaded SMTP replies
• suppresses outbound delivery when the reply starts with [NO_REPLY]
• saves allowed attachments to disk and includes the saved paths in the prompt

Companion CLI

The CLI is separate from the long-lived channel runtime. Use it for mailbox operations that do not fit the generic channel contract.

Example:

echo '{"command":"list_emails","args":{"folder":"INBOX","limit":10},"credentials":{"imap":{"host":"imap.example.com","port":993,"username":"agent@example.com","password":"YOUR_APP_PASSWORD","tls":true}}}' | python3 -m imap_connector.cli

Supported commands:

• list_folders
• list_emails
• read_email
• search_emails
• move_email
• mark_read
• create_folder
• get_thread
• send_email
• reply_email

Validation

python3 -m pytest