Triggers are the custom-code hooks that run when an inbox processes a message. Whereas rules handle the common cases declaratively, triggers let you implement business logic that goes beyond filing the message.
What a Trigger Receives
Every trigger is invoked with structured access to the message:
$message->from,$message->to,$message->subject,$message->date$message->bodyText,$message->bodyHtml— body in both forms$message->attachments— array of file blobs with name, MIME type and size$message->headers— full header dictionary$matchedRule— the rule that fired the trigger (null if “unmatched” trigger)
Trigger Return Value
The trigger should return one of:
- true — processing succeeded, mark message as handled.
- false — let the next rule continue processing.
- ['error' => 'reason'] — mark as failed; the message stays in the inbox for retry.
Example Triggers
- Expense receipt extraction: When a PDF arrives on receipts@, run an OCR step and create a draft expense entry with the parsed amount.
- Sender reputation: Check incoming sender domain against a deny-list; bounce or quarantine flagged senders.
- Out-of-office detection: If the body matches typical OOO patterns, mark the sender as “unavailable until X” on their user record.
- Forward to teams: If subject contains a project code, look up the project owner and forward the message to their address.
Note: Triggers run synchronously during inbox polling. Keep them quick — anything over a few seconds should queue a background task rather than blocking the next message.