Email

Email in the platform is four nodes and one connection that carries two different things at once: the sending server (SMTP) and the mailbox server (IMAP or POP3). This is not a simplification for the form’s sake: at every provider those are two different hosts with different ports and different encryption, and splitting them would mean two connections to one mailbox that sooner or later disagree about the password.

The connection: two legs, one password

Created in Settings → Integrations, kind Email. The general mechanics (secret encryption, permissions, port-beats-field) are in the integrations overview.

The Provider picker fills in both legs in one click. There are four presets, and they differ in more than host names:

The SMTP port decides how sending is encrypted: 465 encrypts from the first byte, 587 opens in the clear and upgrades to TLS. These are not interchangeable numbers — the wrong one means “does not send at all”, not “sends slower”.

The SMTP host must not be left empty. At all four providers above it differs from the mailbox host; with an empty field, sending falls back to the mailbox host and fails. The connection check does not fail over an empty field — it reports it as “not configured”: a connection created only for reading has no sending leg, and failing the check over that would be wrong.

IMAP or POP3. IMAP has folders, server-side search and a “seen” flag. POP3 has none of them: no folders, no search, no flags. Choosing POP3 is not “lighter”, it is poorer — three fields on the fetch node stop meaning anything (see below). Take IMAP whenever the provider offers it.

Four nodes

The connection arrives one of two ways: an Email Config node wired by a data edge into the email_config port, or a connection picked in the working node’s own form. The port beats the field. The port is required: with neither wired nor filled, the editor warns and the run and deploy gates reject — the refusal arrives before a paid run reaches the send.

Sending

Every field of the message is templated, meaning values from the run are substituted into it: {{ inputs.input.email }} into the recipient, a model’s answer into the body. Two are mandatory — recipient and subject; if the template in either resolves to an empty string the node fails rather than sending a subject-less message to nobody.

The HTML switch decides how the provider renders the body: as markup or as literal text. The sender defaults to the connection’s login; the “from address” and “from name” fields in the node’s advanced section override it for one message. The platform always keeps the envelope address equal to the header address — otherwise the recipient’s SPF check treats the message as a forgery.

The node outputs a message_id — the identifier it assigned to the message itself. It is what ties a sent message to a row in your own database.

Reading

The node pulls a batch of messages and returns them as a list. Each carries uid, subject, sender, recipients, date, text body, HTML body and a “read” flag. Alongside: how many messages arrived and which folder they came from.

What gets pulled is chosen by the “what to fetch” field:

The count is capped at a hundred messages per call. Dates are parsed strictly: an unparsable date is rejected rather than quietly dropped — otherwise “since 1 July” would silently widen into “the whole folder”.

With POP3 selected, the three fields above mean nothing: the folder is always the inbox, the criterion is not applied, the flag is not set. The node does not hide this — its output leaves the “mailbox” field empty, so a downstream node cannot branch on a value that never existed.

Scenario: message → fields → record

The typical job looks like this: every N minutes pull the new messages, extract the fields you care about from each (who wrote, about which order, what they want) and put the result into a collection — or reply straight away.

A message body can be long, and it travels into the model in full and is billed by tokens. On a noisy mailbox it is cheaper to cut the noise earlier — by sender, right in the fetch criteria, rather than after the fact.

Email as an agent tool

Email Tool gives the model four operations: send a message, fetch messages, search by text and reply to a message by its uid. All four are on by default — unlike the calendar, where some operations are off. Worth remembering: a freshly dropped email tool on an agent means the model can send mail in your name.

Three differences between the tool and the identically named nodes, all of which only show up in use:

• fetching through the tool never sets the seen flag. The model is looking at a mailbox, not draining a queue, and it must not silently eat your cursor;
• replying is two operations in one: the tool locates the original by uid itself, takes the sender and subject from it and sends the answer. The model only needs a uid and the text;
• an error does not fail the run. The tool hands the model the error text together with a machine-readable code, and the model can correct itself — fix an address and try again. The code is what lets it tell “wrong password”, which is pointless to retry, from “server busy”, which is not.

Where this usually breaks

What next