All channels

Email (IMAP + SMTP)

Any mailbox works: the channel polls a dedicated mailbox over IMAP for unread mail, runs each message through the flow, and replies in-thread over SMTP (In-Reply-To / References, Re: subject). No public webhook URL is needed — the gateway connects out to your mail provider.

Channel key: email (conversation_context.channel); the mailbox address is conversation_context.channel_account_id.

What you need

  • A mailbox used only by the agent (the poller marks handled mail as read; a shared inbox would confuse humans and the agent).
  • IMAP and SMTP hostnames/ports and a login. Providers that enforce 2‑step verification require an app password instead of the account password.

Gmail / Google Workspace

  • IMAP imap.gmail.com port 993 (SSL/TLS); SMTP smtp.gmail.com port 587 (STARTTLS) or 465 (SSL/TLS). Since January 2025 IMAP is always on — https://support.google.com/mail/answer/7126229
  • With 2‑Step Verification on, create an app password at https://myaccount.google.com/apppasswords — steps and restrictions (unavailable for security‑key‑only 2SV, Advanced Protection, and when a Workspace admin disables them; revoked when you change your password): https://support.google.com/accounts/answer/185833
  • Workspace admins: Admin console → Apps → Google Workspace → Gmail → End User Access → allow IMAP, and Security → Less secure apps is NOT needed with app passwords.

Microsoft 365 / Outlook.com

  • IMAP outlook.office365.com port 993 (SSL/TLS); SMTP smtp-mail.outlook.com (Outlook.com) or smtp.office365.com (Microsoft
    1. port 587 (STARTTLS) — https://support.microsoft.com/en-us/office/pop-imap-and-smtp-settings-8361e398-8af4-4e97-b147-6c6c4ac95353
  • Microsoft mailboxes are not supported today. Microsoft has removed password (Basic) authentication for Exchange Online IMAP/SMTP AUTH and for Outlook.com — only OAuth2 remains — while this channel authenticates with a password (SASL PLAIN). Use a mailbox on a provider that supports app passwords (Gmail, Fastmail, most hosted IMAP) instead; OAuth2 support is on the roadmap.

Other providers

Any IMAP/SMTP server with TLS: implicit TLS on 993/465, STARTTLS on other ports. Plain, unencrypted servers are refused (except localhost for tests).

Official documentation

Connect in Tools Anatomy

/channels → Messaging channels → Email → Connect:

Field Value
IMAP host / port e.g. imap.gmail.com / 993
SMTP host / port e.g. smtp.gmail.com / 587
Username the mailbox login (usually the address)
Password / app password secret, stored in the Secret Manager
From address / From name what replies are sent as
Folder (advanced) default INBOX
Poll interval (advanced) seconds between checks, default 30, minimum 10
Signature appended to every reply

Connect logs in over IMAP (and opens the folder) and authenticates over SMTP; both must succeed. There is no webhook to configure.

Identity we derive

Canonical key Source Notes
external_user_id sender address, lower‑cased
channel email
email sender address, runtime_only
display_name sender's name from From:, runtime_only never a join key
phone_number — not provided

Context Vault identity channel: email. Threads: the first Message-ID in References (or In-Reply-To, or the message's own id).

Limits

  • Polling delay = the poll interval (default 30 s) plus the provider's delivery time; email is not real time.
  • Only the sender's new text is used: quoted history ("On … wrote:", "-----Original Message-----", lines starting with >) is stripped; HTML mail is reduced to text. Attachments are not processed (the reply notes text only).
  • Loop protection: auto-replies, bounces (Auto-Submitted, Precedence: bulk/junk/list, List-Id, mailer-daemon/no-reply senders) and mail from the mailbox itself are ignored; our replies carry Auto-Submitted: auto-replied.
  • The runner is single-instance: run one channel-gateway replica per mailbox, or two pollers would race on unread mail.
  • Provider sending limits apply (Gmail ~500/day per account, Workspace ~2,000/day; Microsoft 365 10,000 recipients/day).
  • A message that cannot be parsed is marked read and skipped (it never blocks the mailbox).

Test it

  1. From another address, email the mailbox with a question.
  2. Within one poll interval the flow's reply arrives in the same thread.
  3. /channels → the channel → Threads shows the conversation; the mailbox itself shows the original as read and the reply in Sent (SMTP providers that don't copy to Sent, e.g. some Gmail setups, may not).

Troubleshooting

  • Connect fails with "platform rejected the credentials" — wrong login, or the provider requires an app password / has IMAP disabled (Google Workspace admin, Microsoft Basic auth off).
  • "folder INBOX could not be opened" — the folder name differs (e.g. localized); set the advanced Folder field.
  • "SMTP server does not offer STARTTLS" — use port 465 (implicit TLS) or a TLS-capable host.
  • Replies not threading — the client discards References; the reply still goes to the sender with Re: subject.
  • Same mail answered twice — two gateway instances poll the same mailbox; run one.