Email

Connect Comis to Email with step-by-step IMAP/SMTP setup

Connect your Comis agent to an email inbox. Comis monitors incoming messages via IMAP and replies via SMTP. Supports password and OAuth2 authentication, RFC 5322 reply-chain threading, sender allowlists, and file attachments up to 100,000 characters per message.

You don’t need to understand the technical details to use this feature. The configuration examples below are copy-paste ready.

Prerequisites

• Comis installed and running (Quickstart)

• An email account with IMAP and SMTP access enabled
• For Gmail: an App Password (2FA required) or OAuth2 credentials
• For self-hosted: IMAP and SMTP server addresses and credentials

Email uses IMAP to receive messages and SMTP to send replies. Your email provider must allow IMAP access. Gmail users should use App Passwords or configure OAuth2 — regular account passwords will not work if 2FA is enabled.

Setup

1. Enable IMAP access

   Gmail: Go to Settings > See all settings > Forwarding and POP/IMAP > Enable IMAP. Click Save Changes.

   Outlook: IMAP is enabled by default for most Outlook and Microsoft 365 accounts. No action needed.

   Self-hosted: Check your mail server configuration to ensure IMAP is enabled and accessible on port 993 (TLS) or 143 (STARTTLS).

2. Get your credentials

   For password authentication:

   • Gmail: Go to your Google Account > Security > App passwords. Generate a new app password for “Mail” and copy it. You must have 2FA enabled on your Google account to use App Passwords.
   • Outlook: Go to Account Settings > App passwords and generate one.
   • Self-hosted: Use your existing email password or create a dedicated application password.

   For OAuth2 authentication:

   • Create an OAuth2 client in Google Cloud Console (Gmail) or Azure AD (Outlook).
   • Note the client ID and client secret.
   • Generate a refresh token using the OAuth2 authorization flow for your provider.
3. Configure Comis

   Add the Email channel to your Comis configuration file (~/.comis/config.yaml):

   channels:
     email:
       enabled: true
       address: "[e-mail]"
       imapHost: "imap.example.com"
       smtpHost: "smtp.example.com"
       botToken: "${EMAIL_PASSWORD}"
       allowMode: "allowlist"
       allowFrom:
         - "[e-mail]"
   

   Set the EMAIL_PASSWORD environment variable in your ~/.comis/.env file:

   EMAIL_PASSWORD=your-email-password-or-app-password
   

   Never store API keys, tokens, or passwords directly in config.yaml. Use the .env file or Secret Manager for credential management.

   Password Auth

   The configuration above uses password authentication. The botToken field holds your email password or App Password. This is the simplest setup and works with most email providers.

   OAuth2 Auth

   For OAuth2 authentication (recommended for Gmail), use this configuration instead:

   channels:
     email:
       enabled: true
       address: "[e-mail]"
       imapHost: "imap.gmail.com"
       smtpHost: "smtp.gmail.com"
       authType: "oauth2"
       clientId: "${EMAIL_OAUTH_CLIENT_ID}"
       clientSecret: "${EMAIL_OAUTH_CLIENT_SECRET}"
       refreshToken: "${EMAIL_REFRESH_TOKEN}"
       allowMode: "open"
   

   Set the environment variables in your ~/.comis/.env file:

   EMAIL_OAUTH_CLIENT_ID=your-oauth-client-id
   EMAIL_OAUTH_CLIENT_SECRET=your-oauth-client-secret
   EMAIL_REFRESH_TOKEN=your-oauth-refresh-token
   

   The config key is botToken (shared across all channel types) but for Email this is your email password or App Password, not a bot token. Use the EMAIL_PASSWORD environment variable to avoid confusion.

4. Restart and verify

   Restart the Comis daemon to pick up the new configuration:

   comis daemon stop && comis daemon start
   

   Check the logs for a successful connection:

   comis daemon logs
   

   Look for a line containing “Email adapter started” or “channel-email activated”. If you see this, the adapter is running and monitoring your inbox.

   Send a test email from an allowed sender to confirm the bot receives and replies to it.

Configuration

These options go under channels.email in your config.yaml:

Option	Type	Default	What it does
enabled	boolean	false	Turns on the Email adapter
address	string	(required)	Email address to monitor and send from
imapHost	string	(required)	IMAP server hostname (e.g. imap.gmail.com)
imapPort	number	993	IMAP server port
smtpHost	string	(required)	SMTP server hostname (e.g. smtp.gmail.com)
smtpPort	number	587	SMTP server port
secure	boolean	true	Use TLS for IMAP/SMTP connections
authType	"password" / "oauth2"	"password"	Authentication method
botToken	string / SecretRef	(optional)	Email password or App Password (env: EMAIL_PASSWORD)
clientId	string / SecretRef	(optional)	OAuth2 client ID (required when authType: "oauth2")
clientSecret	string / SecretRef	(optional)	OAuth2 client secret (required when authType: "oauth2")
refreshToken	string / SecretRef	(optional)	OAuth2 refresh token (required when authType: "oauth2")
allowMode	"allowlist" / "open"	"allowlist"	Sender filtering mode. allowlist blocks all senders not in allowFrom. open accepts all senders.
allowFrom	string[]	[]	Email addresses allowed to send messages to the bot (only used when allowMode: "allowlist")
pollingIntervalMs	number	60000	Fallback polling interval in milliseconds when IMAP IDLE is not supported
mediaProcessing.transcribeAudio	boolean	true	Transcribe audio attachments to text
mediaProcessing.analyzeImages	boolean	true	Describe image attachments using AI vision
mediaProcessing.describeVideos	boolean	true	Extract descriptions from video attachments
mediaProcessing.extractDocuments	boolean	true	Extract text from PDF, DOCX, and other document attachments
mediaProcessing.understandLinks	boolean	true	Fetch and summarize URLs included in messages

What your agent can do

Once connected to Email, your agent can:

• Send and receive email messages
• Maintain conversation threads via RFC 5322 reply headers (In-Reply-To, References)
• Receive and process file attachments (images, video, audio, documents)
• Send HTML-formatted responses (Markdown is converted to HTML automatically)
• Filter senders with allowMode: "allowlist" or allowMode: "open"
• Detect and skip automated mailers (noreply@, mailer-daemon@, Auto-Submitted and Precedence: bulk headers, List-Unsubscribe)

Email does not support reactions, editing or deleting sent messages, fetching historical messages on demand, streaming (live-updating responses), buttons, cards/embeds, native polls, group chats (To/Cc are flat metadata, not grouped conversations), or @mentions.

How Email works

Email is the only dual-protocol adapter in Comis — it uses IMAP to receive messages and SMTP to send replies.

Receiving messages (IMAP): Comis connects to your IMAP server and uses IMAP IDLE (RFC 2177) for near-instant inbox monitoring. The IDLE connection is recycled every 25 minutes — well within the 29-minute limit recommended by RFC 2177 — to keep the session healthy across NAT and proxy timeouts. If your IMAP server does not support IDLE, Comis falls back to polling at the interval configured by pollingIntervalMs (default: 60 seconds).

Sending replies (SMTP): All outbound messages are sent via SMTP with proper reply-chain headers (In-Reply-To, References) to maintain conversation threading in the recipient’s email client. Every outbound message includes an Auto-Submitted: auto-generated header to prevent mail loops with other automated systems.

Automated sender detection: Comis automatically skips messages from automated senders to avoid reply loops. The following patterns are detected and filtered:

• Addresses starting with noreply@ or mailer-daemon@
• Messages with an Auto-Submitted header (any value except “no”)
• Messages with Precedence set to bulk, junk, or list
• Messages containing List-Unsubscribe or X-Auto-Response-Suppress headers

Credential validation: At startup, the Email adapter validates your credentials by testing the IMAP connection before committing to the full lifecycle. If authentication fails, the adapter reports the error and does not start, preventing silent failures.

Platform limits

Limit	Value	What Comis does about it
Message length	100,000 characters	Automatically splits long responses into multiple emails at paragraph boundaries
Attachment size	No platform limit	Limited by your email provider’s attachment size limit (typically 25 MB for Gmail)
Polling interval	60 seconds (default)	Configurable via pollingIntervalMs; IMAP IDLE provides near-instant delivery when supported

Complete walkthrough: from zero to first reply

A start-to-finish run for a Gmail mailbox [e-mail]:

1. Enable IMAP and create an App Password

   In Gmail, open Settings -> See all settings -> Forwarding and POP/IMAP and enable IMAP. Then visit Google Account -> Security -> App passwords (2-Step Verification must be on). Generate a password for “Mail” and copy the 16-character value.

2. Pick an allowlisted sender

   Decide which email address you will reply from for testing — for example, your personal [e-mail]. Bots default to allowlist mode, so unlisted senders are ignored.

3. Wire it into Comis

   Add to ~/.comis/.env:

   EMAIL_PASSWORD=your-16-char-app-password
   

   Add to ~/.comis/config.yaml:

   channels:
     email:
       enabled: true
       address: "[e-mail]"
       imapHost: "imap.gmail.com"
       smtpHost: "smtp.gmail.com"
       botToken: "${EMAIL_PASSWORD}"
       allowMode: "allowlist"
       allowFrom:
         - "[e-mail]"
   
4. Restart and verify

   comis daemon stop && comis daemon start
   comis daemon logs
   

   You should see Email adapter started followed by IMAP IDLE active.

5. Send the first email

   From [e-mail], send a normal email to [e-mail] with a plain subject like “Hello”. Within a few seconds the agent’s reply arrives in your inbox, threaded under your original message via In-Reply-To.

Troubleshooting

Authentication fails at startup

Credential validation runs at startup. Check that IMAP is enabled on your email provider, the password or App Password is correct, and if using Gmail with 2FA, you are using an App Password (not your regular password). For OAuth2, verify that the client ID, client secret, and refresh token are all valid and the refresh token has not expired.

Messages arrive but bot does not reply

Check your SMTP settings. The SMTP host and port must match your provider (smtp.gmail.com:587 for Gmail, smtp.office365.com:587 for Outlook).

Also verify allowMode and allowFrom — in "allowlist" mode (the default), only senders listed in allowFrom will trigger responses. If allowFrom is empty and allowMode is "allowlist", no messages will be processed.

Bot replies to automated emails

Comis filters most automated senders automatically (noreply@, mailer-daemon@, messages with bulk/junk precedence, and messages with Auto-Submitted headers). If you are still seeing replies to automated mail, check the sender headers for unusual patterns and consider using allowMode: "allowlist" to restrict to known senders.

Long delay before messages appear

If your IMAP server does not support IDLE, Comis falls back to polling at the interval set by pollingIntervalMs (default 60 seconds). Reduce this value for faster delivery, but be mindful of your provider’s rate limits. Most major providers (Gmail, Outlook, Yahoo) support IMAP IDLE, so check your server’s IDLE support if you experience delays.

Delivery Infrastructure

How streaming, typing indicators, and retry logic work under the hood.

Multiple users & teams

Run one install for a whole team - private per person, isolated per agent.

All Channels

Compare all 9 supported platforms side by side.

Agent Configuration

Set up your agent’s personality, tools, and behavior.

Secret Management

Learn how to manage API keys and tokens securely.