Start on an event: e-mail, database, MQTT

How an event becomes a run

A listener runs inside the Waiso workers — one live listener per trigger. It only records what arrives; about every second the API turns each recorded event into a run of the item’s published version, through the same checks as a schedule: credits, inputs and the item’s runs-at-the-same-time limit. Every event has a unique key, so the same e-mail, change or message is recorded once even if the listener sees it twice.

Add and test a trigger

1. 1
   Open Events

   Publish the item first — each event runs the published version. In its Triggers tab, under Events, press Add event trigger.

   Add event trigger
2. 2
   Pick the kind and fill it in

   Choose E-mail received, Database change or MQTT message, give it a Name and fill its fields (next sections). E-mail and MQTT have a step-by-step setup guide beside the form — Gmail, Outlook / Microsoft 365, other IMAP servers, and a broker.

3. 3
   Read What your code receives

   The panel lists every parameter of the published main and what it will get. If every event would be refused, it says so, and Show a main that receives it offers a main you can Copy or Insert in editor (a reviewable change in the editor — publish it afterwards).

4. 4
   Save and test

   Press Add trigger. Click the new row to open it, then Test: the target runs once with a sample event, tagged Test in the list. A test is not a real event, so the health line keeps saying Listening · waiting for the first real event.

What your code receives

One rule, the same in the form and in the run: a script parameter named event receives the whole event and nothing else; otherwise each parameter named like an event field gets that field. A flow gets every field as an input of the same name, plus event with all of it. A required parameter that no field fills makes every event Not run; a parameter with a default that no field fills keeps its default.

In Python an e-mail’s sender is from, a reserved word, so read e-mails through event; in TypeScript and JavaScript the same goes for a row change, because new is reserved. Each attachment is {name, size, contentType, s3Key, storage, s3}, stored in the project’s storage — pass it straight to waiso.s3.download.

import waiso

def main(event: dict):
    # event: from, to, cc, subject, text, html, date, messageId, attachments
    pdfs = [a for a in event["attachments"] if a["contentType"] == "application/pdf"]
    sizes = [len(waiso.s3.download(a)) for a in pdfs]
    return {"from": event["from"], "subject": event["subject"], "pdfs": len(pdfs), "bytes": sum(sizes)}

Try it with the real thing

Once a trigger has received an event, the editor’s Inputs card offers Use the last event — MQTT message, 2 min ago (or Use the test event): one click fills every input from it, by the same rule. For an object or list parameter, Use sample fills a value shaped like what your code reads.

Each kind’s settings

E-mail received (IMAP)

IMAP server, Port, Encrypted connection (TLS), User, Password (stored encrypted and never shown again; Gmail and Outlook need an app password), Folder, and the optional Sender contains and Subject contains. After the run starts: Leave it, Mark as read or Move to folder. Mail already in the folder never runs, and changing the server, account or folder starts reading from that moment. Messages over 25 MB run without their attachments.

Database change (PostgreSQL)

Pick a PostgreSQL connection from the project’s integrations, the Tables and the Changes (Insert, Update, Delete). Waiso reads the database’s change log by logical replication: on save it creates a publication and a replication slot (Setting up the database…), never touches your tables, and catches up on changes made while it was briefly down. Deleting the trigger removes both.

• wal_level = logical — otherwise saving is refused: This database does not record changes for replication. Set wal_level = logical … and restart it.
• A connection user with REPLICATION (ALTER ROLE … WITH REPLICATION) that owns the tables — otherwise The connection’s user can’t read the change log.
• A free replication slot (max_replication_slots). An update’s old values arrive only after ALTER TABLE … REPLICA IDENTITY FULL.

MQTT message

Broker URL, Topics (+ and # allowed) and Delivery: At most once (QoS 0) or At least once (QoS 1). payload is the message parsed from JSON, or the text itself when it is not JSON. Payloads over 256 KB go to the project’s storage.

Health, history, pause

Click a trigger to open it. Its health line says Listening · last event 3 min ago, or what is wrong in words: Can’t sign in, Can’t connect, Folder not found, The replication slot is gone — delete this trigger and add it again. Below, Last 20 events (kept 7 days), each marked Ran, Not run (with why: not published, a missing required input…) or Waiting. Edit changes it in place (a database-change trigger keeps its connection, tables and changes — delete it and add a new one to change those); the row’s switch is Pause trigger / Resume trigger. On the Runs page, a run started by an event carries an E-mail, Database change or MQTT chip.

Limits and honest gaps

• Events and their attachments are kept 7 days, then deleted.
• MQTT messages sent while the trigger is paused are lost, unless you turn on Keep messages while paused or reconnecting (persistent session), which makes the broker keep QoS 1 messages for it.
• A paused database-change trigger keeps its slot, so the database keeps every change for it — after some days the row says so. Delete the triggers you no longer need.
• Servers on private addresses are refused (Address not allowed) unless your administrator allows them.