Email (IMAP) trigger

Add an Email Trigger node (trigger_email) and Elizon watches a mailbox for you: every new email that matches your filters starts one run, with the message already parsed and its attachments already stored as files.

This is the trigger for work that arrives by email — supplier invoices, signed contracts, support requests, monitoring alerts — where the mail itself is the input.

Configuration

Connecting a mailbox

A password typed into the node is refused by the save itself. A credential written into a graph is stored with every saved version of that workflow, appears in every version diff, cannot be rotated, and would travel in an export — so it is never accepted in the first place.

Test connection signs in, lists the folders the account can see, and shows the unread count of the one you chose. It reads the saved node, so save the workflow before pressing it; nothing you have typed and not saved is sent anywhere.

OAuth2 for Microsoft 365 and Google Workspace is not available yet — these use a password or an app password today.

Which emails start a run

Every filter is applied by the mail server, not by Elizon after downloading, so a folder with ten years of mail in it is never fetched to find today's three invoices.

Output

The payload is flat, unlike the webhook and form paths — there is no HTTP request here to have a body:

Attachments are only fetched when Bring attachments into the run is on. You can narrow them by extension and cap their size; an attachment that is too large or the wrong type is skipped and the email still runs. Inline images that the HTML body refers to (a signature logo) are not treated as attachments.

Set Format to Raw to also get {{ trigger.raw }}, the whole message source. Every parsed field above is still there.

Email threading

{{ trigger.inReplyTo }} and {{ trigger.references }} tell you which earlier email a reply answers. They are read from the parsed headers, so a References header folded over several lines, or with commas between its ids, still comes out as a clean list of <id>s that you can compare. {{ trigger.headers.references }} keeps the raw header text, as before.

To match a customer's reply to the reminder you sent, store the reminder's messageId when Send Email sends it, then look up {{ trigger.inReplyTo }} — or any of {{ trigger.references }} — against what you stored. The Send Email page walks through the whole pattern.

After processing

This is a convenience for whoever reads the mailbox, not part of the exactly-once guarantee below. A message whose run started but whose flag could not be set — a read-only shared folder, say — is not processed twice.

How often, and what happens on the first run

Check every is 1 to 60 minutes, 5 by default. At most 50 emails start runs per check; anything more waits for the next one, so a burst is drained rather than dropped.

Exactly once, even across a crash

Each email starts exactly one run, forever. Elizon records its position in the folder (the IMAP UIDVALIDITY and the highest message it has handled) and gives each run an identity derived from the message itself, which the workflow engine refuses to start twice. So:

• a crash between starting a run and recording the position does not produce a second run;
• a crash before the run starts leaves the message to be picked up by the next check, rather than skipped;
• if the folder is recreated or renumbered by the server, Elizon re-reads where it has got to and continues, without re-firing mail it has already processed.

When it cannot sign in

A failed check does not retry in a tight loop. The error appears on the trigger in Studio — the message the server gave, when it happened, and how many checks in a row have failed — and the interval between attempts widens (double, then quadruple, up to eight times your configured interval) until it works again. After five consecutive failures the workflow's owner is notified. Nothing is consumed by a failed check: the next successful one picks up exactly where the last successful one left off.

The schedule itself is created, updated, or removed when you publish or unpublish — see Publishing.

Example

Forward each supplier invoice to an agent that extracts its fields:

name: Supplier invoices
description: Reads invoices that arrive in the invoices mailbox.
graph:
  nodes:
    - id: invoice-mail
      type: trigger_email
      position: { x: 0, y: 0 }
      data:
        filterUnseen: true
        filterSubjectContains: Invoice
        downloadAttachments: true
        attachmentExtensions: pdf
        postAction: markRead
        pollMinutes: 5
    - id: extract
      type: ai_agent
      position: { x: 280, y: 0 }
      data:
        mode: existing
        agent: agents.invoice-reader
        agentName: Invoice reader
        inputMappings: []
  edges:
    - { id: mail-to-extract, source: invoice-mail, target: extract }

The mailbox itself — host, port, security, username, password, mailbox — is not in a portable definition; whoever installs or builds the workflow sets it on the node.

In a Package

A Package can declare type: email in its triggers, and it declares nothing else — no mailbox, no server, no credential. Those are set by whoever installs it, in their own organization, on the installed workflow's Email Trigger node. A carried INBOX would point the trigger at whichever account the installer supplied, and a carried secret reference would resolve to a different value in their vault; both are worse than a node that plainly needs configuring.

triggers:
  - id: invoices-inbox
    type: email

On the node:

• Travels: postAction, filterUnseen, filterFrom, filterTo, filterSubjectContains, filterSince, downloadAttachments, attachmentExtensions, attachmentMaxBytes, format, pollMinutes, processExistingUnread, processExistingMax
• Converted: none
• Never carried: host, port, security, username, password, mailbox, moveToMailbox

A password typed into the node fails the build (SLOT_CREDENTIAL_VALUE_REJECTED); only a {{secret.KEY}} reference is accepted, and even that does not travel.