Skip to content

Email Inbox Integration

oAI-Web can monitor IMAP mailboxes and dispatch agents in response to incoming emails.

Account types

trigger accounts

IMAP accounts that dispatch agents based on trigger word matching in email subjects/bodies.

  • Uses IMAP IDLE (push) for low-latency detection when supported; falls back to polling
  • Each matched email fires the configured agent with the email content as context
  • Good for: "when I receive an email from my bank, summarise it and push a notification"

handling accounts

IMAP accounts that give an agent full email management capabilities.

  • Polls every 60 seconds
  • The agent receives a special email_handling tool that gives it access only to that account
  • force_only_extra_tools=True — only the email tool and any extra_tools are available (no general tools)
  • The agent cannot escalate beyond what's declared in extra_tools
  • Good for: "check these emails, respond to simple queries, forward others"

Setup

  1. Go to Settings → Email Accounts → Add Account
  2. Fill in IMAP and SMTP credentials (or SMTP-only for send-only accounts)
  3. Select account type (trigger or handling)
  4. Set the agent that will handle matching emails
  5. Optionally configure monitored folders (blank = all folders)
  6. Save

The listener starts automatically for all enabled accounts.

Trigger matching

Same logic as Telegram triggers: all tokens in the trigger phrase must be present in the message (subject + body, combined), order-independent, case-insensitive.

Manage trigger rules in Settings → Inbox → Trigger Rules (linked to a specific account).

Initial load

When an account is first set up, a one-time initial load runs to mark existing messages as "seen" without triggering agents. The limit (default: 200 most recent messages) prevents the agent from being flooded on the first run.

After the initial load, only new messages trigger rules.

Multiple accounts

Each account runs its own listener task. Accounts are independent — an email can match triggers in multiple accounts simultaneously.

Account listeners are managed by InboxListenerManager in server/inbox/listener.py. It starts/stops individual listeners as accounts are created, updated, or deleted via the API.

Bound tools in handling accounts

When an agent runs for a handling account, it receives: - BoundFilesystemTool — scoped to {base}/{username}/inbox/ (if system:users_base_folder is configured) - BoundTelegramTool — pre-configured with the account's telegram_chat_id (if set) - EmailHandlingTool — access to that specific account's IMAP/SMTP

force_only_extra_tools=True ensures the agent cannot reach outside these three tools.

Security considerations

  • Email body content is sanitised with sanitize_external_content() before being passed to the agent
  • The agent for an inbox trigger cannot send emails unless email is in its allowed_tools
  • Handling accounts use force_only_extra_tools — structurally impossible to escalate
  • Credentials are encrypted at rest (IMAP password, SMTP password stored as AES-GCM blobs)