Installation

AirMarshal is currently available for Windows. Download the installer from the Dashboard and follow these steps.

System Requirements

• Windows 10 or Windows 11
• Microsoft 365 or Outlook.com email account
• Internet connection
• Claude API key from Anthropic (or Claude Pro/Max subscription for OAuth)

Installation Steps

1. Download the installer from the Dashboard
2. Run AirMarshal-Setup-x.x.x.exe
3. Follow the installation wizard
4. AirMarshal will launch automatically and appear in your system tray

AI Configuration

AirMarshal uses AI to analyze your emails. As a beta user, you have three options:

Option 1: Claude API Key (Recommended)

AirMarshal uses Claude AI to analyze your emails. You'll need an API key from Anthropic:

1. Go to console.anthropic.com
2. Create an account or sign in
3. Navigate to API Keys and create a new key
4. Copy the key (you won't be able to see it again)
5. In AirMarshal Settings, select "Claude API Key" as your AI provider
6. Paste your key and save

First Run Setup

After installation, AirMarshal will guide you through setup with an interactive tour.

Interactive Onboarding Tour

On first launch, AirMarshal shows an interactive walkthrough that:

• Guides you through each section of the app
• Highlights important features with spotlight effects
• Explains Dry Run mode and how to stay safe
• Ends on the Settings page where you'll configure your accounts

You can restart the tour anytime from Settings > Help > Restart Tour.

Step 1: Sign In with Microsoft

1. Go to Settings and click "Connect" under Microsoft Graph
2. A device code will appear prominently in the Settings page - click the code to copy it to your clipboard
3. Your browser should open automatically. If not, click the "click here to open" link below the code
4. Paste the code on the Microsoft sign-in page
5. Sign in and grant the requested permissions

Permissions Explained

Step 2: Configure AI Provider

AirMarshal needs an AI provider to analyze your emails. You have two options:

Claude API Key

1. Go to the Settings page
2. Under AI Provider, select "Claude API Key"
3. Paste your API key from console.anthropic.com
4. Click Save

Claude OAuth (Experimental)

If you have a Claude Pro or Max subscription, you can use OAuth to authenticate without an API key:

1. Under AI Provider, select "Claude OAuth"
2. Click "Connect" and sign in with your Claude account

Step 3: Verify Connection

The Dashboard should now show:

• Your email address under "Connected Account"
• "AI: Connected" status
• Processing status: "Paused" (waiting for rules)

Next: Creating Your First Rules

Creating Rules

Rules tell AirMarshal how to handle your emails. Write them in plain English - no complicated syntax required.

Rule Basics

Go to the Rules page and type a rule in natural language. AirMarshal understands context, so be as specific or general as you like.

Example Rules

Rule Tips

• Be specific - "Move emails from amazon.com" is clearer than "Move shopping emails"
• Use exceptions - "Move X except when Y" helps avoid false positives
• Start simple - Add one or two rules, observe the results, then add more
• Check Dry Run results - Review what AirMarshal would do before enabling real actions

Available Actions

Dry Run Mode

Dry Run mode lets you see what AirMarshal would do without actually making changes. It's enabled by default for safety.

How It Works

When Dry Run is enabled:

• AirMarshal processes emails and decides on actions
• Actions are logged to the History page with a "Dry Run" badge
• No actual changes are made to your emails
• You can review each action and approve or reject it

Reviewing Dry Run Actions

1. Go to the History page
2. Look for entries marked "Dry Run"
3. Review what action AirMarshal wanted to take
4. If correct, click Accept to learn the pattern, or Accept & Execute to also apply the action immediately
5. If incorrect, click Teach to correct it and create the right pattern

Disabling Dry Run

Once you're confident in your rules:

1. Go to Settings
2. Toggle "Dry Run Mode" off
3. Click Save

Learning from Actions

AirMarshal uses a two-tier learning system. When the AI makes a suggestion, you can quickly approve it or correct mistakes to teach it the right behavior.

Two-Tier System

AirMarshal organizes learning into two tiers:

Quick Accept

For AI suggestions you agree with:

1. Go to the History page
2. Find an amber "Would Move" or "Would Flag" entry
3. Click the Accept button
4. The action is saved as a Tier 1 learned pattern

This is the fastest way to train AirMarshal - one click and it learns the pattern.

Accept & Edit

For more control over what AirMarshal learns:

1. Click Accept & Edit on any history item
2. Review the suggested action and folder
3. Choose what to learn:
   • This sender - Apply to all emails from this address
   • This domain - Apply to all emails from this company
   • Similar subjects - Apply to emails with similar topics
4. Click Confirm to save the pattern

How Learning Works

When you approve or teach AirMarshal:

• A Tier 1 pattern is saved to the database
• Future emails matching the pattern are handled without calling the AI
• Tier 1 patterns take priority over Tier 2 AI rules
• History shows a green "Learned" badge for pattern-triggered actions

Rule Editing

Edit, delete, and apply rules directly from the Rules page - no need to manually edit files.

Editing Rules

Both Tier 1 learned patterns and Tier 2 AI rules can be edited directly:

1. Go to the Rules page
2. Find the rule you want to edit
3. Click the Edit (pencil) button
4. Modify the rule in the modal dialog
5. Click Save to apply changes

Editing Tier 1 Patterns

When editing a learned pattern, you can change:

• Pattern type - Sender, domain, or subject matching
• Pattern value - The text to match
• Actions - Select multiple actions with checkboxes:
  • Move to folder (with folder picker)
  • Flag the email
  • Mark as read
  • Delete
• Secondary condition - Add AND conditions for more specific matching

Editing Tier 2 Rules

Tier 2 rules from your AIRMARSHAL.md file can also be edited:

• Condition - The "if" part of the rule
• Action - What to do when the condition matches
• Folder - For sorting rules, the destination folder

Deleting Rules

To remove a rule you no longer need:

1. Find the rule on the Rules page
2. Click the Delete (trash) button
3. Confirm the deletion

Retroactive Rule Application

Apply rules to emails that are already in your inbox:

1. Find the rule you want to apply retroactively
2. Click the Apply Retroactively button
3. AirMarshal searches your inbox within the Historical Lookback period (configured in Settings) and shows a preview of matching emails
4. Review the list and click Apply to All
5. The rule action is executed on all matching emails

Compound Conditions

Create more specific patterns using AND conditions:

Compound conditions help avoid false positives by requiring multiple criteria to match.

Action History

The History page shows everything AirMarshal has done with color-coded entries for easy scanning.

Color Coding

History entries are color-coded to show their source:

History Entry Details

Each entry shows:

• Timestamp - When the action occurred
• Email details - Subject and sender
• Action taken - What AirMarshal did (or would do in Dry Run)
• Confidence - How certain the AI was (0-100%)
• Badges - "Dry Run", "Learned", or tier indicator
• AI Reasoning - Why the AI made this decision

Filtering History

Use the search and filter options to find specific actions:

• Search by sender or subject
• Filter by action type (moved, archived, etc.)
• Filter by source (rule, learned, dry run)
• Date range selection

Taking Action on History

Teaching and correction buttons are available on all history entries, not just dry-run actions:

• Accept - Quick one-click approval, creates a Tier 1 learned pattern
• Accept & Edit - Review and customize the pattern before saving (choose sender, domain, or subject matching)
• Accept & Execute - For pending "Needs Input" actions: approve and immediately execute the suggested action on the email
• Teach - Correct a mistake by specifying the right action and create a new pattern
• Revert - Undo an executed action: moves the email back to its original folder, restores flag status, or restores read/unread state

Beta Program Guide

Welcome to the AirMarshal beta! Here's what you need to know about participating in the beta program.

What's Available

• Full email processing with Claude AI
• Natural language rule creation
• Dry Run mode for safe testing
• Learning from corrections
• Action history and auditing
• Daily AI-generated digest summaries
• Backup & restore for settings and patterns
• Auto-updates to latest beta versions

What's Coming

• Free built-in AI (no API key required)
• Calendar integration and scheduling
• Auto-reply drafting
• macOS support

Beta Expectations

• Report bugs - Use the Feedback page or send logs from the app
• Share ideas - Feature requests are welcome
• Be patient - Beta software may have rough edges
• Keep updated - Install updates when prompted for bug fixes

Sending Logs

If you encounter an issue, sending logs helps us diagnose and fix the problem quickly.

How to Send Logs

From the App (recommended):

1. Open AirMarshal and go to Settings
2. Scroll to the Beta Feedback section
3. Optionally add notes describing the issue
4. Click "Send Logs"

From the System Tray:

1. Right-click the AirMarshal icon in your system tray
2. Select "Send Logs"

What's Included

Log files contain:

• Application logs (errors, warnings, debug info)
• Your rules configuration
• System information (OS version, app version)

Privacy Mode

When privacy mode is enabled in Settings, logs are automatically sanitized before upload:

• Email addresses - Replaced with [email]
• Email subjects - Replaced with [X chars]
• Display names - Replaced with [name]
• Folder paths - Replaced with [folder]
• Message IDs - Replaced with [id]

This preserves enough context for debugging while protecting your sensitive data.

Known Issues

Current known issues and limitations in the beta version.

Current Limitations

Recently Fixed

• v1.8.2 - Fixed "Emails Processed" counter to include all reviewed emails; fixed pending action badge showing "Moved" instead of "Needs Input"; added AI contradiction safety check
• v1.8.1 - Fixed dashboard stats showing zeros; improved Microsoft sign-in with visible device code modal
• v1.8.0 - NEW: Backup & Restore - create backups of your settings, rules, and patterns; restore from .ambu files; automatic daily backups; backup prompt when deleting profiles
• v1.7.10 - Dashboard tooltips explain counters, processing status with countdown, Top Destinations chart, fixed Daily Digest time range and "Reviewed" tracking
• v1.7.9 - Fixed folder cache persistence (no more resetting to 0), Accept & Execute now properly moves emails, "mark as read" works in learned patterns
• v1.7.7 - Fixed test mode settings not applied when resuming, "Do Nothing" now shows as "Reviewed", fixed duplicate history entries
• v1.7.5 - Fixed duplicate processing where reviewed emails were re-analyzed every poll cycle. Added "Accept & Execute" button for pending actions.
• v1.7.4 - Teaching from any action, Revert/Undo button, uncertain emails in History with "Needs Input" badge
• v1.7.3 - Fixed emails being lost when AI hits rate limit - they now automatically retry
• v1.7.2 - Fixed "object not found" errors when Outlook rules move emails before processing
• v1.7.0 - AI provider selection, improved error handling

Reporting New Issues

Found something not listed here? Please report it:

1. Use the Feedback page with type "Bug Report"
2. Include steps to reproduce if possible
3. Send logs from the app for technical issues

Frequently Asked Questions

Common questions about AirMarshal.

Troubleshooting

Solutions to common problems.

Dashboard

The Dashboard is your at-a-glance overview of AirMarshal's activity. It shows what's happening right now and a summary of today's work.

Today's Activity

The top section shows two counters for the current day:

• Emails Processed - The number of unique emails AirMarshal has reviewed today, including emails where no action was needed. Hover the (?) icon for details.
• Actions Taken - The number of actions executed (moves, deletes, flags, mark as read). Compound actions (e.g., move + mark as read) count as multiple actions.

These counters reset at midnight and are tracked independently of the action history database.

Processing Status

Below the counters, a real-time status display shows:

• Whether AirMarshal is currently processing, paused, or waiting
• When the last inbox check occurred
• How many emails were processed in the last poll
• A countdown to the next inbox check

Top Destinations

A bar chart showing which folders receive the most emails, based on your action history. This helps you see your email routing patterns at a glance.

Stats Summary

Historical statistics showing email counts by action type (moved, deleted, flagged, etc.) for different time ranges.

Available since v1.7.10

Daily Digest

The Daily Digest is an AI-generated summary of everything AirMarshal did since the last digest, delivered automatically at your chosen time.

What's in the Digest

• Time period covered - From the last digest to now (no gaps between digests)
• AI-generated highlights - A natural language summary of key activity
• Action breakdown - Counts by type (moved, deleted, flagged, marked read, reviewed)
• Detailed lists - Every email acted on, grouped by action type
• Top senders - Which senders generated the most actions

Scheduling

By default, the digest runs automatically at 5:00 PM each day. You can change this in Settings:

1. Go to Settings
2. Find the Daily Digest section
3. Set your preferred digest time
4. Toggle the digest on or off

Manual Trigger

You can generate a digest at any time by clicking the Daily Digest button in the sidebar. If a digest was already generated today, it will be updated with the latest activity.

Digest History

AirMarshal keeps the last 14 days of digests. You can browse previous digests from the Digest page using the date selector.

Available since v1.7.10

Backup & Restore

AirMarshal can back up your settings, rules, learned patterns, and action history to a portable file, and restore them later.

What's Included in a Backup

• Settings - All your configuration (poll interval, confidence threshold, theme, etc.)
• Rules - Your AIRMARSHAL.md rules file
• Learned Patterns - All Tier 1 patterns you've taught
• Action History (optional) - Your full processing history
• API Keys (optional) - Your saved API credentials

Creating a Backup

1. Go to Settings
2. Find the Backup & Restore section
3. Choose whether to include History and API Keys
4. Click Create Backup
5. Choose where to save the .ambu file

Restoring from Backup

1. Double-click any .ambu file to open it in AirMarshal, or use Settings > Restore
2. AirMarshal shows a preview of what's in the backup
3. Select which sections to restore (settings, rules, patterns, history, API keys)
4. Click Restore to apply

Automatic Daily Backups

AirMarshal automatically creates a backup each day (alongside the daily digest). These are stored in your Documents/AirMarshal folder.

Available since v1.8.0

Settings

The Settings page lets you configure how AirMarshal processes your emails, when it runs, and how it behaves.

Processing Settings

Startup & Behavior

• Auto-start with Windows - Launch AirMarshal when you log in (default: on)
• Start minimized - Start in the system tray instead of showing the window (default: on)
• Notifications - Show desktop notifications for pending actions (default: off)

Daily Digest

• Enabled - Toggle automatic daily digest generation
• Digest Time - What hour to generate the digest (default: 5 PM)

Privacy

• Include email details in logs - When OFF, email subjects and senders are redacted in log files (default: off)

Accounts

Connect your Microsoft account and configure your AI provider (Claude API key or built-in AirMarshal AI for beta users).

Settings are saved automatically and persist across app restarts.

Themes

AirMarshal supports light, dark, and system-matched themes to suit your preferences.

Available Themes

Changing Themes

1. Go to Settings
2. Find the Appearance section
3. Select your preferred theme
4. Click Save

The theme change takes effect immediately - no restart needed.

Mailbox Folder Scanning

AirMarshal can scan your actual mailbox folders to suggest real folder names instead of generic ones.

Why Scan Folders?

When the AI suggests moving an email, it's helpful if it knows your actual folder structure. Instead of suggesting "Newsletters" (which might not exist), it can suggest "Marketing/Newsletters" (a folder you actually have).

How to Scan Folders

1. Connect your Microsoft account first
2. Go to Settings
3. Find Mailbox Folder Scanning
4. Click Scan Folders
5. Wait for the scan to complete

What Gets Scanned

• All your mail folders and subfolders
• Folder hierarchy (parent/child relationships)
• Folder names only - no emails are read