<!-- source: https://deepwiki.com/qhkm/zeptoclaw/7.6-email-integration -->

# Email Integration

- src/channels/email_channel.rs
- src/peripherals/i2c.rs
- src/peripherals/mod.rs
- src/peripherals/rpi_i2c.rs
- src/peripherals/serial.rs
- src/tools/google.rs

This page documents the email channel implementation, which provides bidirectional email communication via IMAP IDLE (inbound) and SMTP (outbound). The email channel is feature-gated and requires building with `--features channel-email`.

For general channel architecture and the `Channel` trait, see [Channel Architecture](/qhkm/zeptoclaw/7.1-channel-architecture). For configuration file structure, see [Configuration File Structure](/qhkm/zeptoclaw/5.1-configuration-file-structure).

## Architecture Overview

The email channel uses two separate protocols for bidirectional communication: IMAP IDLE for receiving messages (push-based) and SMTP for sending messages. This avoids the need for a public webhook endpoint.

**Email Channel Architecture**

```

```

**Sources:** [src/channels/email_channel.rs60-92](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/email_channel.rs#L60-L92) [src/channels/email_channel.rs160-255](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/email_channel.rs#L160-L255) [src/channels/email_channel.rs474-536](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/email_channel.rs#L474-L536)

## Feature Gate

The email channel is **optional** and only compiles when the `channel-email` feature is enabled. This reduces binary size and dependency count for deployments that don't need email integration.

Without the feature, `EmailChannel::start()` and `EmailChannel::send()` return a clear error indicating the requirement.

**Sources:** [src/channels/email_channel.rs1-8](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/email_channel.rs#L1-L8) [src/channels/email_channel.rs388-395](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/email_channel.rs#L388-L395) [src/channels/email_channel.rs463-471](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/email_channel.rs#L463-L471)

## Configuration

The email channel is configured via the `channels.email` section. The configuration is mapped to the `EmailConfig` struct.

**Sources:** [src/channels/email_channel.rs9-23](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/email_channel.rs#L9-L23) [src/channels/email_channel.rs81-85](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/email_channel.rs#L81-L85)

## IMAP IDLE (Inbound Messages)

The inbound path uses IMAP IDLE to receive push notifications when new mail arrives, avoiding constant polling.

**IMAP Connection Flow**

```

```

**Sources:** [src/channels/email_channel.rs160-191](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/email_channel.rs#L160-L191) [src/channels/email_channel.rs196-255](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/email_channel.rs#L196-L255)

### Message Processing Pipeline

When new mail is detected, the channel fetches and processes `UNSEEN` messages.

**Message Processing Steps**

```

```

**Key Implementation Details:**

1. Deduplication : The seen_ids HashSet is checked before allowlist validation to prevent repeated logs for blocked senders. src/channels/email_channel.rs 319-326
2. Plain Text Extraction : The extract_plain_text function prefers body_text(0) . If unavailable, it falls back to body_html(0) and uses strip_html . src/channels/email_channel.rs 131-137
3. HTML Stripping : A naive tag stripper strip_html removes content between < and > brackets and joins the remaining whitespace. src/channels/email_channel.rs 140-152
4. Attachments : Extracts image attachments (MIME type image/* ) up to 20 MB and converts them to MediaAttachment . src/channels/email_channel.rs 343-365

**Sources:** [src/channels/email_channel.rs258-374](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/email_channel.rs#L258-L374) [src/channels/email_channel.rs117-139](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/email_channel.rs#L117-L139)

## SMTP (Outbound Messages)

Outbound messages are sent via SMTP using `lettre`'s `AsyncSmtpTransport`.

**Outbound Send Flow**

```

```

**Subject Line Parsing:**
The `send` method attempts to split the message body at the first double-newline. If the first part starts with `Subject:`, it is extracted as the email subject. Otherwise, it defaults to `ZeptoClaw Message`. [src/channels/email_channel.rs480-492](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/email_channel.rs#L480-L492)

**Sources:** [src/channels/email_channel.rs474-536](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/email_channel.rs#L474-L536)

## Allowlist Pattern Matching

The `is_sender_allowed` method applies rules in a specific order to determine if an inbound `From` header should be processed.

**Evaluation Logic:**

1. If allowed_senders is empty, check deny_by_default . src/channels/email_channel.rs 107-109
2. Check for "*" wildcard. src/channels/email_channel.rs 111-113
3. Iterate through patterns: If pattern starts with @ , use ends_with . src/channels/email_channel.rs 117-118 If pattern contains @ , use eq_ignore_ascii_case . src/channels/email_channel.rs 119-120 Otherwise, append @ to pattern and use ends_with . src/channels/email_channel.rs 122

**Sources:** [src/channels/email_channel.rs104-125](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/email_channel.rs#L104-L125)

## Google Workspace Integration

While the `EmailChannel` provides a generic IMAP/SMTP implementation, ZeptoClaw also includes a `GoogleTool` for advanced Gmail operations via the Google Workspace API. This tool allows the agent to search, read, send, and reply to emails using OAuth tokens.

**Key Gmail Actions in GoogleTool:**

- gmail_search : Search messages using Gmail query syntax. src/tools/google.rs 87
- gmail_read : Fetch full message content by ID. src/tools/google.rs 88
- gmail_send : Send new messages (marked as dangerous). src/tools/google.rs 89
- gmail_reply : Reply to existing threads (marked as dangerous). src/tools/google.rs 90

**Sources:** [src/tools/google.rs20-38](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/google.rs#L20-L38) [src/tools/google.rs81-174](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/google.rs#L81-L174)

## Reconnection and Error Handling

The IMAP IDLE loop runs in a dedicated task spawned via `tokio::spawn`.

**Reconnection Logic**

```

```

**Key Points:**

- Uses exponential backoff (starting at 1s, capping at 60s) for connection failures. src/channels/email_channel.rs 410-444
- The running AtomicBool allows for graceful shutdown when stop() is called. src/channels/email_channel.rs 452-455
- Each session reset clears the local backoff timer. src/channels/email_channel.rs 430

**Sources:** [src/channels/email_channel.rs401-456](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/email_channel.rs#L401-L456)
