Inbound Email Trigger
The Email Inbound (Mailhook) trigger gives a workflow its own email address. Every message sent or forwarded to that address starts the workflow once, with the message as its input. Use it when a system can only send email: a website form that mails its submissions, order confirmations, invoices from a supplier, alerts from a monitoring tool.
It is the FluidGrids version of Zapier's Email by Zapier and Email Parser, or Make's custom mailhook. If you instead want to watch a mailbox you already own, use the Email Trigger (IMAP).
Like every event trigger it runs the workflow's Active version only.
The address
- Add Email Inbound (Mailhook) to a workflow and save. The node now shows its address, for example
[email protected]. - Copy it into the system that sends the mail, or set up a forwarding rule in your mailbox.
- Activate the workflow. Mail sent before activation is logged and dropped.
The address:
- is created the first time you save the workflow and stays the same across edits, new versions and activation;
- starts with the Address label (or the workflow name) followed by a random 16-character code that cannot be guessed;
- can be rotated: the node gets a new address and the old one stops working at once. A rotated or deleted address is never handed out again;
- accepts plus addressing:
leads-…[email protected]reaches the same trigger.
FluidGrids never replies to the sender, never sends bounces and never sends auto-replies.
Settings
| Setting | Default | What it does |
|---|---|---|
| Address label | the workflow name | The readable start of the address. A new label applies when you rotate the address. |
| Allowed senders | anyone | Only start for these senders: addresses ([email protected]) or domains (@example.com), separated by commas. Matched against the envelope sender and the From address. |
| Require an authenticated sender | off | Drop mail unless SPF or DKIM passed and DMARC did not fail. |
| Subject filter | none | Only start when the subject contains this text (case-insensitive), or matches /a regular expression/. |
| Drop spam | on | Drop mail the spam scan flags. Mail with a virus is always dropped. |
| Include the HTML body | on | Add html to the output. |
| Include all headers | off | Add every header as headers. Credentials in headers are masked. |
| Attachments | store | Store keeps each attachment for 7 days and gives the run a download link valid for one hour; Names and sizes only; or Leave them out. |
| Include a link to the raw message | off | Add rawMessageUrl, a one-hour link to the original message. |
| Max runs per hour | 120 | Messages over this limit within an hour are dropped and logged. |
| Parse rules | none | Fields to pull out of each message (see below). |
Messages larger than 25 MB are dropped and logged.
What a run receives
| Field | Meaning |
|---|---|
messageId | The Message-ID header |
inboundId | This delivery's id |
address | The trigger address that received the message |
from | The sender: { address, name } |
envelopeFrom | The envelope sender (MAIL FROM) |
to, cc, replyTo | Lists of { address, name } |
subject, date | The subject and the Date header |
receivedAt, triggerTime | When the message was received and when the run started |
text | The plain-text body, or text made from the HTML when the message has no text part |
html | The HTML body, when included |
strippedText | The text without the quoted reply below it and without the signature |
headers | Every header as { name, value }, when included |
attachments | { filename, contentType, size, contentId, inline, fileId, downloadUrl, downloadUrlExpiresAt } per attachment |
attachmentCount | How many attachments the message had |
verdicts | { spf, dkim, dmarc, spam, virus }, each PASS, FAIL, GRAY or PROCESSING_FAILED |
parsed | The fields the parse rules found |
parseErrors, parseOk | Rules that found nothing or could not run, and whether every required field was found |
rawMessageUrl | Link to the raw message, when included |
messageId, subject, from, to, cc and date have the same names as in the IMAP trigger, so a workflow can switch between the two.
Parse rules
Parse rules turn a message into named fields under parsed, the common use of an email parser. Each rule reads one source and extracts one field with one method:
| Method | Extracts | Example rule |
|---|---|---|
label | The text after Label: on the same line | { "field": "name", "method": "label", "label": "Name" } |
between | The text between two markers | { "field": "orderId", "method": "between", "start": "Order [", "end": "]" } |
regex | The first capture group, or a named group | { "field": "ref", "method": "regex", "source": "subject", "pattern": "#(\\d+)" } |
line | The Nth non-empty line (-1 is the last) | { "field": "firstLine", "method": "line", "line": 1 } |
table | The cell next to a header cell in an HTML table | { "field": "total", "method": "table", "label": "Total" } |
The source is text (default), subject, html (default for table), from or header:<name>, such as header:x-lead-source. Add "required": true to report the field in parseErrors when it is missing; values are trimmed unless you add "trim": false.
Parsing never stops the run. When a required field is missing, parseOk is false, so an IF node can route those messages to a person.
Regular expressions are checked before they run: backreferences, lookbehind and repeated groups that contain a quantifier or alternatives (such as (a+)+) are refused, because a message from anyone could otherwise make them run for a very long time.
Testing
Click Listen for test email on the node. The next message sent to the address within the listening window starts one TEST run of the version open in the editor instead of a production run, and the canvas shows it. Save the workflow first: the test uses the saved version.
Delivery log
The inboundMailDeliveries(workflowKey, triggerNodeId) GraphQL query lists the newest messages for the node and what happened to each: STARTED, TEST_STARTED, SKIPPED_INACTIVE, SKIPPED_FILTERED, SKIPPED_SPAM, SKIPPED_VIRUS, SKIPPED_RATE_LIMITED, SKIPPED_TOO_LARGE, SKIPPED_QUOTA or FAILED, with the reason and the run id. The log keeps the sender, the size, the verdicts and the outcome, never the subject or the body.
Template: parse lead emails and post them to Slack
inbound-email-leads-to-slack.json is a ready-made workflow:
- Lead email: an Inbound Email trigger labelled
leads, filtered to subjects containing "lead", with rules forName,Email,PhoneandMessage. - Post to Slack: posts "New lead: Jane Doe <[email protected]> +1 555 0100" and the message to a channel.
To use it:
- Import the template: download the file and run
fluidgrids import inbound-email-leads-to-slack.json, or pass its contents to theimportWorkflowGraphQL mutation. It is created as a Draft. - Open it in the builder. On Post to Slack, pick your Slack connection and set the channel.
- Save, copy the address from the Lead email node, and point your form's notification email (or a forwarding rule) at it.
- Activate the workflow, then send a test lead.
When it does not fire
- Is the workflow Active? Mail to a workflow without an active version is logged as
SKIPPED_INACTIVE. - Check the delivery log. It says whether the message was filtered, flagged as spam, over the hourly limit or too large.
- Was the address rotated? Mail to an old address is dropped without a log entry.
- Out of runs? Inbound email runs count against the workspace's monthly run quota.
Next steps
- Workflows: triggers, versions and activation
- Expression Language: reading
$json.parsed.namein later nodes - Runs: inspecting what a run received