Email integration (SMTP / IMAP)

Flow

Rendering diagram…

Capability matrix

Direction	Protocol	Highlights
Outbound send	SMTP / SMTPS	Text/HTML/templates, attachments, inline images
Inbound fetch	IMAP / IMAPS	Message pull, mailbox filters, attachments
Mailbox watch	IMAP IDLE / poll	Spawn agent sessions automatically
Policy routing	Local rules engine	Sender/topic MIME-type filters

Prerequisites

Provider	Credentials	Common endpoints
On-prem Exchange / Postfix	User + password	IMAP 993 SSL, SMTP 465/587
Gmail	App password or OAuth 2	imap/smtp Gmail hosts
Microsoft 365 / Outlook	OAuth 2 preferred	outlook.office365.com:993
Tencent / NetEase enterprise mail	Issued SMTP codes	Vendor docs

Gmail / Outlook routinely block password-based IMAP. Production should standardize OAuth 2 flows.

Configuration

Credential record

Console → Integrations → Email:

Mailbox label
IMAP/SMTP endpoints + TLS
Authentication (basic or OAuth default From)

Sanity check

combo-cli integration test --credential <cred_id> --type mail
# expect IMAP + SMTP positives

Optional trigger blueprint

trigger:
  source: email
  credential_id: <cred_id>
  match:
    folder: INBOX
    from_regex: "@supplier\\.com$"
    subject_regex: "(quote|quotation)"
  action:
    agent_id: "quote-assistant"
    session_template: "per-sender"
    inputs:
      subject: "{{ email.subject }}"
      body: "{{ email.body_text }}"
      attachments: "{{ email.attachments }}"

Auto-replies

on_finish:
  reply_email:
    credential_id: <cred_id>
    to: "{{ trigger.email.from }}"
    subject: "Re: {{ trigger.email.subject }}"
    body_html: "{{ agent.output_html }}"

Scenario ideas

Use case	Setup notes
Prospect emails → summarized quotes	IDLE listener + drafts requiring human approval before send
Test / review summaries distribution	SMTP after agent synthesis
Executive digests via cron	Cron + multi-recipient broadcasts
Supplier attachments → ingestion	IDLE + parsers + KB upload

Large attachments / sender reputation

Size: default ~25 MB SMTP ceiling—larger payloads use temporary MinIO URLs
Authentication: DKIM / SPF / DMARC for branded domains
TLS mandates: Credential flag require_tls: true

Troubleshooting

Symptom	Fix
IDLE drops every ~30 min	Turn on TCP keep-alive; SDK auto-reconnect (~25 min cadence default)
Deliveries flagged spam	Tune DNS authentication + sending cadence
Subject mojibake	Enforce UTF-8 headers / MIME folds
OAuth refresh failures	Short Outlook refresh TTL—implement refresh reliably

Email integration (SMTP / IMAP)

On this page