Self-improving AI Employees for everyone
Email Send (emailSend)
| Field | Value |
|---|---|
| Category | email / tool (dual-purpose) |
| Backend handler | server/nodes/email/email_send/__init__.py — dispatched via BaseNode.execute() -> @Operation("send") -> EmailService.send (_service.py) |
| Tests | server/tests/nodes/test_email.py |
| Skill (if any) | none shipped |
| Dual-purpose tool | yes - connect to input-tools as the node's own name |
Purpose
Send an email over SMTP via the bundled Himalaya
CLI. Works with any IMAP/SMTP provider; Gmail, Outlook/O365, Yahoo, iCloud,
ProtonMail (Bridge), Fastmail and custom/self-hosted are provided as built-in
presets (see server/config/email_providers.json). When wired to an AI agent's
input-tools handle the LLM fills the same parameter schema.
Inputs (handles)
| Handle | Connection type | Required | Purpose |
|---|---|---|---|
input-main |
main | no | Upstream data; not consumed directly - all inputs come from parameters |
Parameters
| Name | Type | Default | Required | displayOptions.show | Description |
|---|---|---|---|---|---|
provider |
options | gmail |
no | - | One of gmail / outlook / yahoo / icloud / protonmail / fastmail / custom. Picks the preset in email_providers.json |
to |
string | "" |
yes | - | Comma-separated recipient list |
subject |
string | "" |
yes | - | Email subject line |
body |
string | "" |
no | - | Email body (plain text or HTML, see body_type); rows: 6 textarea hint |
cc |
string | "" |
no | - | CC recipients, only added if truthy |
bcc |
string | "" |
no | - | BCC recipients, only added if truthy |
body_type |
options | text |
no | - | text or html. HTML sends a multipart/alternative MIME message |
Also resolved at runtime (not node-exposed):
email/password/display_name- from node params OR storedemail_address/email_password/email_display_nameAPI keys.imap_*/smtp_*- from node params OR preset OR stored custom keys (see Decision Logic).
Outputs (handles)
| Handle | Shape | Description |
|---|---|---|
output-main |
object | Himalaya send result merged with from (sender address) |
When wired to an AI agent's input-tools handle (usable_as_tool = True, tool name email_send), the same payload is returned to the LLM via the tool-dispatch path — there is no separate output-tool handle.
Output payload
{
from: string; // resolved sender address from credentials
// plus whatever keys Himalaya's `message send` command returns (often {} on success)
raw_output?: string; // present when Himalaya stdout is non-JSON
}
Wrapped in the standard envelope: { success: true, result: <payload>, execution_time: number, node_id, node_type, timestamp }.
Logic Flow
flowchart TD
A[BaseNode.execute -> Operation send] --> B[EmailService.send params]
B --> C[resolve_credentials]
C -->|no email/password| Ee[ValueError -> error envelope]
C --> D[Merge with provider preset from email_providers.json]
D --> E[HimalayaService.send_email]
E --> F[Build MIME message text or multipart/alternative]
F --> G[ensure_binary: which himalaya]
G -->|missing| Eb[RuntimeError -> error envelope]
G --> H[Write TOML config to tempfile]
H --> I[subprocess: himalaya -c cfg -a acct message send<br/>stdin = MIME bytes, timeout 60s]
I -->|returncode != 0| Er[RuntimeError -> error envelope]
I --> J[Parse JSON stdout or wrap as raw_output]
J --> K[tempfile unlinked in finally]
K --> L[Merge from into result]
L --> M[Return success envelope]
Decision Logic
- Credential precedence (per field) in
EmailService.resolve_credentials:- Node parameter (e.g.
imap_hoston the node). - Provider preset from
email_providers.json(e.g.gmail->imap.gmail.com). - Stored custom API key (
email_imap_host,email_imap_port, etc.). Only reached when the preset field is empty, which in practice meansprovider == 'custom'.
- Node parameter (e.g.
- Port coercion: stored ports are strings in the API-key store;
_coerce_portcasts them tointand silently returnsNoneon invalid values. - Missing email/password:
resolve_credentialsraisesValueError("Email address not configured"/"Email password not configured") before any subprocess is spawned ->BaseNode.execute()catches and returnssuccess=false. - HTML vs plain:
body_type == 'html'->multipart/alternativewith an HTML part (no plain-text fallback part is attached). Anything else -> a singletext/plainpart. - CC/BCC headers: only set when the parameter is truthy. BCC is added as a header (visible in the composed MIME) - Himalaya is responsible for stripping it before sending.
- Account name: derived from the email local-part via
HimalayaService._account_name([email protected]->john_doe). Dots and+are replaced with_. - Subprocess errors: non-zero returncode raises
RuntimeError("himalaya error: <stderr>");BaseNode.execute()'sexcept Exceptioncatches and emits the error envelope (with full traceback logging).
Side Effects
- Database writes: none (no API usage tracking for email).
- Broadcasts: none.
- External API calls: none direct - SMTP traffic is handled entirely by
the
himalayabinary. - File I/O:
- Writes a Himalaya TOML config (containing the plaintext password) to a
NamedTemporaryFileprefixedhimalaya_in the OS temp dir. - Unlinks the tempfile in the
finallyblock ofHimalayaService.execute.
- Writes a Himalaya TOML config (containing the plaintext password) to a
- Subprocess: spawns
himalaya -c <tmpfile> -a <account> --output json message sendwith the composed MIME message on stdin; timeout 60s.
External Dependencies
- Binary:
himalayamust be onPATH. Detected viashutil.whichand cached onHimalayaService._binary_path. - Credentials:
auth_service.get_api_key('email_address'),get_api_key('email_password'), and (forprovider='custom') the six custom host/port/encryption keys. All optional if their values are passed directly as node parameters. - Config:
server/config/email_providers.jsonfor presets and defaults. - Python packages: stdlib only (
asyncio,email.mime.*,tempfile,shutil).
Edge cases & known limits
- Credentials hit the filesystem: the generated TOML contains the raw
password in plaintext on disk for the duration of the subprocess call. Best-
effort cleanup happens in
finally, but a crash betweentmp.flush()andunlinkcan leave it behind. - No retry / idempotency: a transient SMTP failure returns
success=falseand the caller must re-run the node; there is no queue. - Body escaping: values are not escaped when formatted into the TOML
config. A password or host containing
"would produce invalid TOML and a confusinghimalaya errorstring. - 60s hard timeout: SMTP sends that exceed 60 seconds raise
asyncio.TimeoutErrorfromHimalayaService.execute(not caught as a special case) and surface as a generic error envelope. - No attachments: the current handler only composes a single text or HTML part; attachments are not supported.
Related
- Companion nodes:
emailRead,emailReceive - Architecture docs: Email Service, Credentials Encryption