Operate and troubleshoot mail imports

​

Access and monitoring

With mailbox-importer.view, open Admin settings → Mailbox importer → Mailboxes. Each card shows whether intake is Enabled, whether a secret is configured, the last poll time, and the latest polling error when one exists. Open View settings and history, or Settings and history if you have Manage. The mailbox cards and the open Import history refresh every 30 seconds while the page is active. These updates preserve unsaved settings in the editor. The history shows received time, status, attempt count, and an error code. It displays 100 messages per page. Use Previous imports, Next imports, and Show failed imports only to find older failures. The history screen intentionally omits mail subjects, recipient lists, and document IDs. Viewing importer settings does not reveal document content. Use ordinary document access and workflow inspection permissions to examine the resulting archive.

​

Verify your first import

Use fictional content in a mailbox you are authorized to test. For the supplier rule example, send from billing@supplier.example to your test intake mailbox with subject Invoice 1007, a signature PNG embedded in the body, and two real PDF attachments. Substitute addresses you actually control; the example domains cannot receive your test mail. Finally, verify the source message is still present and its read state is unchanged. Record the mailbox, test time, chosen policy, resulting documents, and workflow instance for your handover.

​

Pause and resume intake

With Manage or Admin, clear Enable scheduled import and Save settings. Re-enable and save to resume. Pausing does not delete previously archived documents or undo work already in progress. Already saved documents can still complete their pending notifications and start workflows while intake is disabled. Pausing the mailbox is therefore not a way to cancel a workflow or erase a queued event. Manage existing instances through Workflow administration.

​

Rotate the application secret

You need mailbox-importer.admin and access to create a secret on the existing Microsoft Entra application.

1. Create a replacement client secret on the same app registration, following the credential setup procedure. Keep the old credential available until the replacement is verified.
2. Open the mailbox’s Application secret section, enter the new Value in New client secret, and choose Save secret.
3. Confirm the secret is reported as configured. Check a subsequent poll and representative import; the configured indicator means a value is stored, not that Microsoft has accepted it.
4. After verification, retire the old secret in Microsoft Entra and record the replacement’s expiry. If several mailbox configurations use that application secret, update each one before retiring it.

The stored secret cannot be displayed or recovered from the form. Credential changes are audited without recording the secret value. If someone changes the configuration or secret while your editor is open, saving your secret reports a conflict. Reload the page, confirm the current application ID, and enter the replacement secret again. This prevents an old editor from overwriting another administrator’s credential or saving a secret against a replacement application.

​

Replace the application registration

If you change Application (client) ID, save the configuration disabled first. This clears the previous application’s secret. Then enter the new application’s secret, verify its mailbox access, and enable and save again. You cannot use the old application’s secret with the replacement client ID.

​

Retry a failed import

Archiving retries automatically with increasing delays and normally reaches Failed after five attempts. Mail-event publication continues retrying independently after archiving has completed.

1. Read the mailbox-card error and the failed history row. Determine whether the cause is Microsoft 365 access, document configuration, permissions, or content.
2. Correct that cause. Ensure the mailbox is enabled when you want archiving to resume.
3. With Manage or Admin, select Retry on the failed row. It returns to the queue; Retry is not a second upload operation.
4. Watch the row progress and verify the documents and workflow. If Microsoft Graph has imposed a retry delay, a manual retry does not bypass it.

​

Recover a partial split archive

One attachment can fail after the HTML mail or another attachment has already been saved. Saved parts remain valid documents; the import is not rolled back as a whole. They can be indexed before the complete message reaches Imported. Retries reuse the saved parts and create only the missing ones. Mail.Imported waits for the full archive. Repair access or the underlying document/storage problem and retry the existing import rather than manually uploading the same files. If no part has been saved, a manual retry lets a corrected archive policy apply. Once any part has been saved, the selected targets, mappings, and source content are fixed for that import. Changing the configuration cannot redirect its remaining attachments to another document type. Changed source content is rejected with MailContentChanged.

​

Change a source or policy

The importer recognizes a message by its Microsoft 365 source identity. Ordinary repeated polls and folder moves within the same mailbox do not create another archive of the same recognized message. Copying or reimporting mail can create a new identity, so do not use mailbox copies as a retry mechanism. Microsoft’s immutable message ID guidance describes identity changes such as movement to an archive mailbox and export/reimport. For a new folder configuration, disable the old one when it should no longer collect mail. For historical reprocessing or a partial import that requires a different archive design, agree a recovery plan with support. Do not remove import tracking records to force a retry.

​

Audit and support handover

The integration records three different kinds of evidence: Import history is an operational status list, not a configuration-change viewer. For a configuration audit investigation, supply the mailbox configuration identifier; records are associated with Mailbox: followed by that identifier. Use your organization’s configuration-audit access or support process. The mailbox editor does not expose a dedicated configuration-audit button. For support, collect the configuration name and identifier, mailbox/folder, received and failure times, status, error code, what changed, and any accessible document or workflow instance IDs. The stored rule name and instance.mailImportId help correlate completed archives with workflow history. Do not include secret values, tokens, or unnecessary message content.

​

Troubleshooting

​

Where to read next