Skip to content
SupaCloud Docs
Select themeSelect language

Set up an IMAP trigger

An IMAP trigger polls a mailbox you own and starts a workflow run for every new message. Use it when the mail already arrives somewhere you control — a shared invoices@ box, a supplier notification address, a ticketing alias.

The workflow builder's palette — the node groups and, beneath them, the trigger groups including Messaging with its IMAP entry.The workflow builder's palette — the node groups and, beneath them, the trigger groups including Messaging with its IMAP entry.

Prerequisites

Section titled “Prerequisites”
  • An IMAP server reachable from your SupaCloud instance, plus a host, port, username and password.
  • A workspace where you may create resources and edit a workflow.
  • A workflow to start. If you have none yet, walk through Build your first workflow.

Steps

Section titled “Steps”

  1. Create the mailbox resource.

    In Resources → New, pick IMAP mailbox (inbound email / polling) and fill in IMAP host, Port (993 for implicit TLS), Username and Password. Leave Use TLS on unless your server only speaks plain IMAP on port 143.

    The password is stored as a secret and is never shown again.

  2. Add the trigger to your workflow.

    Open the workflow, drag IMAP out of the Messaging group in the trigger palette, and select the mailbox resource you just created.

  3. Choose the folder and the polling cadence.

    • Folder — INBOX unless you sort inbound mail into a subfolder first. A subfolder is often the tidier setup: your mail rules decide what the workflow ever sees.
    • Poll interval (seconds) — how often SupaCloud checks, between 10 and 3600 seconds (default 60).
    • Claim scope — leave it at default. Change it only when you deliberately want two triggers to process the same mailbox independently; each scope keeps its own record of what it has handled.

  4. Leave “New-message detection” on the UID cursor.

    This is how the trigger decides which messages are new, and the default — UID cursor (recommended) — is the one you want. See How new messages are detected below for what the other option costs you.

    With the UID cursor you also choose Start the cursor at:

    • The beginning of the folder (default) — everything already in the folder is delivered, oldest first. Nothing is skipped.
    • Only new mail from now on — the existing contents are passed over and only mail that arrives after you save is delivered. Pick this when you are attaching a trigger to a large archive.

    This choice applies to the first poll only. After that the trigger drives itself.

  5. Set how many messages one poll may take.

    Messages per poll (1–200, default 8) caps how much of a backlog a single poll drains. A larger backlog is simply drained by the following polls, so the setting trades catch-up speed against how long one poll occupies the scheduler. Raise it when you are importing a big folder; leave it at 8 for steady-state mail.

  6. Save, and check the first run.

    Save the workflow. Within one poll interval the first matching message starts a run. Open Runs to confirm the trigger context carries the sender, subject and body you expect.

How new messages are detected

Section titled “How new messages are detected”

Under UID cursor, SupaCloud keeps its own record per trigger and folder: the mailbox generation plus the highest message number it has finished processing. A poll asks the server for everything above that mark, and reads message bodies without opening them.

Read flag exists only so that triggers created before the change keep behaving as they did; nothing new should use it. If you see it selected on an existing trigger, switching to the UID cursor is safe: the trigger picks up from the current state of the folder, and messages already processed are recognised and not run twice.

What happens when the mailbox is rebuilt

Section titled “What happens when the mailbox is rebuilt”

Message numbers are only meaningful within one generation of a mailbox. If your provider recreates the folder — a restore from backup, a migration between servers, a mailbox rebuilt after corruption — the server announces a new generation and every stored number becomes meaningless.

SupaCloud notices, records the event, and re-reads the folder from the beginning. Messages it has already delivered are recognised by their permanent message id and are not run a second time; anything genuinely new is delivered. You do not have to do anything, but a trigger that keeps resetting is worth investigating on the mail-server side.

Reading the message in your workflow

Section titled “Reading the message in your workflow”

Every node downstream can read the message through ${{ trigger.… }}:

Field What it holds
from / to the sender / recipient line, verbatim
subject the subject, or an empty string
body_text / body_html the plain-text part; the HTML part when present
message_id the message’s permanent id
date the Date: line, verbatim
folder / uid where the message was read from, and its number
headers every header, keyed in lower case
attachments filename, content_type and size_bytes per attachment

Attachment contents are left on the server; only the summary reaches the workflow, so a large attachment never inflates a run.

Section titled “Related”