Documentation Index

Fetch the complete documentation index at: https://mintlify.com/zeroclaw-labs/zeroclaw/llms.txt

Use this file to discover all available pages before exploring further.

​

Email Channel

​

Overview

• Channel Name: email
• Transport: IMAP (receive) + SMTP (send)
• Authentication: Username/password
• Public Port Required: No
• Supports: Text, HTML, attachments, allowlist filtering

​

Configuration

​

Required Settings

[channels_config.email]
imap_host = "imap.example.com"
smtp_host = "smtp.example.com"
username = "bot@example.com"
password = "your-password"
from_address = "bot@example.com"
allowed_senders = ["*"]

​

Complete Configuration

[channels_config.email]
imap_host = "imap.example.com"
imap_port = 993  # Default: 993 (TLS)
imap_folder = "INBOX"  # Default: INBOX
smtp_host = "smtp.example.com"
smtp_port = 465  # Default: 465 (TLS)
smtp_tls = true  # Default: true
username = "bot@example.com"
password = "your-password"
from_address = "bot@example.com"
idle_timeout_secs = 1740  # 29 minutes (RFC 2177 recommendation)
allowed_senders = ["user@example.com", "@company.com"]

[channels_config.email.imap_id]
enabled = true  # Send RFC 2971 ID metadata
name = "zeroclaw"
version = "0.1.7"
vendor = "zeroclaw-labs"

​

Provider-Specific Examples

​

Gmail

imap_host = "imap.gmail.com"
imap_port = 993
smtp_host = "smtp.gmail.com"
smtp_port = 465
username = "your-email@gmail.com"
password = "app-specific-password"  # Not your Google password!

1. Go to Google Account settings
2. Security → 2-Step Verification
3. App passwords → Generate new password
4. Use generated password in config

​

Outlook/Office 365

imap_host = "outlook.office365.com"
imap_port = 993
smtp_host = "smtp.office365.com"
smtp_port = 587  # Note: 587 for STARTTLS
smtp_tls = true
username = "your-email@outlook.com"
password = "your-password"

​

Yahoo Mail

imap_host = "imap.mail.yahoo.com"
imap_port = 993
smtp_host = "smtp.mail.yahoo.com"
smtp_port = 465
username = "your-email@yahoo.com"
password = "app-password"  # Generate in Yahoo Account Security

​

NetEase (163.com / 126.com)

imap_host = "imap.163.com"  # or imap.126.com
imap_port = 993
smtp_host = "smtp.163.com"  # or smtp.126.com
smtp_port = 465
username = "your-email@163.com"
password = "authorization-code"  # Not your login password!

[channels_config.email.imap_id]
enabled = true  # Required for NetEase!
name = "zeroclaw"
version = "0.1.7"
vendor = "zeroclaw-labs"

​

Features

​

IMAP IDLE (Push Mode)

1. Connect to IMAP server with TLS
2. Authenticate with username/password
3. Select mailbox (default: INBOX)
4. Check for existing unseen messages
5. Enter IDLE mode
6. Server pushes notifications when new mail arrives
7. Fetch and process new messages
8. Re-enter IDLE

• Default: 1740 seconds (29 minutes)
• RFC 2177 recommends clients restart IDLE every 29 minutes
• Automatic reconnection on timeout
• Exponential backoff on connection errors

• Instant delivery (no delay)
• Lower server load
• Lower bandwidth usage
• Standard protocol support

​

Allowlist Filtering

​

Empty List (Deny All)

allowed_senders = []

​

Wildcard (Allow All)

allowed_senders = ["*"]

​

Specific Email Addresses

allowed_senders = [
    "alice@example.com",
    "bob@company.org"
]

​

Domain Matching

allowed_senders = [
    "@example.com",      # With @ prefix
    "company.org"        # Without @ prefix
]

• user@example.com ✔️
• admin@example.com ✔️
• anyone@company.org ✔️

​

Mixed Rules

allowed_senders = [
    "ceo@company.com",   # Specific user
    "@trusted.org",      # Entire domain
    "partners.net"       # Another domain
]

​

Message Processing

​

Text Extraction

1. Plain text body (MIME text/plain)
2. HTML body (MIME text/html) - HTML tags stripped
3. Text attachments
4. Fallback: "(no readable content)"

<p>Hello <strong>world</strong></p>
→ "Hello world"

​

Subject Handling

Subject: Question about ZeroClaw

How do I configure email channel?

​

IMAP ID Extension (RFC 2971)

[channels_config.email.imap_id]
enabled = true
name = "zeroclaw"
version = "0.1.7"
vendor = "zeroclaw-labs"

• Some providers (NetEase) require it
• Helps with debugging
• Provider can optimize for known clients

• name - Client application name
• version - Client version
• vendor - Vendor/organization name

​

Attachment Support

• Text attachments inlined: [Attachment: file.txt]\ncontent
• Other MIME types skipped

​

Reply Threading

# Incoming: alice@example.com
# Reply target: alice@example.com

​

Implementation Details

​

Source Location

​

Key Components

​

EmailChannel Struct

pub struct EmailChannel {
    pub config: EmailConfig,
    seen_messages: Arc<Mutex<HashSet<String>>>,
}

​

EmailConfig

pub struct EmailConfig {
    pub imap_host: String,
    pub imap_port: u16,
    pub imap_folder: String,
    pub smtp_host: String,
    pub smtp_port: u16,
    pub smtp_tls: bool,
    pub username: String,
    pub password: String,
    pub from_address: String,
    pub idle_timeout_secs: u64,
    pub allowed_senders: Vec<String>,
    pub imap_id: EmailImapIdConfig,
}

​

Connection Flow

​

IMAP (Receive)

1. TCP Connect: TcpStream::connect(host:port)
2. TLS Handshake: rustls with system root certificates
3. IMAP Greeting: Wait for server hello
4. LOGIN: LOGIN username password
5. IMAP ID: Send RFC 2971 metadata (if enabled)
6. SELECT: Open mailbox (INBOX)
7. SEARCH: Find unseen messages: UID SEARCH UNSEEN
8. FETCH: Download message bodies: UID FETCH ... RFC822
9. STORE: Mark as seen: UID STORE ... +FLAGS (\Seen)
10. IDLE: Enter idle mode: IDLE
11. Wait: Block until server notification or timeout
12. DONE: Exit idle: DONE
13. Repeat from step 7

​

SMTP (Send)

1. TCP Connect: (TLS port 465 or STARTTLS port 587)
2. TLS: Establish encrypted connection
3. EHLO: Identify client
4. AUTH: Authenticate with credentials
5. MAIL FROM: Set sender
6. RCPT TO: Set recipient
7. DATA: Send message body
8. QUIT: Close connection

​

Message Deduplication

• Tracks seen message IDs in memory: HashSet<String>
• Message ID from Message-ID header or generated UUID
• Persists across IDLE reconnections
• Not persisted to disk (resets on restart)

• Marks all unseen messages in inbox as seen
• Processes them once
• Future restarts see no unseen messages

​

Error Recovery

1. Log error with backoff counter
2. Wait 1 second
3. Exponential backoff: 2s, 4s, 8s, …, max 60s
4. Reconnect from scratch
5. Resume listening

1. Exit IDLE cleanly with DONE
2. Check for new messages
3. Re-enter IDLE

​

Error Handling

​

Common Errors

IMAP login failed: authentication failure

• Verify username/password
• Check if app passwords required
• Enable IMAP access in provider settings

IMAP connection timeout

• Check firewall rules
• Verify IMAP port (993 for TLS)
• Test with telnet: openssl s_client -connect imap.example.com:993

TLS handshake failed: certificate verify failed

• Update system root certificates
• Check system time (affects cert validation)

IMAP error: command not permitted

[channels_config.email.imap_id]
enabled = true

IMAP IDLE error: command not recognized

​

Runtime Commands

​

Best Practices

1. Use App Passwords: For Gmail, Yahoo, etc.
2. Allowlist Domains: Use @company.com for organizations
3. Dedicated Account: Create separate email for bot
4. Monitor Logs: Watch for connection errors
5. IMAP ID: Enable for NetEase and other providers requiring it
6. TLS Always: Never disable smtp_tls

​

Troubleshooting

​

No Messages Received

echo "Test" | mail -s "Test" bot@example.com

allowed_senders = ["your-email@example.com"]

RUST_LOG=debug zeroclaw daemon 2>&1 | grep -i email

• Email IDLE listening on INBOX (instant push enabled)
• Blocked email from ...
• Email poll failed:

openssl s_client -connect imap.example.com:993
# Then manually:
# A1 LOGIN username password
# A2 SELECT INBOX
# A3 SEARCH UNSEEN

​

Messages Not Sending

• Port 465: SMTP over TLS (smtps)
• Port 587: SMTP with STARTTLS

telnet smtp.example.com 465

# Using swaks (SMTP test tool)
swaks --to user@example.com \
      --from bot@example.com \
      --server smtp.example.com:465 \
      --auth LOGIN \
      --auth-user bot@example.com \
      --auth-password 'your-password' \
      --tls

​

IDLE Keeps Disconnecting

idle_timeout_secs = 900  # 15 minutes

idle_timeout_secs = 300  # 5 minutes

​

Performance

​

Message Latency

• Delivery: <5 seconds (instant push)
• Processing: Depends on agent/provider

• Poll interval: Configurable (default: 60s)
• Latency: 0-60 seconds

​

Optimization Tips

1. IDLE Over Polling: Always preferred
2. Reduce Timeout: Lower for flaky networks
3. Dedicated Mailbox: Use separate folder if needed
4. Allowlist: Reduces processing overhead

​

Security

​

Credential Protection

• Stored in config file (protect with permissions: chmod 600)
• Never logged
• Transmitted over TLS only

​

TLS Configuration

• IMAP: Port 993 (implicit TLS)
• SMTP: Port 465 (implicit TLS) or 587 (STARTTLS)
• Uses system root certificates (rustls + webpki-roots)
• Certificate validation always enabled

​

Allowlist Enforcement

• Checked before any processing
• Case-insensitive for email addresses
• Logged when blocked:
  Blocked email from untrusted@example.com
  

​

See Also

• Channels Reference
• RFC 3501 - IMAP4rev1
• RFC 2177 - IMAP IDLE
• RFC 2971 - IMAP ID Extension
• RFC 5321 - SMTP