Skip to content

Email

OMD Cleo supports email as a full two-way communication channel. The agent can receive incoming emails (via IMAP polling or a webhook) and send replies via SMTP.

How it works

  • Incoming mail is received either by polling an IMAP inbox at a configurable interval, or by receiving a webhook POST from your mail provider.
  • Outgoing mail is sent via SMTP. Replies include proper In-Reply-To and References headers so mail clients show a single thread.
  • Only the final AI response is sent as an email. Intermediate tool-call messages are not forwarded to avoid noisy back-and-forth.

Setup

Add email to ENABLED_CLIENTS:

ENABLED_CLIENTS=email

Required environment variables

Variable Description
EMAIL_SMTP_HOST SMTP server hostname (e.g. smtp.strato.de)
EMAIL_USER Login username for SMTP and IMAP
EMAIL_PASSWORD Login password for SMTP and IMAP

Optional environment variables

Variable Default Description
EMAIL_SMTP_PORT 587 SMTP port (STARTTLS)
EMAIL_FROM_ADDRESS EMAIL_USER From-address for outgoing emails
EMAIL_IMAP_HOST — IMAP hostname for polling; required for polling mode
EMAIL_IMAP_PORT 993 IMAP port (SSL)
EMAIL_POLL_INTERVAL_SECONDS 60 Seconds between IMAP poll runs

When EMAIL_IMAP_HOST is set, the agent polls the configured inbox periodically:

  1. Connects to the IMAP server with the configured credentials.
  2. Searches for UNSEEN messages.
  3. Processes each new message (threading by Message-ID / References).
  4. Marks processed messages so they are not handled twice.

No external webhook infrastructure is required.

Receiving email: webhook

As an alternative to polling, configure your mail provider to POST incoming emails to:

POST /email/incoming

Request body:

{
  "from_address": "user@example.com",
  "to_address": "cleo@yourdomain.com",
  "subject": "Re: Question",
  "body": "Plain text body of the email",
  "message_id": "<optional Message-ID header>",
  "in_reply_to": "<optional In-Reply-To>",
  "references": "<ref1> <ref2>"
}

Attachments

Outbound emails support file attachments. Use the attachments parameter in the send_message API or workflow configuration to attach files (in-memory bytes or binary objects — not file paths).

Thread tracking

The agent derives the conversation thread ID from the references header (using the first Message-ID), falling back to message_id, then email:{from_address}. This ensures replies stay in the same conversation and mail clients display a single thread.