Mailbox Maintenance

01Overview

CCI.NET Mailbox Maintenance is a PowerShell GUI tool for Microsoft 365 administrators. It performs bulk mail operations, security audits, duplicate detection and forensic investigations against Exchange Online mailboxes using the Microsoft Graph API. All API calls go directly between the tool and Microsoft. No data passes through any third-party server.

Features at a glance

Requirements

• A Windows PC with PowerShell, where you can run the script.
• A Microsoft 365 tenant and an administrator who can create an Entra ID app registration and grant admin consent.
• Optional licensing for some features: Microsoft Defender for Office 365 Plan 1 or 2 (Message Trace) and Entra ID P1 or P2 (Sign-in Anomaly Report).

02Entra app registration

The tool authenticates through an Entra ID app registration using client credentials (app-only authentication). This is a one-time setup per tenant.

Required permissions

Create the app registration

1. Open the Entra admin center at https://entra.microsoft.com.
2. Go to Identity → Applications → App registrations → New registration.
3. Fill in the form:

   Field	Value
   Name	CCI-MailboxMaintenance
   Supported account types	Accounts in this organizational directory only
   Redirect URI	Leave blank

4. Click Register.

Grant API permissions

1. Click API permissions → Add a permission → Microsoft Graph → Application permissions.
2. Search for and add each permission you need from the table above.
3. Click Grant admin consent for [Tenant].

Create a client secret

1. Click Certificates & secrets → New client secret.
2. Enter a description, set a 24-month expiry and click Add.
3. Copy the secret Value immediately.

Your three credential values

03Installation and first launch

1. Save the script to C:\scripts\CCI_MailboxMaintenance.ps1.
2. Unblock the file and set the execution policy. Run these once, as Administrator:

   Unblock-File -Path C:\scripts\CCI_MailboxMaintenance.ps1
   Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

3. Launch the tool from C:\scripts:

   .\CCI_MailboxMaintenance.ps1

4. Go to the Connection tab, enter or load your credentials and click Connect & Test. A green Connected message confirms success.

04Credential profiles

The profile bar at the top of every window saves tenant credentials under a named profile. Profiles are encrypted with Windows DPAPI and cannot be read outside the user account and machine that saved them.

Profile bar controls

Typical workflow

1. First time: paste the Tenant ID, Client ID and Client Secret into the Connection tab.
2. Click Save As... and name the profile after the organization (for example Fabrikam).
3. Every later session: select the profile, click Load, then Connect & Test.

Profile security

• Profiles are stored in C:\scripts\CCI_MailboxMaint_Profiles.json. Tenant ID and Client ID are stored as plain text. The Client Secret is DPAPI-encrypted.
• A profile copied to another machine or user account will fail to decrypt. This is by design.
• To revoke access, delete the client secret in Entra. The saved profile then becomes harmless.

05Connection tab

The Connection tab is the first tab in the window. It holds the credential fields, a Quick Start guide and a permission reference. Connect here before using any other tab.

Fields

Connect & Test

Connect & Test acquires a Bearer token and verifies Graph API access. On success it shows Connected ✓ (token valid until HH:MM:SS).

06Mail Operations tab

The Mail Operations tab is the main action screen. It has three sections: SOURCE, OPERATION and DESTINATION.

SOURCE controls

Well-known folder names

Delete (permanent)

Permanently removes matching items. Items do not go to Deleted Items; they are gone immediately. Delete uses 8 parallel threads.

Move to Mailbox

Moves matching items to another mailbox. A cross-mailbox transfer takes three API calls per message: GET from the source, POST to the destination (preserving timestamps via MAPI extended properties), then DELETE the original. The thread count is adjustable.

Copy to Mailbox

Works like Move to Mailbox, but the originals stay in the source folder. Use it to create a backup before a destructive operation, or to copy content to a shared mailbox.

Archive ALL Mail

Enumerates every mail folder recursively and moves all contents to the destination mailbox. Calendar, Contacts, Tasks and Notes folders are skipped automatically. Use it for full mailbox offboarding.

Search & Delete

Searches for items matching a KQL query and permanently deletes every match. The search repeats until 0 results remain. Example queries:

from:sender@example.com
subject:"Invoice" AND has:attachment
received>=2024-01-01 AND received<2024-06-01

DESTINATION panel

Appears automatically for Move, Copy and Archive ALL.

Thread count

The Threads spinner (1–8, default 3) controls Move and Copy parallelism. Lower is safer on busy tenants; higher is faster for large operations when traffic is light.

Run, Stop and Clear Log

Status bar

The dark bar at the bottom of the window shows live status:

• ▶ RUNNING 14m 22s | 250 Moved — Inbox (updates every 3 seconds)
• ✓ COMPLETE — Elapsed: 2h 14m 33s
• ⏹ STOPPED — Elapsed: 19m 47s
• Ready. (idle)

07Audit & Reports tab

Every audit produces an HTML report that opens automatically in your default browser and is saved to C:\scripts\. The CSV log captures all findings.

Single-mailbox audits. Enter a mailbox address in the Mailbox field at the top of the tab, then click the audit you want.

Folder Size Report

Lists every mail folder with its item count and unread count in a sortable HTML table. Folders over 10,000 items are highlighted amber. Run this first, before any bulk operation, to understand the mailbox's volume.

Hold Status Check

Checks the Recoverable Items size as an indicator of litigation or retention hold. For definitive status, use Exchange Online PowerShell:

Get-Mailbox user@example.com | Select LitigationHoldEnabled,RetentionHoldEnabled

Forward & Delegate Audit

Company-Wide Bulk Audit

Scans every licensed mailbox in the tenant. Requires User.ReadBasic.All. Only mailboxes with findings are shown on screen; clean mailboxes are logged to CSV.

Email Timeline Audit

Shows the complete email activity for a mailbox in a date window. Choose one of three source modes:

Options: Start/End Date, Start/End Time, Timezone (default Pacific Standard Time), Received / Sent / Deleted checkboxes, and All Mail Folders.

08Duplicate Finder tab

Scans a mailbox for duplicate email messages, contacts or calendar events. Dry Run is checked by default, so the first run always produces a report only, with nothing deleted.

Mode selection

Email controls

Shown in Email Messages mode.

Workflow

1. Enter the mailbox address, select a mode and confirm Dry Run is checked.
2. Click Scan for Duplicates. The tool scans and groups items by match key.
3. An HTML report opens showing total scanned, groups found, items to delete, and a 50-group sample (green = KEEP, red = WOULD DELETE).
4. A CSV file is written with every group. Review it in Excel to confirm the pattern looks right before going further.
5. If you are satisfied, uncheck Dry Run and click Scan for Duplicates again to delete.

How duplicates are resolved

Within each duplicate group the oldest item (earliest received or created date) is kept and all others are deleted.

• Contacts are grouped by email address, or by display name if there is no email address.
• Calendar events are grouped by subject + organizer + start date/time.

09Security Investigations tab

Six forensic audit tools for breach response, designed to answer three questions: how did the attacker get in, what did they do, and how are they keeping access?

Shared controls

OAuth App Audit

Lists every third-party application granted OAuth2 permissions in the tenant. Attackers often register malicious OAuth apps to keep access even after a password reset. Requires Application.Read.All.

• Apps with Mail.Read or Mail.ReadWrite scopes are flagged red.
• Unverified publishers are flagged. Legitimate apps are almost always verified.

External Forwarding Domains

Scans every mailbox for inbox rules that forward externally and for admin SMTP forwarding. Results are grouped by destination domain. Domains that 5 or more mailboxes forward to are highlighted red. Requires User.ReadBasic.All.

Attachment Inventory

Lists all attachments received in a date window, with filename, type, size, sender and subject. Dangerous file types (EXE, ZIP, JS, PS1, BAT, VBS, CMD, HTA, SCR, PIF) are flagged red. Files over 5 MB are highlighted for exfiltration review.

Sign-in Anomaly Report

Shows the Entra ID sign-in log for a mailbox in a date window. It surfaces failed attempts, high-risk events, sign-ins from unusual countries and login storms. Requires AuditLog.Read.All and Entra ID P1 or P2.

Mailbox Permission Snapshot

Exports all calendar delegates and mailbox sharing permissions across every mailbox. Run it before and after a suspected breach to spot delegate access added by an attacker. Requires User.ReadBasic.All.

Suspicious Rule Detector

Evaluates every inbox rule and assigns it a risk score. It also detects hidden MAPI rules that are invisible in Outlook and in the standard Graph API.

Scoring criteria

Risk levels

10Troubleshooting tab

Permission Checker

Click Run Permission Check to verify every permission with live API calls, not just by checking what is listed in Entra. The check runs in a background thread so the window stays responsive.

Reconnect & Recheck

Acquires a fresh Bearer token and immediately reruns all permission tests. Use it every time you add or change a permission in Entra.

Permission reference

Common errors and fixes

11Performance and throttling

Performance summary

Throttling

• HTTP 429 (Too Many Requests) is handled automatically. The tool reads Retry-After and pauses. No items are skipped.
• Microsoft can return Retry-After values of 30–120 seconds on large operations against busy tenants.
• If there is no progress for 5 minutes, a stuck-thread safeguard fires: it logs a warning and breaks the thread pool so processing continues with the next page.
• A 30-minute hard timeout per page prevents infinite hangs.

Resuming after Stop

If you stop a Move and run it again with the same settings, the items already moved are no longer in the source folder. The date filter applies to the source only, so nothing is processed twice.

12Security and logs

Security considerations

• The Client Secret is held in memory only during the session. The script never writes it to disk in plain text.
• The profile file stores the Client Secret DPAPI-encrypted, readable only by the same Windows user on the same machine.
• Mail.ReadWrite grants access to every mailbox in the tenant. Treat credential profiles like a Global Admin password.
• Rotate the client secret annually, or whenever a team member with access leaves.
• To revoke access immediately, delete the app registration or disable the secret in Entra.

Logs and files

Exchange Online reference commands

Useful Exchange Online PowerShell commands for confirming what the tool reports:

Connect-ExchangeOnline -UserPrincipalName admin@example.com
Get-Mailbox user@example.com | Select LitigationHoldEnabled,RetentionHoldEnabled
Get-MailboxPermission user@example.com | Where { $_.AccessRights -eq 'FullAccess' }
Get-InboxRule -Mailbox user@example.com | Select Name,Enabled,ForwardTo,DeleteMessage
Get-MailboxFolderStatistics user@example.com | Select Name,ItemsInFolder | Sort ItemsInFolder -Desc

13Quick reference

14Getting help

Questions, bug reports, feature requests or a copy of the tool: email info@taucher.llc. You'll reach the people who wrote the software.