From 8bbdb86f79ad0648c97ca5b8b3664227432a5a5f Mon Sep 17 00:00:00 2001
From: Ivo Oskamp <ivooskamp@oskamp.info>
Date: Sun, 8 Feb 2026 16:57:10 +0100
Subject: [PATCH] Multiple accuracy fixes for Inbox Management documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Critical corrections based on actual UI behavior:

Email Detail Modal Layout:
- Fixed layout description: TWO-COLUMN (not top/middle/bottom)
- Left side: Metadata + action buttons + parsed objects
- Right side: Email body in iframe
- Updated screenshot caption to reflect left/right layout

Action Buttons (Left Side):
- REMOVED "Re-parse" from modal (doesn't exist in modal!)
- Only available buttons: Approve, Delete, Download .eml
- Re-parse is ONLY on inbox page, not in modal

Approving Emails:
- FIXED: Job name is READ-ONLY during approval (cannot be edited!)
- Only customer selection is editable
- Added callout: "Job Name Cannot Be Changed"
- Removed all references to "edit job name" or "adjust job name"

Re-parsing Emails:
- REMOVED "Re-parse Single Email" section (doesn't exist!)
- Only "Re-parse all" available on inbox page
- Added callout: "No Individual Re-parse"
- Workaround: Delete unwanted emails, re-parse all, re-import

Deleting Emails:
- Fixed location: "Deleted Mails" page (Admin only)
- NOT in "Settings → Maintenance"
- It's a separate navigation page

Inbox Filters and Search:
- REMOVED entire section (not in planning, won't be implemented)
- No false expectations about future filtering features

Troubleshooting Unparsed Emails:
- FIXED: Parsers can ONLY be created by BackupChecks developer
- Users CANNOT create custom parsers
- Added warning callout about parser creation
- Instructions: Contact support with .eml samples

Best Practices:
- Removed "Edit job names during approval" (impossible!)
- Added "Verify parsed job names" - contact support if wrong
- Updated to reflect actual capabilities

All corrections ensure documentation matches actual UI behavior.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 .../mail-import/inbox-management.html         | 97 ++++++++++---------
 docs/changelog-claude.md                      |  2 +-
 2 files changed, 51 insertions(+), 48 deletions(-)

diff --git a/containers/backupchecks/src/templates/documentation/mail-import/inbox-management.html b/containers/backupchecks/src/templates/documentation/mail-import/inbox-management.html
index 4734827..de3138f 100644
--- a/containers/backupchecks/src/templates/documentation/mail-import/inbox-management.html
+++ b/containers/backupchecks/src/templates/documentation/mail-import/inbox-management.html
@@ -110,17 +110,17 @@
 
 <h3>Email Detail Modal</h3>
 
-<p>The email detail modal contains three main sections:</p>
+<p>The email detail modal uses a two-column layout:</p>
 
 <figure>
   <img src="{{ url_for('static', filename='images/documentation/approve-job.png') }}"
        alt="Email Detail Modal" />
-  <figcaption>Figure 1: Email detail modal showing metadata, email body, and approval interface with customer selection</figcaption>
+  <figcaption>Figure 1: Email detail modal with metadata on the left and email body on the right</figcaption>
 </figure>
 
-<h4>1. Metadata Section (Top)</h4>
+<h4>1. Metadata Section (Left Side)</h4>
 
-<p>Displays email header information:</p>
+<p>Displays email header information on the left side of the modal:</p>
 
 <ul>
   <li><strong>From:</strong> Sender address</li>
@@ -130,18 +130,17 @@
   <li><strong>Overall status:</strong> Success/Warning/Failed indicator</li>
 </ul>
 
-<p>The metadata section also includes action buttons:</p>
+<p>Below the metadata, action buttons are available:</p>
 
 <ul>
   <li><strong>Approve:</strong> Opens the approval dialog to link this email to a customer and create a job</li>
-  <li><strong>Re-parse:</strong> Re-runs parsers on this email to update parsed data</li>
   <li><strong>Delete:</strong> Marks the email as deleted and removes it from the inbox</li>
   <li><strong>Download .eml:</strong> Downloads the original email file (if stored)</li>
 </ul>
 
-<h4>2. Email Body (Middle)</h4>
+<h4>2. Email Body (Right Side)</h4>
 
-<p>The email body is displayed in an embedded iframe:</p>
+<p>The email body is displayed on the right side of the modal in an embedded iframe:</p>
 
 <ul>
   <li>HTML emails are rendered in their original formatting</li>
@@ -154,9 +153,9 @@
   The email body is sandboxed in an iframe for security. This prevents malicious scripts from executing while still allowing you to see the formatted email content.
 </div>
 
-<h4>3. Parsed Objects (Bottom)</h4>
+<h4>3. Parsed Objects (Left Side, Below Metadata)</h4>
 
-<p>If the email was successfully parsed, this section shows the <strong>backup objects</strong> extracted from the email:</p>
+<p>If the email was successfully parsed, the backup objects are listed below the metadata on the left side:</p>
 
 <table>
   <thead>
@@ -202,18 +201,22 @@
 <ol>
   <li>Open the email detail modal by clicking on an inbox row</li>
   <li>Review the email content and parsed objects</li>
-  <li>Click the <strong>Approve</strong> button at the top of the modal</li>
-  <li>An approval dialog opens with two fields:
+  <li>Click the <strong>Approve</strong> button in the metadata section (left side)</li>
+  <li>An approval dialog opens showing:
     <ul>
-      <li><strong>Select customer:</strong> Choose which customer this backup job belongs to</li>
-      <li><strong>Job name:</strong> Pre-filled with the parsed job name (you can edit if needed)</li>
+      <li><strong>Job name:</strong> The parsed job name (read-only, cannot be edited)</li>
+      <li><strong>Select customer:</strong> Dropdown to choose which customer this backup job belongs to</li>
     </ul>
   </li>
   <li>Select the <strong>customer</strong> from the dropdown (or start typing to search)</li>
-  <li>Verify or adjust the <strong>job name</strong></li>
   <li>Click <strong>Confirm</strong> to approve</li>
 </ol>
 
+<div class="doc-callout doc-callout-info">
+  <strong>💡 Job Name Cannot Be Changed:</strong><br>
+  The job name is determined by the parser and cannot be modified during approval. If the parsed job name is incorrect, you need to fix the parser or contact support - you cannot manually override it during the approval process.
+</div>
+
 <div class="doc-callout doc-callout-tip">
   <strong>💡 Customer Selection:</strong><br>
   Always create the customer account <strong>before</strong> approving emails. This allows you to immediately link the job to the correct customer. See <a href="{{ url_for('documentation.page', section='customers-jobs', page='managing-customers') }}">Managing Customers</a> for details.
@@ -244,29 +247,24 @@
 
 <h2>Re-parsing Emails</h2>
 
-<p>If an email was not parsed correctly, you can re-parse it after updating parser configuration.</p>
-
-<h3>Re-parse Single Email</h3>
-
-<p>To re-parse a single email:</p>
-
-<ol>
-  <li>Open the email detail modal</li>
-  <li>Click the <strong>Re-parse</strong> button</li>
-  <li>BackupChecks will re-run all parsers on this email</li>
-  <li>The modal will refresh with updated parsed results</li>
-</ol>
+<p>If an email was not parsed correctly, you can re-parse it after updating parser configuration. Re-parsing is only available from the inbox page, not from the email detail modal.</p>
 
 <h3>Re-parse All Emails</h3>
 
 <p>To re-parse all emails in the inbox at once:</p>
 
 <ol>
-  <li>At the top of the inbox page, click the <strong>Re-parse all</strong> button</li>
-  <li>This re-runs parsers on <strong>all inbox emails</strong></li>
+  <li>On the inbox page, click the <strong>Re-parse all</strong> button at the top of the page</li>
+  <li>BackupChecks will re-run all parsers on <strong>all inbox emails</strong></li>
+  <li>The page will refresh showing updated parsed results</li>
   <li>Useful after adding new parsers or fixing parser bugs</li>
 </ol>
 
+<div class="doc-callout doc-callout-info">
+  <strong>💡 No Individual Re-parse:</strong><br>
+  There is no option to re-parse a single email. The "Re-parse all" button processes all emails in the inbox simultaneously. If you only want to re-parse specific emails, delete the others first, then use "Re-parse all", then re-import the deleted emails.
+</div>
+
 <div class="doc-callout doc-callout-info">
   <strong>💡 When to Re-parse:</strong><br>
   Re-parsing is useful when emails were imported before a parser was configured, or when parser logic has been updated. Re-parsing does not re-fetch emails from the mailbox - it only re-processes emails already in the database.
@@ -295,7 +293,7 @@
 
 <div class="doc-callout doc-callout-warning">
   <strong>⚠️ Soft Delete:</strong><br>
-  Emails are <strong>soft-deleted</strong>, not permanently removed. Deleted emails are hidden from the inbox but remain in the database. Admins can view deleted emails in <strong>Settings</strong> → <strong>Maintenance</strong> → <strong>Deleted mails</strong>.
+  Emails are <strong>soft-deleted</strong>, not permanently removed. Deleted emails are hidden from the inbox but remain in the database. Administrators can view deleted emails on the <strong>Deleted Mails</strong> page (visible only to Admin role).
 </div>
 
 <h2>Downloading .EML Files</h2>
@@ -317,15 +315,6 @@
   <li>Archiving backup reports outside BackupChecks</li>
 </ul>
 
-<h2>Inbox Filters and Search</h2>
-
-<p>The inbox currently displays all <strong>unapproved</strong> imported emails in chronological order (newest first). Filtering and search features are planned for a future update.</p>
-
-<div class="doc-callout doc-callout-info">
-  <strong>📝 Future Feature:</strong><br>
-  Search and filter capabilities (by sender, subject, backup software, status) are planned to help manage large inboxes. For now, use the pagination controls to browse emails.
-</div>
-
 <h2>Common Workflows</h2>
 
 <h3>Setting Up a New Customer</h3>
@@ -343,14 +332,28 @@
 <h3>Troubleshooting Unparsed Emails</h3>
 
 <ol>
-  <li>Find emails with empty <strong>Backup</strong> or <strong>Job name</strong> columns</li>
-  <li>Open the email detail modal</li>
-  <li>Review the email body to understand its format</li>
-  <li>Check if a parser exists for this backup software in <strong>Settings</strong> → <strong>Parsers</strong></li>
-  <li>If no parser exists, request one or create a custom parser</li>
-  <li>After adding a parser, use <strong>Re-parse</strong> to process the email again</li>
+  <li>Find emails with empty <strong>Backup</strong> or <strong>Job name</strong> columns in the inbox table</li>
+  <li>Open the email detail modal to review the email body and understand its format</li>
+  <li>Check if a parser exists for this backup software:
+    <ul>
+      <li>Navigate to <strong>Settings</strong> → <strong>Parsers</strong> (Admin only)</li>
+      <li>Look for a parser matching the backup software or email format</li>
+    </ul>
+  </li>
+  <li>If no parser exists:
+    <ul>
+      <li>Contact BackupChecks support or the developer to request a parser</li>
+      <li>Provide sample emails (forward .eml files) to help with parser development</li>
+    </ul>
+  </li>
+  <li>After a parser is added by the developer, use <strong>Re-parse all</strong> on the inbox page to process the emails again</li>
 </ol>
 
+<div class="doc-callout doc-callout-warning">
+  <strong>⚠️ Custom Parsers:</strong><br>
+  Parsers can <strong>only be created by the BackupChecks developer</strong>. End users cannot create or modify parsers. If you need support for a new backup software, contact support with sample email reports (.eml files).
+</div>
+
 <h3>Cleaning Up Spam or Test Emails</h3>
 
 <ol>
@@ -365,9 +368,9 @@
 <ul>
   <li><strong>Review new emails daily:</strong> Check the inbox regularly to approve new jobs promptly</li>
   <li><strong>Create customers first:</strong> Always create customer accounts before approving their jobs</li>
-  <li><strong>Use descriptive job names:</strong> Edit job names during approval if the parsed name is unclear</li>
   <li><strong>Clean up the inbox:</strong> Delete or approve emails to keep the inbox manageable</li>
-  <li><strong>Monitor parsing success:</strong> Check for emails with missing backup software - these may need parser configuration</li>
+  <li><strong>Monitor parsing success:</strong> Check for emails with missing backup software - these may need parser support from the developer</li>
+  <li><strong>Verify parsed job names:</strong> Review the parsed job name before approving - if it's incorrect, contact support to fix the parser (you cannot edit it during approval)</li>
 </ul>
 
 <h2>Next Steps</h2>
diff --git a/docs/changelog-claude.md b/docs/changelog-claude.md
index 20732a7..b4e4f8b 100644
--- a/docs/changelog-claude.md
+++ b/docs/changelog-claude.md
@@ -7,7 +7,7 @@ This file documents all changes made to this project via Claude Code.
 ### Added
 - Completed Mail & Import documentation section (4 pages):
   - **Mail Import Setup**: Microsoft Graph API configuration with enhanced security (Azure AD app registration, start with Mail.Read only, Application Access Policy to restrict access to one mailbox via Exchange PowerShell, add Mail.ReadWrite after testing), two-step save workflow clarification (same "Save settings" button clicked twice - once for credentials to enable folder browsing, then again for complete configuration), automatic folder browser popup (no manual path entry), test configuration, troubleshooting (authentication errors, folder not found, no emails imported), advanced configuration (email retention, multiple mailboxes), comprehensive security best practices including principle of least privilege, note about planned UI improvement to make two-step save workflow more obvious
-  - **Inbox Management**: Inbox overview and workflow (inbox shows ONLY unapproved emails - approved emails immediately disappear), table columns explanation (EML column shows download link, not checkmark), viewing email details with screenshot (approve-job.png showing metadata, body iframe, and approval interface), email detail modal sections (metadata with action buttons, body iframe, parsed objects - removed incorrect "Customer" and "Approved" fields), approving emails (customer selection, job name), what happens after approval (email disappears from inbox, future emails auto-approved and never appear in inbox), re-parsing emails (single and bulk), deleting emails (single and bulk delete, soft delete behavior), downloading .eml files, common workflows (new customer setup with clear approval flow, troubleshooting unparsed emails, cleaning spam), best practices
+  - **Inbox Management**: Inbox overview and workflow (inbox shows ONLY unapproved emails - approved emails immediately disappear), table columns explanation (EML column shows download link, not checkmark), viewing email details with screenshot (approve-job.png), email detail modal TWO-COLUMN layout (left: metadata + action buttons + parsed objects, right: email body iframe), action buttons (Approve, Delete, Download .eml - NO Re-parse in modal), approving emails (customer selection ONLY - job name is READ-ONLY and cannot be edited), what happens after approval (email disappears from inbox, future emails auto-approved and never appear in inbox), re-parsing emails (ONLY "Re-parse all" button on inbox page - no individual re-parse), deleting emails (single and bulk delete, soft delete viewable on "Deleted Mails" page for Admins only), downloading .eml files, common workflows (new customer setup, troubleshooting unparsed emails - parsers can ONLY be created by developer, cleaning spam), best practices (verify parsed job names before approval - cannot edit during approval), removed Inbox Filters section (not in planning)
   - **Mail Parsing**: Parsing overview and workflow (retrieval, preprocessing, parser selection, matching, parsing, storage), parsers (viewing available parsers, parser information), match criteria (sender, subject, body match), supported backup software (Veeam, Synology, NAKIVO, Boxafe, Panel3, QNAP, Syncovery, 3CX, RDrive, NTFS Auditing), parser execution order, enabling/disabling parsers, re-parsing emails, parsing workflow example, troubleshooting parsing issues, parser limitations, best practices
   - **Auto-Import Configuration**: Auto-import overview and features, enabling auto-import, import interval configuration (5/15/30/60 minutes), batch size explanation, how auto-import works (timer, check settings, authenticate, fetch, parse, auto-approve, move, log, persist, wait), auto-approval logic and conditions, when auto-approval fails, manual import (triggering, batch size 1-50), import settings summary table, monitoring import activity (audit log, inbox page, jobs/daily jobs), troubleshooting (auto-import not running, emails not auto-approved, import errors), best practices, advanced configuration (disabling temporarily, EML retention, high-volume environments)