> ## Documentation Index
> Fetch the complete documentation index at: https://docs.insight.nobly.dk/llms.txt
> Use this file to discover all available pages before exploring further.
# Route imported mail into workflows
> Configure the Mail imported trigger, scope workflows to the archived mail document, and use mail metadata and attachment document IDs for postprocessing.
## Before you begin
You need `workflow-engine.manage` or `workflow-engine.admin`, a provisioned Workflow Engine, and a mailbox with its [archive policy configured](/mailbox-importer/archive-rules). 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](/workflows/actions) and the services enabled for your tenant.
## Configure the trigger in the designer
Open **Admin settings → Workflow → Workflow Designer**. Name the definition, for example **Supplier mail postprocessing**, and select **Document** as its anchor type.
Select the document types used for the EML or HTML body. For the [supplier rule example](/mailbox-importer/archive-rules#example-keep-ordinary-mail-split-supplier-invoices), select **Supplier mail**, example ID `30`. Include **Mail archive**, example ID `10`, only if this workflow should also handle fallback EML imports.
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](/workflows/first-workflow) explains how to build a task path.
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.
Choose **Validate**, correct errors, and **Save draft**. Once there are no unsaved changes, choose **Publish**. A saved draft does not react to mail events.
[Enable the mailbox](/mailbox-importer/setup#save-the-secret-then-enable-intake), 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.
```json theme={null}
{
"type": "Mail.Imported",
"filter": {
"and": [
{ "==": [{ "var": "mail.sender" }, "sender@example.com"] },
{ "==": [{ "var": "mailbox" }, "intake@example.com"] }
]
}
}
```
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](/workflows/expressions#trigger-filters) 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](/workflows/expressions).
| Instance reference | Value |
| ------------------------------------------------------------- | ----------------------------------------------------------- |
| `instance.mail.sender` / `instance.mail.senderName` | Sender address and display name |
| `instance.mail.to` / `instance.mail.cc` / `instance.mail.bcc` | Arrays of recipient addresses present in the metadata |
| `instance.mail.subject` | Mail subject |
| `instance.mail.sentUtc` / `instance.mail.receivedUtc` | UTC timestamps; sent time can be null |
| `instance.mail.internetMessageId` | Internet message identifier |
| `instance.mail.conversationId` | Graph conversation identifier |
| `instance.mail.messageId` | Graph message identifier used by the importer |
| `instance.mailbox` | Source mailbox address |
| `instance.mailboxConfigurationId` | Mailbox configuration identifier |
| `instance.mailImportId` | Identifier for this import, useful when investigating a run |
| `instance.mailArchiveRuleName` | Selected archive-rule name, or null for the default policy |
| `instance.mailDocuments` | The mail and all separately archived attachment documents |
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:
| Field | Meaning |
| ---------------- | ----------------------------------------------------------------------------- |
| `documentId` | Archived document to retrieve or pass to a supported processing action |
| `documentTypeId` | Destination type selected by the archive policy |
| `kind` | `eml`, `body`, or `attachment` |
| `fileName` | Archived filename |
| `partIndex` | Stable part identifier; the mail is `0`, and attachment indices can have gaps |
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
| Check | What success means |
| --------------------------------------------------------------------- | ----------------------------------------------------- |
| Mailbox history reaches **Imported** | Archiving and publication of the mail event succeeded |
| One instance of the intended definition appears for the mail document | Trigger, scope, and filter matched |
| The instance contains the expected mail variables and document list | The workflow received the complete archive context |
| Actions and terminal outcome succeed in instance history | Postprocessing completed |
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](/workflows/monitoring#handling-failures).
## Where to read next
Verify the complete path, rotate secrets, investigate audit records, and recover failed or partial imports.
Choose supported actions and verify their document targets, parameters, and permissions.