Email Integration (IMAP/SMTP)

This document explains how to configure an email integration for Flocks so Rex or a specified Agent can receive questions by email, reply to emails, and send Task Center or Workflow results to specified mailboxes.

Use Cases

• Let users ask Flocks questions directly by email without depending on an IM client or bot platform.
• Send scheduled inspections, alert investigations, daily reports, or remediation recommendations to on-call mailboxes, ticket mailboxes, or team mailing lists.
• The enterprise environment already has usable SMTP / IMAP mailbox services and cannot conveniently expose a public Webhook.
• Preserve email threads so context can be tracked in email clients, ticket systems, or archive systems.

Prerequisites

• Prepare a dedicated mailbox for the Flocks email integration. Using a personal daily-use mailbox is not recommended.
• Confirm that the mailbox has IMAP receiving and SMTP sending enabled.
• Obtain the mailbox account, app-specific password, or authorization code. Mailboxes with two-factor authentication usually cannot use the login password directly.
• Confirm that the server running Flocks can access the mailbox provider's IMAP / SMTP hosts and ports.
• For production environments, prepare the allowed sender list in advance to prevent anyone who knows the email address from triggering an Agent.

Common ports are listed below. Use the mailbox provider documentation or information from the enterprise email administrator as the source of truth:

Protocol	Common Port	Encryption	Purpose
IMAP	993	SSL / TLS	Receive new mail
SMTP	587	STARTTLS	Send reply mail
SMTP	465	SSL / TLS	SMTPS sending port used by some mailbox providers

Procedure

1. Prepare a Dedicated Mailbox

Use a mailbox with a clear responsibility, for example:

flocks-assistant@example.com
soc-rex@example.com

Benefits of a dedicated mailbox:

• The mailbox stores only emails related to Flocks interactions, making audit and troubleshooting easier.
• App-specific passwords, forwarding rules, retention periods, and access permissions can be configured separately.
• If the account leaks or needs rotation, personal mailboxes and other business mailboxes are not affected.

2. Enable IMAP / SMTP and Generate an App Password

The entrypoints vary by mailbox provider. Common approaches:

• Gmail: after enabling 2-Step Verification, generate an app password in Google Account App Passwords; also confirm that IMAP is enabled in Gmail settings.
• Outlook / Microsoft 365: confirm that the organization allows IMAP / SMTP AUTH; after enabling multi-factor authentication, use an app password or request SMTP AUTH according to enterprise policy.
• Enterprise mailbox: contact the email administrator to confirm the IMAP host, SMTP host, ports, encryption methods, and whether an authorization code is required.

Do not enter a personal login password directly into Flocks. Prefer app-specific passwords, authorization codes, or least-privilege credentials issued by the enterprise.

3. Enter Email Integration Settings in Flocks

Go to "Messaging Integrations -> Email Integration" or the "Email" page in the Flocks WebUI, then enter the basic connection information.

Configuration Item	Description
Email address	Full email address Flocks uses to send and receive mail, for example flocks-assistant@example.com.
Email password / authorization code	App-specific password or authorization code generated by the mailbox provider.
IMAP host	Receiving server address, such as imap.gmail.com, outlook.office365.com, or the enterprise mailbox IMAP address.
IMAP port	Usually 993.
IMAP encryption	Usually SSL / TLS.
SMTP host	Sending server address, such as smtp.gmail.com, smtp.office365.com, or the enterprise mailbox SMTP address.
SMTP port	Usually 587; some providers use 465.
SMTP encryption	587 commonly uses STARTTLS, and 465 commonly uses SSL / TLS.
Default Agent	Which Agent handles new emails by default.
Polling interval	How often Flocks checks for new mail. The default can stay around 15 seconds; increase it when enterprise mailbox rate limits are strict.
Allowed senders	Only process emails from senders in the list. Required for production.
Default recipients	Which mailbox or mailing list receives Task Center or Workflow results when no target is specified.

Before saving the configuration, verify server network reachability with an email client or tools such as openssl s_client / telnet so account issues and network issues are not mixed during troubleshooting.

4. Enable and Verify the Integration

1. Click Enable, then click Save.
2. Wait until the email integration status changes to running.
3. Use a mailbox in the allowed list to send a test email to the Flocks dedicated mailbox.
4. Use Test Flocks email integration as the email subject, and put a simple question in the body, for example:

Please reply whether the current email integration is connected.

If Flocks replies in the same email thread, IMAP receiving, Agent processing, and SMTP sending are all working.

Receiving and Reply Mechanism

The email integration periodically polls the inbox for new messages and does not require a public callback URL. The process is:

1. Flocks periodically connects to the IMAP inbox and looks for unread or unprocessed new emails.
2. For emails that match the allowed sender list, it extracts the sender, subject, body, and required context.
3. Rex or the configured default Agent processes the email body.
4. Flocks replies to the original sender through SMTP and tries to preserve the original email thread.

The email subject participates in processing as context. Reply emails preserve the Re: subject and email thread headers where possible, making it easier for users to track the same issue continuously in their email client.

Attachment Handling

If the email integration supports attachment handling, use it with the following strategy:

• Attachments such as images, PDFs, archives, and logs are downloaded to the Flocks workspace or channel cache directory for Agent reading or analysis.
• For untrusted sources, disable attachment handling or allow only attachments from allowlisted senders into Flocks.
• Do not let the email integration automatically process executable files, macro documents, or unknown attachment formats.
• Large attachments may trigger mailbox provider size limits and also increase Agent processing cost. Use Workspace or object storage to transfer large files.

If production needs to ignore inbound attachments completely, disable attachment handling in email integration advanced settings. The exact field depends on the current WebUI version.

Access Control and Security Recommendations

Email addresses are naturally easy to forward or guess, so the email integration must enforce access control.

• In production, always configure Allowed senders to permit only trusted mailboxes, mailbox groups, or ticket system addresses to trigger Flocks.
• Use a dedicated mailbox and app-specific password where possible. Do not use a personal mailbox or primary login password.
• Rotate mailbox app passwords regularly. Revoke old passwords immediately when an employee leaves, a project ends, or leakage is suspected.
• Enable login protection, abnormal login alerts, and least-privilege policies for the email integration account.
• Do not commit mailbox passwords, authorization codes, or .env / configuration export files to Git.
• If Flocks can execute commands, operate devices, or change tickets, the email trigger entrypoint should be used together with Agent tool allowlists and permission approvals.

If you truly need to allow all senders, bind only a read-only analysis Agent and disable high-risk tools.

Result Delivery and Session ID

To proactively send results to an email address from a Flocks page, Task Center, or Workflow, use an email address directly or establish an email conversation binding first.

Common wording:

Send this inspection summary to soc@example.com.

If the current version supports email conversation binding, you can also ask Rex in the target email thread:

What is your session_id?

After you get the Session ID, you can pin the delivery target in a task description or Workflow:

Send to session_id: <session_id>: Today's inspection is complete. Two high-risk alerts were found.

If the email thread changes, a user starts a new subject, or the conversation is reset, reconfirm the target Session ID.

FAQ

IMAP Connection Fails

Verify the following:

• Whether the IMAP host and port are correct.
• Whether IMAP is enabled for the mailbox account.
• Whether the Flocks server can access the IMAP host.
• Whether the enterprise mailbox restricts source IPs or requires VPN / internal network access.
• Whether the encryption method matches the port, for example 993 usually uses SSL / TLS.

SMTP Sending Fails

Verify the following:

• Whether the SMTP host, port, and encryption method are correct.
• Whether an app-specific password or authorization code is used instead of a normal login password.
• Whether the mailbox provider restricts SMTP AUTH, sending frequency, or source IPs.
• Whether the sender address must match the login account.

No Email Is Received or No Reply Is Sent

Verify the following:

• Whether the sender is in the allowed list.
• Whether the test email entered spam, quarantine, or another folder.
• Whether the email integration only processes new emails in the inbox.
• Whether multiple Flocks instances are connected to the same mailbox at the same time, causing one instance to mark the mail as processed first.

Email Replies Are Not Threaded Together

Different email clients apply threading rules differently. First confirm that thread headers such as Message-ID, In-Reply-To, and References in the original email were not removed by intermediate systems. Also avoid repeatedly rewriting the subject in automatic replies.

Response Is Slow

Because the email integration polls the inbox, you can shorten the polling interval to improve response time. Very short intervals increase IMAP connection frequency and may trigger enterprise mailbox rate limits. In production, balance response speed against mailbox provider limits.

---

Related Resources: Messaging and alerting integrations overview | DingTalk integration | Feishu integration | WeCom integration | Slack integration | Telegram integration | WeChat integration | WhatsApp integration