Skip to content

Self-improving AI Employees for everyone

feat: email credentials panel + custom IMAP/SMTP fallback

trohitg413f317a5ec0
diff --git a/client/src/components/CredentialsModal.tsx b/client/src/components/CredentialsModal.tsx
index c2b4016b..d6d4549d 100644
--- a/client/src/components/CredentialsModal.tsx
+++ b/client/src/components/CredentialsModal.tsx
@@ -29,6 +29,7 @@ import {
import { ApifyIcons } from '../assets/icons/apify';
import { SearchIcons } from '../assets/icons/search';
import { TelegramIcons } from '../assets/icons/telegram';
+import { EmailIcons } from '../assets/icons/email';
// ============================================================================
// SERVICE ICONS
@@ -64,6 +65,13 @@ const TelegramIcon = () => (
/>
);
+const EmailIcon = () => (
+ <div
+ dangerouslySetInnerHTML={{ __html: EmailIcons.read }}
+ style={{ width: 20, height: 20 }}
+ />
+);
+
const GoogleWorkspaceIcon = () => (
<GoogleOutlined style={{ fontSize: 20, color: '#4285F4' }} />
);
@@ -110,7 +118,7 @@ interface CredentialItem {
Icon?: React.FC<{ size?: number }>;
CustomIcon?: React.FC;
isSpecial?: boolean;
- panelType?: 'whatsapp' | 'android' | 'twitter' | 'telegram' | 'gmail' | 'google_maps' | 'search';
+ panelType?: 'whatsapp' | 'android' | 'twitter' | 'telegram' | 'gmail' | 'google_maps' | 'search' | 'email';
}
interface Category {
@@ -151,6 +159,13 @@ const CATEGORIES: Category[] = [
{ id: 'gmail', name: 'Google Workspace', placeholder: '', color: '#4285F4', desc: 'Gmail, Calendar, Drive, Sheets, Tasks, Contacts', CustomIcon: GoogleWorkspaceIcon, isSpecial: true, panelType: 'gmail' },
],
},
+ {
+ key: 'email',
+ label: 'Email',
+ items: [
+ { id: 'email_himalaya', name: 'Email (IMAP/SMTP)', placeholder: '', color: '#268bd2', desc: 'Gmail, Outlook, Yahoo, iCloud, Fastmail, ProtonMail, custom', CustomIcon: EmailIcon, isSpecial: true, panelType: 'email' },
+ ],
+ },
{
key: 'android',
label: 'Android',
@@ -427,6 +442,12 @@ const { validateApiKey, saveApiKey, getStoredApiKey, hasStoredKey, removeApiKey,
if (item.panelType === 'telegram') {
return { connected: telegramStatus.connected, label: telegramStatus.connected ? `@${telegramStatus.bot_username}` : 'Not Connected' };
}
+ if (item.panelType === 'email') {
+ return {
+ connected: !!emailStored,
+ label: emailStored && emailAddress ? emailAddress : 'Not configured',
+ };
+ }
return null;
};
@@ -570,6 +591,18 @@ const { validateApiKey, saveApiKey, getStoredApiKey, hasStoredKey, removeApiKey,
const [telegramLoading, setTelegramLoading] = useState<string | null>(null);
const [telegramError, setTelegramError] = useState<string | null>(null);
+ // Email (Himalaya IMAP/SMTP) state
+ const [emailProvider, setEmailProvider] = useState<string>('gmail');
+ const [emailAddress, setEmailAddress] = useState<string>('');
+ const [emailPassword, setEmailPassword] = useState<string>('');
+ const [emailImapHost, setEmailImapHost] = useState<string>('');
+ const [emailImapPort, setEmailImapPort] = useState<number>(993);
+ const [emailSmtpHost, setEmailSmtpHost] = useState<string>('');
+ const [emailSmtpPort, setEmailSmtpPort] = useState<number>(465);
+ const [emailStored, setEmailStored] = useState<boolean | null>(null);
+ const [emailLoading, setEmailLoading] = useState<string | null>(null);
+ const [emailError, setEmailError] = useState<string | null>(null);
+
// Rate limit state
const [rateLimitConfig, setRateLimitConfig] = useState<RateLimitConfig | null>(null);
const [rateLimitStats, setRateLimitStats] = useState<RateLimitStats | null>(null);
@@ -630,6 +663,33 @@ const { validateApiKey, saveApiKey, getStoredApiKey, hasStoredKey, removeApiKey,
}
}, [visible, hasStoredKey]);
+ // Load Email credentials on mount
+ useEffect(() => {
+ if (!visible) return;
+ (async () => {
+ try {
+ const [provider, address, hasPassword, imapHost, imapPort, smtpHost, smtpPort] = await Promise.all([
+ getStoredApiKey('email_provider'),
+ getStoredApiKey('email_address'),
+ hasStoredKey('email_password'),
+ getStoredApiKey('email_imap_host'),
+ getStoredApiKey('email_imap_port'),
+ getStoredApiKey('email_smtp_host'),
+ getStoredApiKey('email_smtp_port'),
+ ]);
+ if (provider) setEmailProvider(provider);
+ if (address) setEmailAddress(address);
+ if (imapHost) setEmailImapHost(imapHost);
+ if (imapPort) setEmailImapPort(parseInt(imapPort, 10));
+ if (smtpHost) setEmailSmtpHost(smtpHost);
+ if (smtpPort) setEmailSmtpPort(parseInt(smtpPort, 10));
+ setEmailStored(!!hasPassword);
+ } catch {
+ setEmailStored(false);
+ }
+ })();
+ }, [visible, getStoredApiKey, hasStoredKey]);
+
// Twitter handlers
const handleTwitterSaveCredentials = async () => {
if (!twitterClientId.trim()) {
@@ -835,6 +895,68 @@ const { validateApiKey, saveApiKey, getStoredApiKey, hasStoredKey, removeApiKey,
}
};
+ // Email handlers (Himalaya IMAP/SMTP)
+ const handleEmailSave = async () => {
+ if (!emailAddress.trim()) {
+ setEmailError('Email address is required');
+ return;
+ }
+ if (!emailPassword.trim() && !emailStored) {
+ setEmailError('Password is required');
+ return;
+ }
+ if (emailProvider === 'custom') {
+ if (!emailImapHost.trim() || !emailSmtpHost.trim()) {
+ setEmailError('IMAP and SMTP host are required for custom provider');
+ return;
+ }
+ }
+ setEmailLoading('save');
+ setEmailError(null);
+ try {
+ await saveApiKey('email_provider', emailProvider);
+ await saveApiKey('email_address', emailAddress.trim());
+ if (emailPassword.trim()) {
+ await saveApiKey('email_password', emailPassword.trim());
+ }
+ if (emailProvider === 'custom') {
+ await saveApiKey('email_imap_host', emailImapHost.trim());
+ await saveApiKey('email_imap_port', String(emailImapPort));
+ await saveApiKey('email_smtp_host', emailSmtpHost.trim());
+ await saveApiKey('email_smtp_port', String(emailSmtpPort));
+ }
+ setEmailStored(true);
+ setEmailPassword('');
+ } catch (err: any) {
+ setEmailError(err.message || 'Failed to save email credentials');
+ } finally {
+ setEmailLoading(null);
+ }
+ };
+
+ const handleEmailRemove = async () => {
+ setEmailLoading('remove');
+ setEmailError(null);
+ try {
+ await removeApiKey('email_password');
+ await removeApiKey('email_address');
+ await removeApiKey('email_provider');
+ await removeApiKey('email_imap_host');
+ await removeApiKey('email_imap_port');
+ await removeApiKey('email_smtp_host');
+ await removeApiKey('email_smtp_port');
+ setEmailStored(false);
+ setEmailAddress('');
+ setEmailPassword('');
+ setEmailImapHost('');
+ setEmailSmtpHost('');
+ } catch (err: any) {
+ setEmailError(err.message || 'Failed to remove credentials');
+ } finally {
+ setEmailLoading(null);
+ }
+ };
+
const handleTelegramRefreshStatus = async () => {
setTelegramLoading('refresh');
setTelegramError(null);
@@ -2027,6 +2149,251 @@ const { validateApiKey, saveApiKey, getStoredApiKey, hasStoredKey, removeApiKey,
);
}
+ // Email (Himalaya IMAP/SMTP) panel
+ if (selectedItem.panelType === 'email') {
+ const PROVIDER_OPTIONS = [
+ { label: 'Gmail', value: 'gmail' },
+ { label: 'Outlook / Office 365', value: 'outlook' },
+ { label: 'Yahoo Mail', value: 'yahoo' },
+ { label: 'iCloud Mail', value: 'icloud' },
+ { label: 'ProtonMail (Bridge)', value: 'protonmail' },
+ { label: 'Fastmail', value: 'fastmail' },
+ { label: 'Custom / Self-hosted', value: 'custom' },
+ ];
+ const AUTH_NOTES: Record<string, string> = {
+ gmail: 'Use an App Password from Google Account > Security > 2-Step Verification.',
+ outlook: 'Use your account password or an App Password.',
+ yahoo: 'Use an App Password from Yahoo Account Security.',
+ icloud: 'Use an App-Specific Password from your Apple ID.',
+ protonmail: 'Requires ProtonMail Bridge running locally (127.0.0.1).',
+ fastmail: 'Use an App Password from Settings > Privacy & Security.',
+ custom: 'Enter credentials for your self-hosted IMAP/SMTP server below.',
+ };
+ return (
+ <div style={{ padding: theme.spacing.xl, display: 'flex', flexDirection: 'column', flex: 1, minHeight: 0 }}>
+ <Descriptions
+ title={<Space><EmailIcon /> Email (IMAP/SMTP via Himalaya)</Space>}
+ bordered
+ column={1}
+ size="small"
+ style={{
+ marginBottom: theme.spacing.xl,
+ background: theme.colors.backgroundAlt,
+ borderRadius: theme.borderRadius.md,
+ }}
+ styles={{
+ label: {
+ backgroundColor: theme.colors.backgroundPanel,
+ color: theme.colors.textSecondary,
+ fontWeight: theme.fontWeight.medium,
+ },
+ content: {
+ backgroundColor: theme.colors.background,
+ color: theme.colors.text,
+ },
+ }}
+ >
+ <Descriptions.Item label="Status">
+ <Tag style={getTagStyle(emailStored ? 'success' : 'error')}>
+ {emailStored === null ? 'Checking...' : emailStored ? 'Configured' : 'Not configured'}
+ </Tag>
+ </Descriptions.Item>
+ {emailStored && emailAddress && (
+ <Descriptions.Item label="Account">
+ <span style={{ fontFamily: 'monospace', fontSize: theme.fontSize.sm }}>{emailAddress}</span>
+ </Descriptions.Item>
+ )}
+ </Descriptions>
+
+ <div style={{ marginBottom: theme.spacing.lg }}>
+ <label style={{
+ display: 'block',
+ fontSize: theme.fontSize.sm,
+ fontWeight: theme.fontWeight.medium,
+ color: theme.colors.text,
+ marginBottom: theme.spacing.sm,
+ }}>
+ Provider
+ </label>
+ <Select
+ value={emailProvider}
+ onChange={setEmailProvider}
+ options={PROVIDER_OPTIONS}
+ style={{ width: '100%' }}
+ />
+ </div>
+
+ <div style={{ marginBottom: theme.spacing.lg }}>
+ <label style={{
+ display: 'block',
+ fontSize: theme.fontSize.sm,
+ fontWeight: theme.fontWeight.medium,
+ color: theme.colors.text,
+ marginBottom: theme.spacing.sm,
+ }}>
+ Email Address
+ </label>
+ <Input
+ value={emailAddress}
+ onChange={(e: React.ChangeEvent<HTMLInputElement>) => setEmailAddress(e.target.value)}
+ placeholder="[email protected]"
+ style={{
+ backgroundColor: theme.colors.background,
+ borderColor: theme.colors.border,
+ color: theme.colors.text,
+ }}
+ />
+ </div>
+
+ <div style={{ marginBottom: theme.spacing.lg }}>
+ <label style={{
+ display: 'block',
+ fontSize: theme.fontSize.sm,
+ fontWeight: theme.fontWeight.medium,
+ color: theme.colors.text,
+ marginBottom: theme.spacing.sm,
+ }}>
+ Password {emailStored && (
+ <span style={{ color: theme.colors.textMuted, fontWeight: theme.fontWeight.normal }}>
+ (leave blank to keep existing)
+ </span>
+ )}
+ </label>
+ <Input.Password
+ value={emailPassword}
+ onChange={(e: React.ChangeEvent<HTMLInputElement>) => setEmailPassword(e.target.value)}
+ placeholder={emailStored ? '••••••••' : 'App password or account password'}
+ style={{
+ backgroundColor: theme.colors.background,
+ borderColor: theme.colors.border,
+ color: theme.colors.text,
+ fontFamily: 'monospace',
+ }}
+ />
+ <div style={{
+ fontSize: theme.fontSize.xs,
+ color: theme.colors.textMuted,
+ marginTop: theme.spacing.sm,
+ lineHeight: 1.5,
+ }}>
+ {AUTH_NOTES[emailProvider]}
+ </div>
+ </div>
+
+ {emailProvider === 'custom' && (
+ <div style={{
+ padding: theme.spacing.md,
+ marginBottom: theme.spacing.lg,
+ border: `1px solid ${theme.colors.border}`,
+ borderRadius: theme.borderRadius.md,
+ backgroundColor: theme.colors.backgroundAlt,
+ }}>
+ <div style={{
+ fontSize: theme.fontSize.sm,
+ fontWeight: theme.fontWeight.medium,
+ color: theme.colors.text,
+ marginBottom: theme.spacing.md,
+ }}>
+ Custom IMAP / SMTP
+ </div>
+
+ <div style={{ display: 'flex', gap: theme.spacing.md, marginBottom: theme.spacing.md }}>
+ <div style={{ flex: 2 }}>
+ <label style={{ display: 'block', fontSize: theme.fontSize.xs, color: theme.colors.textSecondary, marginBottom: theme.spacing.xs }}>
+ IMAP Host
+ </label>
+ <Input
+ value={emailImapHost}
+ onChange={(e: React.ChangeEvent<HTMLInputElement>) => setEmailImapHost(e.target.value)}
+ placeholder="imap.example.com"
+ style={{ backgroundColor: theme.colors.background, borderColor: theme.colors.border, color: theme.colors.text }}
+ />
+ </div>
+ <div style={{ flex: 1 }}>
+ <label style={{ display: 'block', fontSize: theme.fontSize.xs, color: theme.colors.textSecondary, marginBottom: theme.spacing.xs }}>
+ IMAP Port
+ </label>
+ <InputNumber
+ value={emailImapPort}
+ onChange={(v) => setEmailImapPort(typeof v === 'number' ? v : 993)}
+ min={1}
+ max={65535}
+ style={{ width: '100%' }}
+ />
+ </div>
+ </div>
+
+ <div style={{ display: 'flex', gap: theme.spacing.md }}>
+ <div style={{ flex: 2 }}>
+ <label style={{ display: 'block', fontSize: theme.fontSize.xs, color: theme.colors.textSecondary, marginBottom: theme.spacing.xs }}>
+ SMTP Host
+ </label>
+ <Input
+ value={emailSmtpHost}
+ onChange={(e: React.ChangeEvent<HTMLInputElement>) => setEmailSmtpHost(e.target.value)}
+ placeholder="smtp.example.com"
+ style={{ backgroundColor: theme.colors.background, borderColor: theme.colors.border, color: theme.colors.text }}
+ />
+ </div>
+ <div style={{ flex: 1 }}>
+ <label style={{ display: 'block', fontSize: theme.fontSize.xs, color: theme.colors.textSecondary, marginBottom: theme.spacing.xs }}>
+ SMTP Port
+ </label>
+ <InputNumber
+ value={emailSmtpPort}
+ onChange={(v) => setEmailSmtpPort(typeof v === 'number' ? v : 465)}
+ min={1}
+ max={65535}
+ style={{ width: '100%' }}
+ />
+ </div>
+ </div>
+ </div>
+ )}
+
+ {emailError && (
+ <Alert type="error" message={emailError} showIcon style={{ marginBottom: theme.spacing.lg }} />
+ )}
+
+ <div style={{ flex: 1 }} />
+
+ <div style={{
+ display: 'flex',
+ gap: theme.spacing.sm,
+ justifyContent: 'center',
+ paddingTop: theme.spacing.md,
+ borderTop: `1px solid ${theme.colors.border}`,
+ }}>
+ <Button
+ onClick={handleEmailSave}
+ loading={emailLoading === 'save'}
+ disabled={!emailAddress.trim() || (!emailPassword.trim() && !emailStored)}
+ style={{
+ backgroundColor: `${theme.dracula.green}25`,
+ borderColor: `${theme.dracula.green}60`,
+ color: theme.dracula.green,
+ }}
+ >
+ Save
+ </Button>
+ {emailStored && (
+ <Button
+ onClick={handleEmailRemove}
+ loading={emailLoading === 'remove'}
+ style={{
+ backgroundColor: `${theme.dracula.pink}25`,
+ borderColor: `${theme.dracula.pink}60`,
+ color: theme.dracula.pink,
+ }}
+ >
+ Remove
+ </Button>
+ )}
+ </div>
+ </div>
+ );
+ }
+
// Google Workspace panel (Gmail, Calendar, Drive, Sheets, Tasks, Contacts)
if (selectedItem.panelType === 'gmail') {
return (
diff --git a/docs-internal/email_service.md b/docs-internal/email_service.md
new file mode 100644
index 00000000..ea97c695
--- /dev/null
+++ b/docs-internal/email_service.md
@@ -0,0 +1,399 @@
+# Email Service
+
+IMAP/SMTP email integration via the [Himalaya CLI](https://github.com/pimalaya/himalaya). Supports any IMAP/SMTP provider: Gmail, Outlook/Office 365, Yahoo, iCloud, ProtonMail (Bridge), Fastmail, and custom/self-hosted servers. Three workflow nodes (`emailSend`, `emailRead`, `emailReceive`) with dual-purpose workflow + AI tool integration for send/read, and a polling trigger for receive.
+
+## Architecture
+
+```
+ ┌──────────────────────────────────────────────┐
+ │ EmailService (singleton) │
+ │ │
+ handler ─────────► resolve_credentials(params) -> dict │
+ (email.py) │ params > preset (email_providers.json) │
+ │ > stored API keys (AuthService) │
+ │ │
+ │ send(params) -> dict │
+ │ read(params) -> dict (7 operations) │
+ │ poll_ids(creds, folder) -> set[str] │
+ │ fetch_detail(creds, msg_id, folder) -> dict │
+ │ resolve_poll_params(params) -> dict │
+ └───────────┬───────────────────┬──────────────┘
+ │ │
+ ▼ ▼
+ HimalayaService AuthService
+ (CLI wrapper) (get_api_key,
+ │ store_api_key)
+ │ subprocess
+ ▼
+ `himalaya` CLI binary
+ generates temp TOML config,
+ calls IMAP/SMTP backends
+```
+
+### Request Flow (emailSend)
+
+```
+emailSend node
+ │
+ ▼
+handle_email_send(node_id, type, params, ctx)
+ │
+ ▼
+EmailService.send(params)
+ │
+ ├── resolve_credentials(params)
+ │ node params > email_providers.json preset
+ │ > stored "email_*" API keys
+ │
+ ▼
+HimalayaService.send_email(creds, to, subject, body, ...)
+ │
+ ├── _account_name(creds) = email prefix, sanitized
+ ├── _generate_config() writes TOML to tempfile
+ ├── compose MIME message (RFC 2822)
+ ├── subprocess: himalaya -c <tmp> -a <acct> --output json message send
+ │ (stdin = MIME message)
+ ├── parse JSON stdout, delete tempfile
+ ▼
+{"success": True, "result": {...}, "execution_time": 0.34}
+```
+
+### Credentials Resolution Precedence
+
+For every field in the returned credentials dict:
+
+| Priority | Source | Example |
+|---|---|---|
+| 1 (highest) | **Node parameter** (per-node override) | `params["imap_host"]` |
+| 2 | **Provider preset** from `email_providers.json` | `providers.gmail.imap_host = "imap.gmail.com"` |
+| 3 (lowest) | **Stored API key** via `AuthService.get_api_key()` | `email_imap_host` |
+
+Custom/self-hosted providers rely on stored custom keys because their presets are empty. Gmail and other named presets skip the custom-key lookup because the preset always wins first.
+
+## Key Files
+
+| File | Description |
+|------|-------------|
+| `server/services/himalaya_service.py` | CLI wrapper. Subprocess-based invocation, temp TOML config generation, JSON output parsing. Singleton via `get_himalaya_service()`. |
+| `server/services/email_service.py` | Orchestration layer. Credential resolution, operation dispatch, polling helpers. Singleton via `get_email_service()`. |
+| `server/config/email_providers.json` | Provider presets (IMAP/SMTP host/port/encryption per provider) + defaults + polling config. Cached on first load. |
+| `server/services/handlers/email.py` | Three thin node handlers: `handle_email_send`, `handle_email_read`, `handle_email_receive`. |
+| `server/services/node_executor.py` | Handler registry entries: `emailSend`, `emailRead`, `emailReceive`. |
+| `server/services/event_waiter.py` | `TRIGGER_REGISTRY['emailReceive']` + `build_email_filter`. |
+| `server/services/deployment/manager.py` | `_create_email_poll_coroutine` factory for deployment-mode polling. |
+| `server/services/ai.py` | `EmailSendSchema`, `EmailReadSchema` Pydantic schemas for AI tool calling + `DEFAULT_TOOL_NAMES` / `DEFAULT_TOOL_DESCRIPTIONS` entries. |
+| `server/services/handlers/tools.py` | `_execute_email_tool` dispatch for `emailSend` / `emailRead` when called by an AI Agent. |
+| `server/constants.py` | `EMAIL_TYPES`, `EMAIL_TOOL_TYPES`, plus `emailReceive` in `POLLING_TRIGGER_TYPES` and `WORKFLOW_TRIGGER_TYPES`. |
+| `client/src/nodeDefinitions/emailNodes.ts` | Three node definitions (send/read/receive) with provider dropdown, operation dispatcher, displayOptions.show. |
+| `client/src/assets/icons/email/` | `send.svg`, `read.svg`, `receive.svg` + `index.ts` registering them as data URIs via `?raw` import. |
+| `client/src/components/CredentialsModal.tsx` | Email credentials panel (provider dropdown, email/password inputs, conditional custom IMAP/SMTP section). |
+
+## EmailService API
+
+**File:** `server/services/email_service.py`
+
+### `resolve_credentials(params: Dict) -> Dict`
+
+Builds the credentials dict consumed by `HimalayaService`. Required before every operation. Raises `ValueError` if `email_address` or `email_password` is not set (neither in params nor stored).
+
+Returned keys:
+- `email` (str, required) — account address, used as IMAP/SMTP login
+- `password` (str, required) — raw password or app password
+- `display_name` (str) — optional display name (only written to TOML if non-empty)
+- `imap_host`, `imap_port`, `imap_encryption` — resolved via precedence chain
+- `smtp_host`, `smtp_port`, `smtp_encryption` — resolved via precedence chain
+
+Ports come from any level of precedence as `int` (the internal `_coerce_port` helper converts stored string values safely).
+
+### `send(params: Dict) -> Dict`
+
+Resolves credentials, calls `HimalayaService.send_email()`, and returns the result merged with `{"from": creds["email"]}`. Validates `to` and `subject` are non-empty.
+
+### `read(params: Dict) -> Dict`
+
+Operation dispatcher keyed by `params["operation"]` (default `"list"`):
+
+| Operation | HimalayaService method | Required params |
+|---|---|---|
+| `list` | `list_envelopes` | - |
+| `search` | `search_envelopes` | `query` |
+| `read` | `read_message` | `message_id` |
+| `folders` | `list_folders` | - |
+| `move` | `move_message` | `message_id`, `target_folder` |
+| `delete` | `delete_message` | `message_id` |
+| `flag` | `flag_message` | `message_id` |
+
+Return shape: `{"operation": ..., "folder": ..., ...data}` where `data` is merged in if it's a dict, or wrapped as `{"data": data}` otherwise.
+
+### `resolve_poll_params(params: Dict) -> Dict`
+
+Reads polling config from `email_providers.json` (`polling.interval`, `polling.min_interval`, `polling.max_interval`) and clamps the user-provided `poll_interval` into range. Returns `{"interval", "folder", "mark_as_read"}`.
+
+### Polling helpers
+
+- `poll_ids(creds, folder) -> Set[str]` — Calls `list_envelopes` with `baseline_page_size` (from JSON config), extracts envelope IDs as strings for baseline/diff.
+- `fetch_detail(creds, msg_id, folder) -> Dict` — Calls `read_message` and merges `{message_id, folder}` into the result for downstream consumers.
+
+## HimalayaService API
+
+**File:** `server/services/himalaya_service.py`
+
+### CLI execution model
+
+Every operation follows the same pattern inside `execute()`:
+
+1. `ensure_binary()` — locate `himalaya` on `PATH` via `shutil.which`. Caches the path on the singleton. Raises `RuntimeError` with install instructions if missing.
+2. `_generate_config(account_name, credentials)` — build TOML config as a single string (no template file; uses Python f-strings).
+3. `tempfile.NamedTemporaryFile(suffix=".toml", delete=False)` — write config to a temp file.
+4. `asyncio.create_subprocess_exec(binary, -c <tmp>, -a <account>, --output json, <args>)`
+5. Pipe `stdin_data` if provided (used by `send_email` to deliver the MIME message).
+6. `asyncio.wait_for(proc.communicate(...), timeout=60)` — enforces a 60s budget.
+7. Parse JSON stdout (`json.loads`). Fall back to `{"raw_output": stdout_str}` on JSON decode error.
+8. `finally`: delete the temp config file with `Path.unlink(missing_ok=True)`.
+
+**Error handling:** non-zero exit raises `RuntimeError(f"himalaya error: {stderr}")`. The handler layer catches this and returns the standard error-shaped result dict.
+
+### High-level methods
+
+| Method | Himalaya subcommand | Notes |
+|---|---|---|
+| `send_email(creds, to, subject, body, cc, bcc, body_type)` | `message send` (stdin) | Composes MIME via `email.mime` stdlib. `body_type="html"` wraps in `MIMEMultipart("alternative")`; otherwise `MIMEText`. |
+| `list_envelopes(creds, folder, page, page_size)` | `envelope list -f <folder> --page N --page-size M` | |
+| `search_envelopes(creds, query, folder)` | `envelope list -f <folder> --query <q>` | |
+| `read_message(creds, message_id, folder)` | `message read <id> -f <folder>` | |
+| `move_message(creds, message_id, target_folder, folder)` | `message move <id> <target> -f <folder>` | |
+| `delete_message(creds, message_id, folder)` | `message delete <id> -f <folder>` | |
+| `flag_message(creds, message_id, flag, action, folder)` | `flag add/remove <id> --flag <name> -f <folder>` | `action` must be `"add"` or `"remove"`. |
+| `list_folders(creds)` | `folder list` | |
+
+### Account naming
+
+`_account_name(credentials)` derives a consistent TOML section name from the email address:
+
+```python
+"[email protected]" -> "jane_doe_bot"
+```
+
+Dots and `+` are replaced with underscores so the name is valid as a TOML table key. The account name is arbitrary -- Himalaya just needs a consistent label between config and CLI invocation.
+
+## Node Catalog
+
+### emailSend — Dual-purpose (workflow node + AI tool)
+
+Send email via SMTP. Group: `['email', 'tool']`. Two outputs (`main`, `tool`).
+
+**Parameters:**
+| Name | Type | Required | Description |
+|---|---|---|---|
+| `provider` | options | yes | `gmail`, `outlook`, `yahoo`, `icloud`, `protonmail`, `fastmail`, `custom` |
+| `to` | string | yes | Recipient(s), comma-separated |
+| `subject` | string | yes | |
+| `body` | string | yes | Plain text or HTML (per `body_type`) |
+| `cc` | string | no | |
+| `bcc` | string | no | |
+| `body_type` | options | no | `text` (default) or `html` |
+
+**AI tool schema:** `EmailSendSchema` (same fields as node params, `body_type` default `"text"`, `cc`/`bcc` optional). When the LLM invokes `email_send`, `_execute_email_tool` routes to `EmailService.send()` with the LLM args merged over the node params.
+
+### emailRead — Dual-purpose (workflow node + AI tool)
+
+Read/search/manage emails via IMAP. Group: `['email', 'tool']`. Two outputs (`main`, `tool`).
+
+**Parameters** (all conditional via `displayOptions.show` on `operation`):
+| Name | Shown when operation is | Description |
+|---|---|---|
+| `operation` | always | list / search / read / folders / move / delete / flag |
+| `folder` | list, search, read, move, delete, flag | default `INBOX` |
+| `query` | search | Himalaya search syntax (`from:`, `subject:`, etc.) |
+| `message_id` | read, move, delete, flag | |
+| `target_folder` | move | |
+| `flag` | flag | Seen / Answered / Flagged / Draft / Deleted |
+| `flag_action` | flag | add / remove |
+| `page` | list | default 1 |
+| `page_size` | list | default 20, max 100 |
+
+**AI tool schema:** `EmailReadSchema` exposes every operation and all operation-specific fields as optional. The LLM picks an `operation` and fills the relevant subset.
+
+### emailReceive — Polling trigger
+
+Group: `['email', 'trigger']`. No inputs. Single output `main` with the new email data.
+
+**Parameters:**
+| Name | Default | Description |
+|---|---|---|
+| `provider` | gmail | Provider preset |
+| `folder` | INBOX | Mailbox to monitor |
+| `poll_interval` | 60 | seconds (clamped 30..3600) |
+| `filter_query` | `""` | Server-side filter (currently applied client-side in `build_email_filter`) |
+| `mark_as_read` | false | If true, adds `Seen` flag to new messages after fetch |
+
+**Baseline detection:** On first execution the handler calls `poll_ids(creds, folder)` to capture the set of currently-existing envelope IDs. The poll loop then diffs against this baseline -- only newly appearing IDs trigger the workflow. This avoids firing on existing historical mail.
+
+**Event dispatch:** When a new message arrives, the handler:
+1. Fetches full detail via `fetch_detail`
+2. Optionally flags it as read
+3. Dispatches `event_waiter.dispatch("email_received", email_data)` so deployment-mode listeners see it
+4. Returns the result (single-shot in standalone mode; the deployment manager's poll coroutine keeps looping)
+
+## Deployment Mode (Continuous Polling)
+
+**File:** `server/services/deployment/manager.py`
+
+When a workflow containing `emailReceive` is **deployed** (not just run once), the `DeploymentManager` routes the trigger to a polling coroutine instead of a one-shot execution:
+
+```python
+def _create_poll_coroutine(self, node_type, node_id, params):
+ if node_type == 'emailReceive':
+ return self._create_email_poll_coroutine(node_id, params)
+```
+
+`_create_email_poll_coroutine` returns an async poll loop that:
+1. Resolves credentials once
+2. Establishes the baseline via `svc.poll_ids(creds, folder)`
+3. On each iteration (clamped interval from `resolve_poll_params`):
+ - Polls for current IDs
+ - Computes `new_ids = current - seen`
+ - For each new ID: fetches detail, optionally marks read, enqueues via `await queue.put(email_data)` for the per-run workflow executor
+ - Handles `asyncio.CancelledError` cleanly on teardown
+
+The continuous loop delegates entirely to `EmailService` — no credential resolution or polling logic is duplicated in the deployment manager.
+
+## Credentials Storage
+
+### API key names
+
+Stored via `AuthService.store_api_key()` / read via `.get_api_key()`. All keys live in the `EncryptedAPIKey` table (separate from OAuth tokens).
+
+**Required keys (any provider):**
+| Key | Stored by | Read by |
+|---|---|---|
+| `email_provider` | Credentials Modal | `resolve_credentials` (defaults to `gmail`) |
+| `email_address` | Credentials Modal | `resolve_credentials` |
+| `email_password` | Credentials Modal | `resolve_credentials` |
+
+**Optional keys (custom provider only):**
+| Key | Purpose |
+|---|---|
+| `email_imap_host` | Fallback IMAP hostname when preset is empty |
+| `email_imap_port` | Fallback IMAP port (stored as string, coerced to int) |
+| `email_imap_encryption` | `tls` / `start-tls` / `none` |
+| `email_smtp_host` | Fallback SMTP hostname |
+| `email_smtp_port` | Fallback SMTP port |
+| `email_smtp_encryption` | `tls` / `start-tls` / `none` |
+
+These custom keys are **only used when the preset for the selected provider has empty host/port fields** (i.e., `provider == 'custom'`). For named providers like Gmail, the preset always wins before the stored custom keys are consulted.
+
+### Credentials Modal UI
+
+**File:** `client/src/components/CredentialsModal.tsx`
+
+The Email category appears between Productivity and Android in the sidebar. The panel provides:
+
+- **Provider dropdown** (7 options mirroring `email_providers.json`)
+- **Email address** input
+- **Password** input (secret, with "leave blank to keep existing" placeholder when already stored)
+- **Per-provider auth note** (e.g., "Use an App Password from Google Account > Security > 2-Step Verification")
+- **Conditional custom IMAP/SMTP block** shown only when `provider === 'custom'`:
+ - IMAP host (text) + IMAP port (number, default 993)
+ - SMTP host (text) + SMTP port (number, default 465)
+- **Save** button — writes `email_provider`, `email_address`, and conditionally `email_password` (only if user typed a new one) + the four custom IMAP/SMTP keys when applicable.
+- **Remove** button — clears all seven `email_*` keys.
+
+Status is shown via `getSpecialStatus(item)` returning `{ connected: !!emailStored, label: emailAddress || 'Not configured' }`. No WebSocket connection is needed because email credentials are pure API keys (no live session like Telegram or WhatsApp).
+
+## Configuration File
+
+**File:** `server/config/email_providers.json`
+
+```json
+{
+ "defaults": {
+ "provider": "gmail",
+ "folder": "INBOX",
+ "body_type": "text",
+ "page_size": 20,
+ "flag": "Seen",
+ "flag_action": "add"
+ },
+ "polling": {
+ "interval": 60,
+ "min_interval": 30,
+ "max_interval": 3600,
+ "baseline_page_size": 50
+ },
+ "providers": {
+ "gmail": {
+ "name": "Gmail",
+ "imap_host": "imap.gmail.com",
+ "imap_port": 993,
+ "imap_encryption": "tls",
+ "smtp_host": "smtp.gmail.com",
+ "smtp_port": 465,
+ "smtp_encryption": "tls",
+ "auth_note": "Use App Password from Google Account > Security > 2-Step Verification"
+ },
+ "outlook": { "...": "..." },
+ "yahoo": { "...": "..." },
+ "icloud": { "...": "..." },
+ "protonmail": {
+ "imap_host": "127.0.0.1", "imap_port": 1143, "imap_encryption": "none",
+ "smtp_host": "127.0.0.1", "smtp_port": 1025, "smtp_encryption": "none",
+ "auth_note": "Requires ProtonMail Bridge running locally"
+ },
+ "fastmail": { "...": "..." },
+ "custom": {
+ "imap_host": "", "imap_port": 993, "imap_encryption": "tls",
+ "smtp_host": "", "smtp_port": 465, "smtp_encryption": "tls",
+ "auth_note": "Enter your mail server details"
+ }
+ }
+}
+```
+
+Loaded lazily by `EmailService._load_config()` and cached in a module-level `_CONFIG` variable. To add a new provider, edit only this JSON — no code changes required.
+
+**Zero magic numbers:** every default, clamp, and preset lives in this file. `resolve_poll_params` reads the polling defaults; `EmailService.read()` reads `defaults.page_size`, `defaults.flag`, etc.; the provider dropdown options in `CredentialsModal.tsx` mirror the `providers` keys.
+
+## Installation Requirement
+
+The `himalaya` CLI must be installed and on `PATH`. Install via:
+
+```bash
+# macOS
+brew install himalaya
+
+# Linux / macOS with Rust toolchain
+cargo install himalaya
+
+# Pre-built binaries (Linux, macOS, Windows)
+# https://github.com/pimalaya/himalaya/releases
+```
+
+`HimalayaService.ensure_binary()` caches the resolved path on the singleton after first detection. If missing, the handler returns:
+
+```json
+{
+ "success": false,
+ "error": "himalaya CLI not found in PATH. Install via: cargo install himalaya, brew install himalaya, ..."
+}
+```
+
+## Provider-Specific Notes
+
+| Provider | Password type | Notes |
+|---|---|---|
+| **Gmail** | App Password | Requires 2-Step Verification enabled first |
+| **Outlook / Office 365** | Account or App Password | STARTTLS on port 587 |
+| **Yahoo** | App Password | Requires "Allow apps that use less secure sign-in" or App Password |
+| **iCloud** | App-Specific Password | Generate from appleid.apple.com |
+| **ProtonMail** | Bridge password | Requires running ProtonMail Bridge locally. IMAP `localhost:1143`, SMTP `localhost:1025`, encryption `none` (bridge handles TLS internally). |
+| **Fastmail** | App Password | Generate from Settings > Privacy & Security |
+| **Custom** | Whatever the server accepts | Must fill IMAP/SMTP host + port in the Credentials Modal's custom block. |
+
+## Related Docs
+
+- [Node Creation Guide](./node_creation.md) — general pattern for adding workflow nodes
+- [Dual-Purpose Tool Guide](./dual_purpose_tool_node_creation.md) — how `emailSend`/`emailRead` work as both workflow nodes and AI tools
+- [Event Waiter System](./event_waiter_system.md) — trigger registration for `emailReceive`
+- [New Service Integration](./new_service_integration.md) — end-to-end integration pattern (use Google Workspace as a richer OAuth example)
+- [Credentials Encryption](./credentials_encryption.md) — how `email_*` keys are encrypted on disk
diff --git a/docs-internal/workflow-schema.md b/docs-internal/workflow-schema.md
index 8767e28e..487369df 100644
--- a/docs-internal/workflow-schema.md
+++ b/docs-internal/workflow-schema.md
@@ -149,6 +149,12 @@ Consolidated operation-based nodes sharing one OAuth connection. See [new_servic
- `telegramSend` - Dual-purpose: text, photo, document, location, contact
- `telegramReceive` - Event-driven trigger via long-polling
+### Email Nodes (3 nodes)
+IMAP/SMTP integration via the [Himalaya CLI](https://github.com/pimalaya/himalaya). Supports Gmail, Outlook, Yahoo, iCloud, ProtonMail (Bridge), Fastmail, and custom/self-hosted servers. Credentials stored via `auth_service.store_api_key()` -- see [email_service.md](email_service.md).
+- `emailSend` - Dual-purpose: send via SMTP (to, subject, body, cc, bcc, body_type text/html)
+- `emailRead` - Dual-purpose: list / search / read / folders / move / delete / flag via IMAP
+- `emailReceive` - Polling trigger with baseline detection (poll_interval 30-3600s)
+
### Social Nodes (2 nodes)
Unified multi-platform messaging (WhatsApp, Telegram, Discord, Slack, SMS, Email, Matrix, Teams):
- `socialReceive` - Normalize messages from platform triggers
diff --git a/server/services/email_service.py b/server/services/email_service.py
index cc17ae65..7070ed05 100644
--- a/server/services/email_service.py
+++ b/server/services/email_service.py
@@ -55,7 +55,12 @@ class EmailService:
# -- credentials --
async def resolve_credentials(self, params: Dict[str, Any]) -> Dict[str, Any]:
- """Merge stored creds + provider presets + param overrides."""
+ """Merge stored creds + provider presets + param overrides.
+
+ Precedence (per field): node params > provider preset > stored custom keys.
+ Stored custom keys (email_imap_host, email_smtp_port, etc.) are used when
+ the provider is 'custom' or when a preset field is empty.
+ """
from core.container import container
auth = container.auth_service()
@@ -70,17 +75,31 @@ class EmailService:
if not password:
raise ValueError("Email password not configured")
- # Every field: param override > provider preset (preset already has port/host/encryption)
+ def _coerce_port(value: Any) -> Any:
+ if value in (None, ""):
+ return None
+ try:
+ return int(value)
+ except (TypeError, ValueError):
+ return None
+
+ imap_host = params.get("imap_host") or preset.get("imap_host") or await auth.get_api_key("email_imap_host") or ""
+ imap_port = params.get("imap_port") or preset.get("imap_port") or _coerce_port(await auth.get_api_key("email_imap_port"))
+ imap_encryption = params.get("imap_encryption") or preset.get("imap_encryption") or await auth.get_api_key("email_imap_encryption")
+ smtp_host = params.get("smtp_host") or preset.get("smtp_host") or await auth.get_api_key("email_smtp_host") or ""
+ smtp_port = params.get("smtp_port") or preset.get("smtp_port") or _coerce_port(await auth.get_api_key("email_smtp_port"))
+ smtp_encryption = params.get("smtp_encryption") or preset.get("smtp_encryption") or await auth.get_api_key("email_smtp_encryption")
+
return {
"email": email,
"password": password,
"display_name": params.get("display_name", ""),
- "imap_host": params.get("imap_host") or preset.get("imap_host", ""),
- "imap_port": params.get("imap_port") or preset.get("imap_port"),
- "imap_encryption": params.get("imap_encryption") or preset.get("imap_encryption"),
- "smtp_host": params.get("smtp_host") or preset.get("smtp_host", ""),
- "smtp_port": params.get("smtp_port") or preset.get("smtp_port"),
- "smtp_encryption": params.get("smtp_encryption") or preset.get("smtp_encryption"),
+ "imap_host": imap_host,
+ "imap_port": imap_port,
+ "imap_encryption": imap_encryption,
+ "smtp_host": smtp_host,
+ "smtp_port": smtp_port,
+ "smtp_encryption": smtp_encryption,
}
def resolve_poll_params(self, params: Dict[str, Any]) -> Dict[str, Any]: