Email

Connects a mailbox to an agent flow over IMAP/SMTP. NeuraFlow polls the mailbox for new mail; it does not require a webhook or a specific provider.

1. Prerequisites

Values to collect

1. IMAP host, port, username, password (incoming mail)
2. SMTP host, port, username, password (outgoing replies)

Any mailbox that exposes standard IMAP and SMTP works, there's no provider-specific setup. Defaults are IMAP port 993 with SSL and SMTP port 587 with TLS. If the provider uses app passwords instead of the account password (Gmail, for example), use the app password.

2. Configuration

Three console routes:

Route	Purpose
/channels/email	List the organization's email integrations
/channels/email/create	Create an integration
/channels/email/{id}/edit	Reconfigure or disable it

Create

/channels/email/create is one form, four cards, client-side validated with Zod before it ever reaches the server.

Basic Information: Integration Name (required, "Name is required"), Email Address (required, must be a valid address, "Valid email address is required"), Agent Flow (required, "Agent flow is required").

IMAP Configuration (Incoming Mail):

Field	Required	Placeholder/default
IMAP Host	Yes	imap.gmail.com
IMAP Port	Yes	993
IMAP Username	Yes	your-email@example.com
IMAP Password	Yes	App password or account password
Use SSL	No	On

SMTP Configuration (Outgoing Mail): same layout, smtp.gmail.com / 587, otherwise identical field set and defaults, labelled Use TLS instead of Use SSL.

Processing Options: Folder Name (default INBOX), Mark as Read (on), Enabled (on).

Test Connection first checks client-side that IMAP/SMTP host, username and password are all filled in ("Missing fields: " followed by the list of missing ones), then calls POST /channels/email/test-connection with the current form values, unsaved. Toasts "Connection test successful!" or "Connection test failed: " plus the server's message; a request-level failure (e.g. the SSRF host check below) toasts the server's detail or "Connection test failed" if there isn't one.

Create Integration is disabled until an organization is selected. On submit it toasts "Email integration created successfully!" and goes to the edit page, or toasts the server's detail (falling back to "Failed to create integration") on error, most commonly the 409 "Email address already in use" or the SSRF-guard 400s: "Host '...' resolves to a non-routable address" and "Cannot resolve host '...'", both of which apply to the IMAP and SMTP hosts independently, on create, update and Test Connection alike.

Edit

Same four cards, with these differences from create:

• Email Address is shown read-only in the Basic Information card description ("Email: ... (read-only)"), it isn't an editable field here.
• IMAP/SMTP Password fields always load blank and are labelled "(leave empty to keep current)". Test Connection here refuses to run unless you've typed both passwords in ("Please enter both IMAP and SMTP passwords to test connection"), since the stored ones aren't sent to the browser to prefill the test call.
• If the integration's status is error, a red card appears above Basic Information showing the last error message and "Error count: N (integration will auto-disable after 5 failures)".

Save Changes submits every field except the two passwords, which are only included in the PUT request if you typed something into them. Success toasts "Email integration updated successfully!" and clears both password fields again; failure toasts the server's detail or "Failed to update integration".

3. Other

No webhook to register anywhere. A background worker polls every enabled integration's IMAP folder every 2 minutes (EMAIL_POLL_INTERVAL_SECONDS, default 120) rather than reacting to a push notification.

Each poll updates status (active / inactive / error), last_sync_at and last_error. Five consecutive failed polls set enabled=false automatically, which stops the worker from picking the integration up again; re-enabling it on the edit screen is what resumes polling.