Email Gateway

How It Works

The email gateway polls an IMAP inbox every 30 seconds. When it finds a new message, it routes it to the agent. When the agent completes, it sends the full reply via SMTP. Email is batch (no streaming) — the full response is sent as a single reply.

Thread continuity is maintained via In-Reply-To / References headers — replies to the same email thread are sent to the same opencode session.

Configuration

# IMAP (incoming)
IMAP_HOST=imap.gmail.com
IMAP_PORT=993          # 993 = IMAPS (TLS)
IMAP_USER=agent@yourcompany.com
IMAP_PASSWORD=app-password-here

# SMTP (outgoing)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587          # 587 = STARTTLS
SMTP_USER=agent@yourcompany.com
SMTP_PASSWORD=app-password-here

Gmail Setup

1. Enable IMAP in Gmail Settings → Forwarding and POP/IMAP
2. Create an App Password (not your regular password): Google Account → Security → 2-Step Verification → App passwords
3. Use the app password for both IMAP_PASSWORD and SMTP_PASSWORD

Microsoft 365 Setup

1. In Azure AD → App registrations → create an app with IMAP.AccessAsUser.All and SMTP.Send permissions
2. Use OAuth2 credentials or an app password from Exchange admin

Start the Gateway

docker compose --profile email up -d

Usage

Send an email to your gateway address (e.g. agent@yourcompany.com). The agent replies to the same thread.

To: agent@yourcompany.com
Subject: Q2 Pipeline Analysis

Please analyse our Q2 sales pipeline and identify the top 3 deals at risk.

Troubleshooting

Symptom	Fix
No replies received	Check SMTP_* credentials and port
Gateway not picking up emails	Verify IMAP_* credentials; check IMAP is enabled on the mailbox
Duplicate responses	References header missing from client — set IMAP_DEDUP_WINDOW=5m