> ## 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.
# Operate and troubleshoot mail imports
> Verify imports, inspect history and audit, rotate Microsoft 365 secrets, and recover failed or partially archived messages without duplicating documents.
## 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.
| Status | Meaning | What to do |
| ---------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| **Pending** | Queued for archiving or waiting for another attempt | Allow processing time; inspect errors if progress stops |
| **PendingEvent** | All documents are saved; the mail event still needs publication | Investigate prolonged delivery delays; do not upload the message again |
| **Imported** | Archive and mail-event publication completed | Check the [workflow instance](/mailbox-importer/workflows#confirm-routing-and-completion-separately) separately |
| **Failed** | Archiving exhausted its automatic attempts | Correct the cause, then use **Retry** with Manage or Admin |
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](/mailbox-importer/archive-rules#example-keep-ordinary-mail-split-supplier-invoices), 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.
| Test | Expected result |
| -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Send the matching message to the watched folder, after the configured start time | The message is picked up and eventually reaches Imported |
| Inspect the split archive | One HTML document in type 30 and two PDFs in type 40; the logo is in the HTML |
| Inspect keywords | Mail subject is stored in **Mail subject (#101)**; each attachment has its subject in **Mail subject (#202)** and its own filename in **Attachment filename (#203)**, plus any additional mappings you configured |
| Inspect sender, recipients, and dates | Values match the source; recipients are separate values and dates are UTC |
| Send a message that misses the rule | One EML in fallback type 10, preserving the original message and attachments |
| Inspect the published workflow | One instance of the intended definition, anchored to the mail, with the expected attachment IDs |
| Inspect document and workflow history | The importer service account is recorded for automated import activity |
| View settings with View only, then Manage | View is read-only; Manage can save settings and retry but cannot enter secrets |
| Allow further polls or disable and re-enable the mailbox | Already imported messages do not create additional archive copies or repeat the same workflow start |
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](/workflows/monitoring).
## 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](/mailbox-importer/setup#create-the-application-secret). 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
| Change | Effect |
| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| Edit rule order, conditions, destinations, or mappings | New imports use the saved policy; existing documents are not reclassified |
| Retry after any part was saved | The import keeps its original plan and skips saved parts |
| Change the tenant, mailbox, watched folder, or initial start time | Create a new configuration; these fields are locked on an existing one |
| Create another configuration for overlapping mail in the same tenant and mailbox | Already recognized messages are not deliberately reimported just because a new configuration or policy exists |
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](https://learn.microsoft.com/en-us/graph/outlook-immutable-id) 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:
| Record | What it tells you |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| Configuration audit | Who created or changed settings, enabled or disabled intake, changed a credential, or requested retry; credentials themselves are excluded |
| Document/import audit | Which parts were archived and the importer service-account actor; final archive completion is recorded separately |
| Workflow instance history | The trigger, definition version, mail context, and subsequent actions and outcomes |
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
| Symptom or code | Check and recovery |
| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Mailbox importer** is missing, or access is forbidden | Confirm feature availability and View/Manage/Admin grants. Document access alone does not grant settings access. |
| **Enable scheduled import** is unavailable | Save the configuration first, then have someone with Admin save the application secret. A changed application ID requires a new secret. |
| Source fields are read-only | Tenant, mailbox, folder, and start time are locked after creation. Create a new configuration for a different source. |
| Settings or secret save reports a conflict | Another settings or secret change occurred. Reload the page, confirm the current application ID, and reapply the intended edits. A rejected secret must be entered again. |
| `GraphHttp401` or `GraphHttp403` | Check tenant/client IDs, secret value and expiry, application mail-read permission, and access to this specific mailbox. |
| `GraphHttp404` | Check mailbox existence, the folder ID or well-known name, and access. A custom display name is not a Graph folder ID. |
| `GraphHttp429` or `GraphHttp503` | Microsoft is throttling or temporarily unavailable. Allow its retry delay; repeatedly saving or retrying does not shorten it. |
| `ClientSecretNotConfigured` | Save a secret for the current application with Admin. |
| `SecretDecryptionFailed` | Ask support to restore credential access; if necessary, enter a new secret. Do not assume the Configured indicator proves the value is usable. |
| `ServiceAccountNotConfigured`, `ServiceAccountNotFound`, or `ServiceAccountDisabled` | Ask the team responsible for the tenant to correct the importer account. Adding permissions to your own login will not fix background import. |
| `DocumentPermissionDenied` | Grant the importer account the required document and keyword rights on all selected target types. |
| `MessageTooLarge` | Check the complete MIME size against the configured byte limit. Increase the limit only within the allowed range and your archive policy, then retry. |
| `TooManyAttachments` or `HtmlArchiveTooLarge` | Review split-mode content limits. Whole EML may be suitable if no parts have been saved; an existing partial archive cannot be retargeted. |
| `InvalidAttachmentFileName` | Review the offending content with support. Do not silently discard attachments to make the import pass. |
| `MailContentChanged` | Source content differs from the recorded archive plan. Request a recovery review; ordinary retry will not overwrite saved parts. |
| `InvalidGraphMessageIdentity` or `InvalidGraphReceivedTime` | Graph returned unusable identity or date metadata. Capture the error and time for support; do not change the start time to skip an unexplained gap. |
| `ImportFailed` | Check destination required keywords, field formats, document comments, and supported content, then ask support to investigate with the failure time. |
| Mail remains **PendingEvent** | Archiving finished but event publication is delayed. Ask support to investigate delivery; uploading again is unnecessary. |
| Mail is **Imported** but no workflow starts | Confirm a published **Mail imported** trigger, mail-document scope, passing filter, and workflow availability. Check existing instances and delivery with support. |
| HTML is missing a remote logo or differs visually from Outlook | External resources are blocked and active HTML is sanitized. Use EML when you need the original representation. |
## Where to read next
Continue to the next integration area: connecting assistants with controlled access to Nobly Insight.
Revisit access grants, source selection, credentials, and the initial activation sequence.
Inspect and recover postprocessing after the mail archive has completed.