Getting Started with AirMarshal
AirMarshal is an AI-powered email assistant that helps you organize your inbox automatically. It runs quietly in your system tray, monitoring your emails and taking action based on rules you define in plain English.
How It Works
- Connect your Microsoft account - AirMarshal uses Microsoft Graph API to securely access your Outlook/Exchange inbox. Your mailbox folders are automatically scanned so the AI knows your folder structure.
- Define your rules - Write rules in plain English like "Move newsletters to the Newsletters folder" or "Archive emails from automated systems."
- Let AI do the work - The AI analyzes each email and decides which rules apply, taking action automatically.
- Review and refine - Check the action history, correct any mistakes, and AirMarshal learns from your feedback.
Safe by Default
AirMarshal starts in "Dry Run" mode, which shows you what it would do without actually moving or modifying emails. This lets you verify its behavior before enabling real actions.
Quick Start
- Download and install AirMarshal from the Dashboard
- Launch the app and follow the interactive onboarding tour
- Sign in with your Microsoft account (no Azure setup needed)
- Create your first rule on the Rules page
- Watch AirMarshal process your inbox in Dry Run mode
That's it! You'll need a Claude API key to enable AI processing - see Installation for details.
Continue to Installation for detailed setup instructions.
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
- Download the installer from the Dashboard
- Run
AirMarshal-Setup-x.x.x.exe
- Follow the installation wizard
- AirMarshal will launch automatically and appear in your system tray
Windows SmartScreen
You may see a SmartScreen warning because AirMarshal is new software. Click "More info" then "Run anyway" to proceed. We're working on code signing to eliminate this warning.
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:
- Go to console.anthropic.com
- Create an account or sign in
- Navigate to API Keys and create a new key
- Copy the key (you won't be able to see it again)
- In AirMarshal Settings, select "Claude API Key" as your AI provider
- Paste your key and save
API Costs
When using your own API key, you pay per API call. Typical usage (processing ~100 emails/day) costs approximately $1-5/month depending on email complexity and rule count.
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
- Go to Settings and click "Connect" under Microsoft Graph
- A device code will appear prominently in the Settings page - click the code to copy it to your clipboard
- Your browser should open automatically. If not, click the "click here to open" link below the code
- Paste the code on the Microsoft sign-in page
- Sign in and grant the requested permissions
No Azure Setup Needed
AirMarshal uses its own Azure app registration. Just sign in with your Microsoft account - no configuration required.
Permissions Explained
| Permission |
Why It's Needed |
| Read and write mail |
To read emails and move them between folders |
| Read mail folders |
To list your folders for organization rules |
| Send mail |
For future auto-reply features (not used yet) |
Step 2: Configure AI Provider
AirMarshal needs an AI provider to analyze your emails. You have two options:
Claude API Key
- Go to the Settings page
- Under AI Provider, select "Claude API Key"
- Paste your API key from console.anthropic.com
- Click Save
Claude OAuth (Experimental)
If you have a Claude Pro or Max subscription, you can use OAuth to authenticate without an API key:
- Under AI Provider, select "Claude OAuth"
- 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
Move newsletters and promotional emails to the Newsletters folder
Handles subscription emails, marketing, and promotions
Archive emails from no-reply addresses that are older than 1 day
Cleans up automated notifications
Keep emails from my manager Sarah in the inbox, mark them as important
Prioritizes emails from specific people
Move GitHub notifications to the Dev folder unless they mention my username
Filters noise while keeping relevant alerts
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
| Action |
Description |
| Move to folder |
Moves the email to a specified folder |
| Archive |
Moves to Archive folder |
| Delete |
Moves to Deleted Items |
| Mark as read |
Marks the email as read |
| Flag/Unflag |
Adds or removes a flag |
| Mark important |
Sets high importance |
Creating Folders
If a rule references a folder that doesn't exist, AirMarshal will offer to create it for you.
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
- Go to the History page
- Look for entries marked "Dry Run"
- Review what action AirMarshal wanted to take
- If correct, click Accept to learn the pattern, or Accept & Execute to also apply the action immediately
- If incorrect, click Teach to correct it and create the right pattern
Disabling Dry Run
Once you're confident in your rules:
- Go to Settings
- Toggle "Dry Run Mode" off
- Click Save
Recommendation
Run in Dry Run mode for at least a few days before enabling real actions. This helps you catch edge cases and refine your rules.
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:
| Tier |
Color |
Description |
| Tier 1 |
Green |
Learned patterns - specific rules you've approved or taught |
| Tier 2 |
Purple |
AI rules - rules from your AIRMARSHAL.md file analyzed by the AI |
| Needs Input |
Amber |
Uncertain or pending actions waiting for your decision |
| AI Decision |
Blue |
Actions taken by AI analysis (not from a learned pattern) |
Quick Accept
For AI suggestions you agree with:
- Go to the History page
- Find an amber "Would Move" or "Would Flag" entry
- Click the Accept button
- 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:
- Click Accept & Edit on any history item
- Review the suggested action and folder
- 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
- 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
Faster Processing
Tier 1 learned patterns are processed locally without calling the AI. The more patterns you approve, the faster emails are processed.
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:
- Go to the Rules page
- Find the rule you want to edit
- Click the Edit (pencil) button
- Modify the rule in the modal dialog
- 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
Multi-Action Support
You can combine multiple actions in one rule. For example: "Move to Newsletters AND mark as read AND flag". Note that Delete and Move are mutually exclusive.
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:
- Find the rule on the Rules page
- Click the Delete (trash) button
- Confirm the deletion
Retroactive Rule Application
Apply rules to emails that are already in your inbox:
- Find the rule you want to apply retroactively
- Click the Apply Retroactively button
- AirMarshal searches your inbox within the Historical Lookback period (configured in Settings) and shows a preview of matching emails
- Review the list and click Apply to All
- The rule action is executed on all matching emails
Retroactive Actions Are Permanent
Unlike Dry Run mode, retroactive rule application immediately moves or modifies the selected emails. Review the preview carefully before applying.
Compound Conditions
Create more specific patterns using AND conditions:
| Primary |
+ |
Secondary |
Example |
| Domain |
AND |
Subject contains |
amazon.com + "order confirmation" |
| Sender |
AND |
Subject contains |
[email protected] + "urgent" |
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:
| Color |
Meaning |
Example |
| Amber |
Needs Input - uncertain or pending actions |
"Needs Input" badge, awaiting your decision |
| Green |
Tier 1 learned pattern |
"Moved" with "Learned" badge |
| Purple |
Tier 2 AI rule |
"Moved" from AIRMARSHAL.md rule |
| Blue |
AI Decision - action taken by AI analysis |
"Moved" with "AI Decision" badge |
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
"Needs Input" Badge
When the AI is uncertain about an email (low confidence), it appears with an amber "Needs Input" badge instead of taking action. Use Accept & Execute to approve it, or Teach to correct it.
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
Beta Pricing
AirMarshal is free during the beta period. You provide your own Claude API key for AI processing (typical cost: $1-5/month). We'll announce pricing before launching publicly.
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):
- Open AirMarshal and go to Settings
- Scroll to the Beta Feedback section
- Optionally add notes describing the issue
- Click "Send Logs"
From the System Tray:
- Right-click the AirMarshal icon in your system tray
- 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.
How to Enable Privacy Mode
Go to Settings → Privacy → Enable "Sanitize logs before upload". This is enabled by default for new installations.
Known Issues
Current known issues and limitations in the beta version.
Current Limitations
| Issue |
Status |
| Windows SmartScreen warning on install |
Working on code signing |
| Calendar features not available |
Coming in future update |
| macOS not supported |
Planned for post-beta |
| Gmail not supported |
Microsoft accounts only (for now) |
| Shared mailboxes not supported |
Personal accounts only |
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:
- Use the Feedback page with type "Bug Report"
- Include steps to reproduce if possible
- Send logs from the app for technical issues
Frequently Asked Questions
Common questions about AirMarshal.
Is my email data sent to a third party?
Yes, email content is sent to Anthropic's Claude AI for analysis. Your emails are processed in real-time and not stored by the AI provider. AirMarshal uses your own Claude API key or OAuth credentials to authenticate requests.
How much does it cost?
Free during the beta! AirMarshal itself is free. You'll need a Claude API key from Anthropic for AI processing. Typical usage processing ~100 emails/day costs approximately $1-5/month depending on email complexity and rule count.
Can AirMarshal read my attachments?
Currently, AirMarshal only reads email text and metadata (sender, subject, date). Attachment support may come in a future version.
Does it work with Gmail?
Currently, AirMarshal only supports Microsoft 365 and Outlook.com accounts via Microsoft Graph API. Gmail support is being considered for the future.
What happens if AirMarshal crashes?
Your emails are safe in Outlook. AirMarshal doesn't modify emails on Microsoft's servers until you've approved the action (or disabled Dry Run). You can always access your email through Outlook directly.
Can I use my work email?
Yes, if your organization allows third-party apps. Some organizations require admin consent. Check with your IT department if you encounter permission errors.
How do I uninstall?
Use Windows Settings > Apps > AirMarshal > Uninstall. Your rules and settings are stored locally and will be removed.
Troubleshooting
Solutions to common problems.
Microsoft sign-in fails
Try:
- Clear your browser cache and try again
- Use a different browser for the sign-in popup
- Check if your organization blocks third-party apps
- Ensure you're signing in with the correct account
AI shows "Not Connected"
Try:
- Ensure your internet connection is working
- If using built-in AI: wait a moment and try again (service may be busy)
- If using your own API key: verify the key is correct in Settings
- If using your own API key: check your account has available credits
Emails aren't being processed
Check:
- Processing status shows "Running" not "Paused"
- You have at least one rule defined
- Both Microsoft and AI connections are active
- Check History for any error messages
Actions aren't appearing in History
Try:
- Wait for the next polling interval (default: 60 seconds)
- Ensure you have new emails to process
- Check the Dashboard for error indicators
- Restart AirMarshal from the system tray
App won't start or crashes
Try:
- Check Windows Event Viewer for error details
- Try running as Administrator once
- Reinstall the application
- Send logs (if accessible) and contact [email protected]
Email appears in inbox after being moved
Sometimes you may notice an email still appears in your inbox even after AirMarshal has moved it to another folder. This is typically not an AirMarshal issue — it's Exchange/Outlook synchronization lag.
What's happening:
- AirMarshal successfully moved the email via Microsoft Graph API
- Exchange shows a "ghost" reference in the inbox (may appear as a Post item with a yellow dot icon)
- The ghost disappears when new mail arrives or Exchange reconciles its state
How to verify:
- Check the destination folder — if the email is there, the move worked
- Try clicking on the "ghost" email — it may show an error or disappear
- Send yourself a test email — the sync often triggers and clears ghosts
Note: This is a known Exchange behavior and not unique to AirMarshal. The email is safely in its destination folder even if Outlook temporarily shows a stale reference.
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:
- Go to Settings
- Find the Daily Digest section
- Set your preferred digest time
- 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.
Dry Run Actions Excluded
The digest only includes actual actions taken, not dry run suggestions. Switch off Dry Run mode to see real activity in your digest.
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
- Go to Settings
- Find the Backup & Restore section
- Choose whether to include History and API Keys
- Click Create Backup
- Choose where to save the
.ambu file
Restoring from Backup
- Double-click any
.ambu file to open it in AirMarshal, or use Settings > Restore
- AirMarshal shows a preview of what's in the backup
- Select which sections to restore (settings, rules, patterns, history, API keys)
- 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.
Profile Deletion Safety
When you delete a profile, AirMarshal prompts you to create a backup first, so you don't accidentally lose your data.
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
| Setting |
Description |
Default |
| Poll Interval |
How often AirMarshal checks for new emails |
30 seconds |
| Confidence Threshold |
Minimum AI confidence to take action (lower = more aggressive) |
80% |
| Dry Run Mode |
When ON, shows what would happen without executing actions |
ON (safe) |
| Historical Lookback |
How far back to look when processing emails (in days) |
7 days |
| API Usage Mode |
Balance between cost (efficient) and accuracy (learning) |
Balanced |
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
| Theme |
Description |
| System |
Automatically matches your Windows theme preference |
| Light |
Light background with dark text |
| Dark |
Dark background with light text (default) |
Changing Themes
- Go to Settings
- Find the Appearance section
- Select your preferred theme
- 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
- Connect your Microsoft account first
- Go to Settings
- Find Mailbox Folder Scanning
- Click Scan Folders
- 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
Refresh Periodically
If you create new folders in Outlook, run the scan again to update AirMarshal's knowledge of your folder structure.