Import from Email

An email connector watches a mailbox folder and imports every new matching email into your project automatically. Each email becomes one transaction: the email body is rendered to a PDF and imported as the first document, and every attachment that matches your filter becomes a further document. Sender, recipients, subject and received time are stored as transaction metadata, so reviewers can see them (and you can show them as columns in the transaction list).

Typical uses: an accounts-payable mailbox that receives invoices, a shared inbox where scans are forwarded, or a dedicated address like documents@yourcompany.com that other systems send to.

Two connection types

Type	Use for	You need
Email (IMAP)	Generic mail servers: on-premises Exchange, Dovecot and other IMAP hosts, Gmail with an app password	Host, username and password (or app password)
Email (Microsoft 365)	Mailboxes hosted in Microsoft 365 / Exchange Online	On our hosted service, one click of approval from a Microsoft 365 admin (below). On self-hosted deployments, a one-time app registration instead. Plain passwords do not work for Microsoft 365: Microsoft has disabled basic authentication.

Email connectors are available on every deployment type. The deployment must have credential storage configured (self-hosted: set CREDENTIAL_ENCRYPTION_KEY); mailbox secrets are always stored encrypted and are never shown again after you save them.

How it works

1. The connector polls the mailbox folder on a schedule (default: every 60 seconds).
2. An email is picked up when it matches your optional sender and subject filters.
3. The body is converted to a PDF document. Attachments matching the attachment mask (by default: PDF, TIFF, PNG, JPEG, HEIC) are imported alongside it. Inline images such as signature logos are skipped unless you opt in.
4. One transaction is created per email, the workflow starts, and only then is the email released: moved to a mailbox folder (default processed), marked as read, or deleted, per your settings.
5. If an import keeps failing, the email is moved to the failure folder (default error) after several attempts, so problems are always visible in the mailbox itself.

The same email is never imported twice, even across restarts or if it is seen by several servers at once.

Use a dedicated folder

Point the connector at a dedicated mailbox or folder (for example, use a mail rule to move invoices into an Invoices folder). With the default move on success behavior the folder then acts as a queue: new emails arrive, processed emails leave.

Setting up a connector

1. Open your project and go to the Workflow tab, then select the Import activity.
2. Click Add connector and set Source to one of the email types.
3. Under Mailbox credential, click New, fill in the connection details, and Save credential. Then press Test: you should see a confirmation that the mailbox folder was opened.
4. Adjust the mailbox folder, filters, and success/failure behavior as needed.
5. Click Test (dry-run) to preview exactly which emails would be imported right now, and which documents each would produce.
6. Click Import to Playground to try full processing against your draft configuration. This runs exactly the same way production will, just triggered by hand: each email is imported once and then filed away at the source (with the default settings it moves to the processed folder), so re-running the test never creates duplicates. Because it consumes the emails, point a test connector at a test folder or mailbox.
7. Save. Automatic import to production begins once the project is published.

Microsoft 365 setup

There are two ways to connect a Microsoft 365 mailbox. On our hosted service the first one is the default and takes seconds; the second is for self-hosted deployments or teams that prefer to run their own Azure app.

One-click connection (hosted service)

When you click New under Mailbox credential, DocAI Fabric asks one question: are you connecting your own mailbox, or a shared or team mailbox?

A shared or team mailbox such as invoices@yourcompany.com:

1. Add a connector, set Source to Email (Microsoft 365), and under Mailbox credential click New.
2. Choose A shared or team mailbox, type the mailbox address, and click Get consent link.
3. Open the link if you are a Microsoft 365 admin, or send it to one. Approving it once grants DocAI Fabric read access to the mailbox for your organization. The mailbox connects automatically as soon as the admin approves; you do not enter any secret.
4. Recommended: ask your admin to restrict DocAI Fabric to just this mailbox with an application access policy. Until they do, the app can read any mailbox in the tenant. DocAI Fabric shows a reminder on the credential until scoping is in place.

My own mailbox (a personal sign-in, best for a single person):

1. Add a connector, set Source to Email (Microsoft 365), and under Mailbox credential click New.
2. Choose My own mailbox, then click Sign in with Microsoft. A Microsoft sign-in opens in a new tab.
3. Sign in and approve access to your mail. No administrator is needed unless your organization requires admin approval for sign-ins. Your mailbox connects automatically when you finish; you do not enter any secret. This works with work or school accounts and with personal Microsoft accounts (Outlook.com, Hotmail).
4. To poll a shared mailbox this way instead of your own, open Advanced: connect a shared mailbox instead before signing in and enter its address. You must have Exchange "Full Access" delegation on that mailbox.

A personal sign-in stores a token tied to your account. If your password, multi-factor settings, or a security policy change, or you do not use the connector for a long time, the token can expire and DocAI Fabric marks the mailbox Needs re-authentication. Select the credential and click Reconnect to sign in again; the connector keeps its settings. For an always-on shared mailbox, prefer the shared or team option above, which does not depend on one person's sign-in.

Bring your own Azure app (self-hosted, or advanced)

Your Microsoft 365 administrator creates an app registration that DocAI Fabric uses to read the ingest mailbox. This takes about ten minutes. In the credential form, open Advanced: use your own Azure app to enter these values.

1. In the Entra admin center, go to App registrations → New registration. Single tenant; no redirect URI is needed. Note the Application (client) ID and Directory (tenant) ID.

2. Under API permissions, add Microsoft Graph → Application permissions → Mail.ReadWrite, then Grant admin consent. (ReadWrite is required because the connector moves or marks processed emails.)

3. Recommended: restrict the app to just the ingest mailbox with an application access policy in Exchange Online PowerShell:

   New-ApplicationAccessPolicy -AppId <client-id> `
     -PolicyScopeGroupId <mail-enabled security group containing the ingest mailbox> `
     -AccessRight RestrictAccess
   Test-ApplicationAccessPolicy -AppId <client-id> -Identity invoices@yourcompany.com

4. Under Certificates & secrets, create a client secret. Copy the value immediately (it is shown once) and note the expiry date: the connector will stop working when the secret expires, so plan its rotation.

5. In DocAI Fabric, create the credential with the tenant ID, client ID, client secret, and the mailbox address, then press Test.

Gmail and other providers

• Gmail: use the Gmail tile (IMAP with imap.gmail.com, port 993, prefilled). Gmail rejects your normal account password over IMAP, so you need an app password: turn on 2-step verification for the account, then create one at myaccount.google.com/apppasswords and paste it as the password. The credential form links straight to that page.
• On-premises Exchange / Dovecot / other: use the IMAP type with the server's hostname and a normal mailbox login.

Gmail and mailbox folders

Gmail folders are labels, and Gmail does not allow a label underneath the inbox. So on Gmail the success and failure folders are created as top-level labels: processed, not INBOX/processed. The connector creates them the first time it files an email away, so they will not appear in Gmail until the first import succeeds (or fails).

Settings reference

Setting	Meaning	Default
Mailbox folder	The folder that is watched	INBOX
Sender filter	Regex the sender address must match	none
Subject filter	Regex the subject must match	none
Attachment mask	Regex attachment filenames must match	PDF, TIFF, PNG, JPEG, HEIC
Import email body	Render the body to PDF as the first document	on
On success	Move to folder / mark as read / delete	move to processed
On failure	Move to folder / leave in place	move to error
Poll interval	How often the mailbox is checked	60 s

Notes:

• With mark as read, only unread emails are considered; with move or delete, every email remaining in the folder is considered.
• Emails that match the filters but produce nothing to import (no body import, no matching attachments) are skipped and stay in the folder.
• Emails larger than 50 MB are skipped and logged.