Skip to main content

​
Before you begin

You need workflow-engine.manage or workflow-engine.admin, a provisioned Workflow Engine, and a mailbox with its archive policy configured. Keep intake disabled until your first workflow is published if you want it to handle the first imported messages. The importer and workflow have separate responsibilities:
  1. The importer selects an archive rule and creates the mail and attachment documents.
  2. After every part is saved, it emits Mail imported, whose event identifier is Mail.Imported.
  3. Each matching published document workflow can start with the archived mail as its anchor and the complete list of document IDs in its variables.
Importing does not automatically convert files, extract business data, or send replies. Configure those steps using the available workflow actions and the services enabled for your tenant.

​
Configure the trigger in the designer

1

Create a document workflow

Open Admin settings → Workflow → Workflow Designer. Name the definition, for example Supplier mail postprocessing, and select Document as its anchor type.
2

Scope it to the mail document

Select the document types used for the EML or HTML body. For the supplier rule example, select Supplier mail, example ID 30. Include Mail archive, example ID 10, only if this workflow should also handle fallback EML imports.
3

Design the processing path

Add an initial node and the required actions or review tasks. Add terminal outcomes and an error path. For a first routing check, use a review task so you can inspect the mail context before adding automated side effects. The first-workflow guide explains how to build a task path.
4

Select Mail imported

Select the definition’s Triggers tab, add a trigger, and choose Mail imported. Start without a filter for the first test, or add a deliberate routing filter as described below.
5

Validate and publish

Choose Validate, correct errors, and Save draft. Once there are no unsaved changes, choose Publish. A saved draft does not react to mail events.
6

Enable intake and inspect the instance

Enable the mailbox, send a matching test message, and open Workflow Instances. Confirm the published definition version, anchor document, initial variables, and history before adding further automation.
In split mode, the workflow anchor is the HTML mail document. Scoping only to the attachment type, such as type 40, does not match the Mail.Imported event for that message. The attachments are available through the instance’s document list.
Normal document-created notifications can also be emitted for individual archived parts. Use Mail imported when processing depends on mail metadata or on all attachments being present. Avoid configuring both triggers for the same business action unless you intend both paths to run. Mail.Imported belongs to document workflows; it is not a Script Engine event-hook binding.

​
Filter by mailbox or sender

All normal workflow gates still apply: published definition, matching event type, matching mail document type, and a passing optional filter. Importer archive conditions and workflow filters are separate decisions. In the designer’s JSON view, the following is one entry in the definition’s triggers array, not a complete definition. It accepts only sender@example.com arriving through intake@example.com. Replace the sender with the actual address you want, for example billing@supplier.example for the supplier rule.
This filter uses equality. It is not the case-insensitive substring match used by archive rules. Test the exact metadata your mailbox supplies. After editing JSON, choose Apply changes → Validate → Save draft → Publish. Until you apply the JSON edits, the validation and save controls are disabled. Filters run before an instance exists. They read event fields such as mail.sender, mail.subject, mailbox, mailboxConfigurationId, archiveRuleName, and documents, alongside the normal document metadata context. Do not use instance.mail.sender in a trigger filter. The expression reference explains the event context and JSONLogic representation.

​
Use mail metadata after the workflow starts

Mail imports seed these variables when the instance is created. The table shows reference paths; in a formula, prefix a path with $, and in a body template, use the usual double-brace reference syntax described in References and expressions. Mail bodies, attachment bytes, and application secrets are not copied into these variables. Access the documents through the normal document actions or API permissions. Mail metadata in the instance remains subject to workflow instance access controls; consider it when granting workflow inspection access.

​
Process the attachment documents

Each item in instance.mailDocuments has: For the HTML mail, embedded logo, and two-PDF example, the list contains one body item and two attachment items. There is no separate document ID for the embedded logo. Whole EML mode supplies one eml item; it does not expose internal attachments as separate Insight documents. When designing attachment processing, select items by kind and use their documentId. Do not assume the first attachment has a particular part index or that document IDs are consecutive. An action that operates on the workflow’s anchor still operates on the mail document; it does not automatically run for each attachment. Check the selected action’s parameters and access requirements before passing another document ID. For example, keep human review attached to the HTML mail, and pass PDF attachment IDs to the extraction or processing operation your workflow uses. The workflow’s execution identity needs the appropriate rights on the attachment type as well as the mail type.

​
Confirm routing and completion separately

An Imported row does not prove the workflow matched or completed. If no workflow was published when an event was consumed, publishing later does not replay historical imports. Use a new test message to verify the new definition, or plan deliberate historical processing separately. Event redelivery does not create another instance of the same definition for the same import. It can still start different matching definitions. Workflow action retries and external side effects follow the normal workflow recovery rules.

Operate and troubleshoot mail imports

Verify the complete path, rotate secrets, investigate audit records, and recover failed or partial imports.

Action reference

Choose supported actions and verify their document targets, parameters, and permissions.