Setup Guide

A complete walkthrough of every setting in CaseDocMover, with examples for each field.

Installation & Activation

Download the installer for your operating system from the pricing page, then run it.

  1. macOS — open the .dmg, drag CaseDocMover to Applications, then double-click to launch.
  2. Windows — run CaseDocMover.exe. If Windows SmartScreen appears, click More info → Run anyway.
  3. Linux — install the .deb with sudo dpkg -i casedocmover_*.deb, or run the standalone binary directly.

On first launch an activation dialog appears. Enter the license key that was emailed to you after purchase (format: XXXX-XXXX-XXXX-XXXX) and click Activate. The app validates the key online and then starts.

ℹ

CaseDocMover has a 30-day offline grace period. If your machine loses internet access the app will keep running using the last successful validation. After 30 days a renewal prompt will appear.

Once activated the app icon appears in your system tray / menu bar. Right-click it to open Settings, view logs, or quit.

Email Provider

Open Settings → Email Account and choose the provider that matches your mailbox.

Microsoft 365 / Exchange

Three authentication modes are available. Pick the one that matches how your organization manages app access.

Auth moderequired
delegated — device code flow. On first run the app displays a URL and a short code; visit the URL in any browser, enter the code, and sign in once. The refresh token is cached for all future sessions. Best for personal or single-user setups.
app_only — the app authenticates as itself using a client secret; no user sign-in required. Requires an Azure AD app registration with Mail.ReadWrite application permission granted by an admin. Best for shared/service accounts.
ropc — Resource Owner Password Credentials. The app signs in with a username and password to bootstrap the token cache, then immediately erases the password from storage. All subsequent sessions use the cached refresh token silently — identical to delegated mode once authenticated. Use when no browser is available on the machine. Does not support MFA or federated (ADFS/SAML) accounts.
Tenant IDrequired
The Azure Active Directory tenant ID (a GUID), e.g. 9b5c3a1e-4f72-4d18-b3e2-7a2c05d1f234. Use common for personal Microsoft accounts.
Find it at portal.azure.com → Azure Active Directory → Overview → Tenant ID.
Client IDrequired
The Application (client) ID from your Azure app registration.
Find it at portal.azure.com → App registrations → your app → Overview → Application (client) ID.
Client secret
Required for app_only mode only. Create one at App registrations → your app → Certificates & secrets.
Mailbox
The mailbox to monitor. Use me for the signed-in user (delegated/ROPC) or a full email address such as [email protected] for a shared mailbox (app_only).
Username / Password
Required for ropc mode only. Enter the Microsoft 365 UPN (e.g. [email protected]) and the account password. The password is used once to sign in and is then erased automatically — it is never stored beyond the initial authentication. If the cached token is later invalidated (e.g. after a password change or admin revocation), re-enter the password here and save to re-authenticate.
# delegated example
Auth mode:  delegated
Tenant ID:  9b5c3a1e-4f72-4d18-b3e2-7a2c05d1f234
Client ID:  e1d2c3b4-a5f6-7890-abcd-ef1234567890
Mailbox:    me

# app_only example (shared mailbox)
Auth mode:      app_only
Tenant ID:      9b5c3a1e-4f72-4d18-b3e2-7a2c05d1f234
Client ID:      e1d2c3b4-a5f6-7890-abcd-ef1234567890
Client secret:  ~Abc8Q...
Mailbox:        [email protected]

Outlook.com / Hotmail (personal account)

Choose Outlook.com / Hotmail (personal account) in Settings → Email Account. No Azure AD app registration is required — just your email address and an app password.

ℹ

Microsoft requires an app password (a separate one-time credential) for apps that connect directly to personal Outlook mailboxes. Your regular login password will not work here.

Email addressrequired
Your full Outlook.com or Hotmail address, e.g. [email protected].
App passwordrequired
A one-time credential generated specifically for CaseDocMover. To create one:
  1. Go to account.microsoft.com → Security → Advanced security options.
  2. Under App passwords, click Create a new app password.
  3. Name it CaseDocMover and copy the generated password.
  4. Paste it into the App password field in Settings.
Folder to monitor
The mailbox folder to watch. Default is INBOX. Use standard IMAP folder names (e.g. Inbox, INBOX/Cases).
ℹ

The server address (outlook.office365.com:993) and SSL settings are pre-configured automatically — you do not need to enter them.

Email address:  [email protected]
App password:   abcd efgh ijkl mnop   ← generated at account.microsoft.com
Folder:         INBOX

Gmail / Google Workspace

CaseDocMover uses the Gmail API with OAuth2. You need a Google Cloud project with the Gmail API enabled and OAuth2 credentials created.

  1. Go to console.cloud.google.com → APIs & Services → Credentials.
  2. Create an OAuth client ID for a Desktop application.
  3. Download the JSON and either place it as gmail_client_secret.json in the app config folder, or paste the Client ID and Secret into the fields below.
Client ID
The OAuth2 client ID from your Google Cloud credentials (ends in .apps.googleusercontent.com).
Client secret
The OAuth2 client secret.
Label to monitor
The Gmail label (mailbox folder) to watch for new emails. Defaults to INBOX. Use any Gmail label name exactly as it appears in Gmail — for example Legal/Filings for a nested label, or a custom label like Court Docs.
Find your label names at Gmail → Settings → Labels.
INBOX                   ← default, monitors the main inbox
Legal/Filings           ← nested label (parent/child)
Court Docs              ← custom flat label
ℹ

On first save, CaseDocMover will open a browser window asking you to sign in to Google and grant access to your Gmail account. The refresh token is then stored locally so subsequent launches are automatic.

Client ID:        123456789-abc123.apps.googleusercontent.com
Client secret:    GOCSPX-AbCdEfGhIj...
Label to monitor: Legal/Filings

IMAP (Yahoo, iCloud, Zoho, other)

Use this for any mailbox accessible over IMAP — Yahoo Mail, Apple iCloud Mail, Zoho, FastMail, and most hosted email services.

Hostrequired
The IMAP server hostname.
Yahoo Mail:  imap.mail.yahoo.com
iCloud:      imap.mail.me.com
Zoho:        imap.zoho.com
FastMail:    imap.fastmail.com
Port
993 for SSL (recommended), 143 for STARTTLS.
Use SSL
Leave checked unless your server requires plain STARTTLS on port 143.
Usernamerequired
Your full email address, e.g. [email protected].
Passwordrequired
For Yahoo Mail and iCloud you must use an app-specific password, not your main account password, because these providers require it when MFA is enabled.
Yahoo: Account Security → Generate app password. iCloud: appleid.apple.com → Sign-In and Security → App-Specific Passwords.
Folder
The mailbox folder to monitor. Default is INBOX. Use standard IMAP folder names; some servers use INBOX.Subfolder notation.

Email Filters

Filters control which incoming emails are processed. Emails that do not match all active filter sections are ignored. Leave a section empty to skip that check entirely.

Sender addresses
One email address per line. Only emails from these exact addresses will be processed (case-insensitive).
[email protected]
[email protected]
Sender domains
One domain per line. Matches any sender whose address ends with@domain.
courts.gov
lawfirm.com
Subject keywords
One keyword per line. CaseDocMover checks whether the email subject contains these words (case-insensitive).
Match mode
Any keyword (OR) — process the email if the subject contains at least one of the keywords.
All keywords (AND) — process only if the subject contains every keyword.
Keywords:   Case, Filing
Mode: ANY  → matches "New Case Filing" and also "Case Review"
Mode: ALL  → matches "New Case Filing" but NOT "Case Review"
ℹ

If all three filter sections are empty, every email with an attachment is processed. Add filters to narrow down to relevant senders.

File Storage

Open Settings → Document Storage and select where documents should be filed.

SharePoint (Microsoft 365)

CaseDocMover uploads files to a SharePoint Document Library using the Microsoft Graph API. The app searches for a folder whose name matches the extracted case number. Use the Browse button to pick your site, library, and folder from a graphical browser instead of entering IDs manually.

ℹ

SharePoint always requires Microsoft Graph API credentials (Tenant ID + Client ID) regardless of which email provider you use. If your email provider is already Microsoft 365, these credentials are reused automatically. If you use Gmail, IMAP, or Outlook.com for email, a separate Microsoft 365 credentials section will appear at the top of the SharePoint panel — enter your Tenant ID and Client ID there.

SharePoint Siterequired
The GUID of the SharePoint site. Click Browse to select it visually, or find it with Graph Explorer:
GET https://graph.microsoft.com/v1.0/sites/{hostname}:/sites/{site-name}
# Copy the "id" field from the response
Document Libraryrequired
The GUID of the Document Library (drive). Click Browse to select it visually, or find it with:
GET https://graph.microsoft.com/v1.0/sites/{site-id}/drives
# Locate the drive by "name", copy its "id"
Unmatched Files Folder
Optional. The SharePoint item ID of a “Manual Review” folder. When no matching case folder is found, the document is placed here instead of being skipped. Find it with:
GET https://graph.microsoft.com/v1.0/sites/{site-id}/drives/{drive-id}/root/children
# Locate the folder by "name", copy its "id"

Box

Auth mode
jwt — server-to-server authentication using a Box JWT app. Requires a Box Platform application with App Access Only or App + Enterprise Access. Best for automated/service use.
oauth2_token — use a developer token or a pre-acquired OAuth2 access token. Tokens expire after 60 minutes; suitable for short-term testing.
JWT config path
Required for jwt mode. The full path to the JSON key file downloaded from the Box Developer Console (Configuration → Add and manage public keys).
macOS/Linux:  /Users/you/box_jwt_config.json
Windows:     C:Usersyouox_jwt_config.json
Root folder ID
The Box folder ID to search for case folders. Use 0 for the root of All Files, or paste the numeric ID from the URL when browsing Box: app.box.com/folder/123456789 → ID is 123456789.
Review folder ID
Optional. Numeric Box folder ID for unmatched documents.

Dropbox

App key / App secretrequired
Create a Dropbox app at dropbox.com/developers/apps. Choose Scoped access and grant files.content.write and files.content.read permissions. Copy the App key and App secret from the settings page.
Refresh tokenrequired
A long-lived OAuth2 refresh token. Generate one by running the Dropbox OAuth flow once (the app will prompt you on first save if the token is empty).
Root path
The Dropbox folder path to search for case folders. Use /Cases to search within a Cases folder, or leave empty to search from the Dropbox root.
Root path:  /Clients/Active Cases
Review folder
Optional. Full Dropbox path for unmatched documents, e.g. /Manual Review.

SMB / Network Share (on-prem)

For Windows file servers or NAS devices accessible over SMB/CIFS.

Serverrequired
Hostname or IP address of the file server, e.g. fileserver01 or 192.168.1.50.
Sharerequired
The SMB share name (without backslashes), e.g. Cases.
Root UNC pathrequired
The full UNC path to the root folder to search, e.g. \\fileserver01\Cases\Active.
Review UNC path
Optional. Full UNC path for unmatched documents, e.g. \\fileserver01\Cases\Manual Review.
Username / Password
Domain credentials, e.g. DOMAIN\username. Leave blank to use the currently logged-in Windows user (pass-through auth).
Port
Default is 445 (standard SMB). Change only if your network uses a non-standard port.
Server:         fileserver01
Share:          Cases
Root UNC path:  \fileserver01CasesActive
Review UNC:     \fileserver01CasesManual Review
Username:       CORPcasedocmover
Port:           445

Case Matching

Open Settings → Case Matching to control how CaseDocMover identifies case numbers and names uploaded files.

Case number patternrequired
A Python-compatible regular expression that matches case numbers in email subjects or bodies. The first capturing group (or whole match if no group) becomes the {case_number} variable. Click the ? button next to the field to open the regex helper — it includes a library of common law firm patterns and a live tester so you can verify your regex against sample text before saving.
# Matches formats like CV-2024-001234 or CR-20241234
Default:  [A-Z]{2,4}-d{4,8}

# Matches 6-digit numbers preceded by "Case"
Custom:   Cases+(d{6})

# Matches US federal case numbers like 1:24-cv-00123
Federal:  d:d{2}-[a-z]{2}-d{5}
Filename template
Template for the uploaded filename. Click the ? button to open the template builder — it shows all available placeholders with live previews and preset templates you can load with one click. Available placeholders:
  • {case_number} — extracted case number
  • {sender} — sender email address (@domain stripped)
  • {date} — email date as YYYY-MM-DD
  • {ext} — original file extension including the dot (e.g. .pdf)
  • Any custom rule name defined in Advanced Rules (e.g. {client_name})
Default:   {case_number}_{sender}_{date}{ext}
           → CV-2024-001_supremecourt.gov_2025-03-15.pdf

Custom:    {date}_{case_number}_{client_name}{ext}
           → 2025-03-15_CV-2024-001_Smith_John.pdf
Fuzzy match threshold
How closely a folder name must match the extracted case number before CaseDocMover considers it a match (0–100%). The default is 80%.
Lower this value if your folder names have slight variations (e.g. spaces vs. dashes). Raise it to avoid false matches in large folder trees.
Folders:  "CV-2024-0012", "CV-2024-00121"
Extracted: CV-2024-001

Threshold 80% → matches "CV-2024-0012" (score ≈83%)
Threshold 90% → no match (falls back to Review folder)
Folder cache TTL
How long (in minutes) to cache the list of folders fetched from storage before refreshing it. Default is 30 minutes. Increase this on large SharePoint drives to reduce API calls. Decrease it if new case folders are created frequently.

Schedule

Open Settings → Schedule to control how often CaseDocMover checks your inbox for new emails.

Real-time
For IMAP accounts: uses IMAP IDLE to be notified the moment a new email arrives. For Microsoft 365 and Gmail: polls every 30 seconds using a delta/change query. Lowest latency; uses a persistent connection.
Every N minutes
Polls the inbox on a fixed interval. Options: 1, 5, 10, 15, 30, or 60 minutes. A good balance between latency and resource use. Default is 5 minutes.
Daily schedule
Polls once or several times per day at fixed times, calculated from an anchor hour.
Times per day: 2
Anchor hour:   08:00
→ Checks at 08:00 and 20:00 daily

Reports

Open Settings → Reports to configure automated email summaries. When enabled, CaseDocMover sends an HTML report on a daily or weekly schedule listing every email processed during the period — including the case number, destination folder, and uploaded filename.

Enable reports
Master on/off switch. All other report settings are hidden when disabled.
Recipients
One email address per line. All listed addresses receive every report.
[email protected]
[email protected]
Schedule
Daily — sends one report each day at the configured hour.
Weekly — sends one report per week on the configured day and hour.
Send hour
The hour of day (0–23) at which the report is sent. Default is 8 (8:00 AM local time).
Day of week
Shown only when Schedule is set to Weekly. Choose which day the weekly report is delivered (Monday through Sunday).

SMTP Settings

Reports are sent via any standard SMTP server. Use your firm's outbound mail relay, or a transactional email service such as SendGrid, Mailgun, or Amazon SES.

SMTP hostrequired
The outbound mail server hostname.
Office 365:  smtp.office365.com
Gmail SMTP:  smtp.gmail.com
SendGrid:    smtp.sendgrid.net
Port
587 for STARTTLS (recommended), 465 for implicit TLS, 25 for unencrypted (not recommended).
Use TLS
Leave checked to encrypt the connection via STARTTLS. Uncheck only if your relay requires plain SMTP on port 25.
Username / Password
SMTP authentication credentials. For Gmail, use an app-specific password. For Office 365, use the mailbox UPN and password (or an app password if MFA is enabled).
From address
The sender address that appears in the report email, e.g. [email protected]. Must be authorized by your SMTP relay.
ℹ

Use the Send test report button to verify your SMTP settings before saving. A test report containing any emails processed in the last 7 days will be sent immediately to all recipients in the list.

SMTP host:    smtp.office365.com
Port:         587
Use TLS:      ✓
Username:     [email protected]
From address: CaseDocMover <[email protected]>
Recipients:   [email protected]

Advanced Rules

Open Settings → Advanced Rules to define custom variables extracted from each email. These variables can then be used in the Filename template and in the Folder search template.

Each rule has four fields:

Namerequired
A short identifier used as a template placeholder, e.g. client_name becomes {client_name} in your filename template. Use lowercase letters, numbers, and underscores only.
Sourcerequired
Where to extract the value from:
  • subject — the email subject line
  • body — the plain-text email body
  • sender — the From address
  • date — the email date (returns YYYY-MM-DD)
Type
regex — apply a regular expression pattern to the source text. The first capturing group is used; if there are no groups, the whole match is used.
structured — use the entire source field as-is (useful with sender or date).
Pattern
The regex pattern (only used when Type is regex).
# Extract client surname from subject like "RE: Smith, John - CV-2024-001"
Name:     client_name
Source:   subject
Type:     regex
Pattern:  ^RE:s+([w]+),

# Extract court name from body
Name:     court
Source:   body
Type:     regex
Pattern:  Filed in thes+(.+?)s+Court

# Use sender domain as a variable
Name:     sender_domain
Source:   sender
Type:     regex
Pattern:  @([w.]+)$

Folder search template

Controls what string CaseDocMover searches for when looking up a matching folder in storage. Defaults to {case_number}.

You can combine multiple variables to build a more specific query, which helps avoid false matches in large folder structures.

# Default — search by case number only
Folder search template:  {case_number}

# Prefix with a client name to narrow results
Folder search template:  {client_name} {case_number}
# → searches for "Smith CV-2024-001"

# Use court name as folder prefix
Folder search template:  {court} {case_number}
# → searches for "District Court CV-2024-001"
⚠

If no folder matches the search template, the document is placed in the Review folder (if configured) or skipped with a desktop notification. Check the log window for details.

Status

Open Settings → Status to see real-time information about the current processing cycle and connection health.

Last Processing Cycle
Shows the timestamp of the last run, how many emails were fetched and processed, the total processed since the app started, and the last error (if any).
Next run
The scheduled time of the next polling cycle. Click Run Now to trigger an immediate cycle without waiting for the schedule.
Connection Status
Probe both the email provider and the storage provider on demand. Click Test Connections to verify credentials and connectivity without processing any emails.

Help & Logs

Open Settings → Help & Logs to view the in-app activity log and access support options.

Recent activity log
A live tail of the application log showing every email fetched, processed, and filed — including case numbers, destination folders, filenames, and any errors. Color-coded by severity.
Open Full Log Window
Opens a resizable log viewer with the full history of the current session. Share the log output with support when troubleshooting.
ℹ

If something is not working, copy the log output from Settings → Help & Logs and email it to [email protected].

Still stuck? Contact support and include the log output from Settings → Help & Logs.