Settings & Configuration

Learn how to customize InboxZebra for your workflow.

Opening Settings

Keyboard shortcut: Cmd+, (Command + Comma)
Or: Click “InboxZebra” menu → “Preferences”

Settings are organized into tabs:

  • Accounts
  • Categories
  • LLM (AI settings)
  • Background Sync
  • Data
  • Backups
  • Subscription
  • Security
  • Diagnostics

Accounts Tab

View Connected Accounts

See all your connected email accounts:

  • Email address
  • Provider (Office 365 or Gmail)
  • Display name
  • Connection status

Account Actions

Click an account to expand it and access:

  • Custom Instructions (Pro) - Account-specific context
  • Shared Mailbox Settings (Business) - For support@, sales@, etc.
  • Remove Account - Disconnect this account

Per-Account Custom Instructions (Pro)

Give InboxZebra context about each account:

Example for work:

Company: TechStartup (SaaS platform). Role: Founder/CEO.  
Key areas: fundraising, B2B partnerships, product development, hiring.
Clients: fintech and healthcare companies.

Why this helps:

  • AI understands your company/role and industry
  • Better categorization of domain-specific emails
  • Industry jargon recognized correctly
  • Distinguishes client emails from investor emails

Free tier: Cannot add custom instructions
Pro tier: Up to 500 characters per account

Categories Tab

Manage Your Categories

See all categories (default + custom):

  • Edit category descriptions
  • Change category colors
  • Delete custom categories
  • Add new categories

Category Limits

Free: 3 custom categories (+ 9 defaults = 12 total)
Pro: Unlimited custom categories

See: Categories Guide for details

Task Behaviors

Task-related behaviors are handled inline rather than through a dedicated settings tab.

Reply Detection

When a reply arrives for a task in the Waiting stage, InboxZebra prompts you to decide what to do. See Tasks & Action Tracking for details.

Dismiss Learning

When you delete an AI-detected task, InboxZebra asks whether to learn from the dismissal. Choose “Delete & Learn” to add a negative example (so similar emails are skipped in future), or “Delete Only” to remove the task without affecting AI behavior.

Task Completion

When completing a task, the linked email is archived by default. You can override this per-task when marking complete.

See: Tasks & Action Tracking for full guide

LLM Tab (AI Settings)

Choose Your AI Provider

Local (Ollama) - Default, free, private Cloud (Gemini) - Business feature, faster, requires API key

Local AI (Ollama) Configuration

Ollama Model:

  • Choose which AI model to use
  • Default: qwen2.5:7b (recommended)
  • Options: phi3:mini (faster), mistral:7b, gemma2:9b

Ollama Base URL:

  • Usually: http://localhost:11434
  • Change if running Ollama on different port

Test Connection:

  • Click “Check Ollama Status”
  • Verifies Ollama is running and accessible

Cloud AI (Gemini) Configuration (Business)

API Key:

Monthly Quota:

  • Set your spending limit (default: 10,000 calls)
  • Cost estimate shown (~$1/month for 10k emails)
  • Protects from surprise bills

Usage Display:

  • See current month usage
  • Progress bar (green/orange/red)
  • Reset date and remaining quota

See: Cloud AI Processing for full setup guide

Global Custom Rules (Pro)

Add general categorization rules that apply to all accounts:

Examples:

  • “Emails from Upwork or Fiverr should go to Freelance Platform”
  • “Emails mentioning ‘term sheet’ or ‘investment’ should go to Investor Relations”
  • “Stripe payment notifications go to Financial, not Notifications”
  • “Client emails with ‘proposal’ or ‘contract’ go to Client Projects”

How to add:

  1. Type rule in text field
  2. Click “Add”
  3. Rule applies to all future categorizations

Free tier: Cannot add global custom rules
Pro tier: Unlimited rules

Email Fetch Settings

Max Emails to Fetch:

  • Default: 500
  • Increase for large date ranges
  • Recommended for bulk processing: 2,000-10,000

Data Tab

Export Data

Save a backup of your settings:

  1. Click “Export Data”
  2. Choose save location
  3. Saves JSON file with:
    • Categories
    • Learning examples
    • Account metadata (no passwords)
    • Custom labels
    • Preferred senders

Does NOT include:

  • OAuth tokens (must re-authenticate)
  • Actual email content

Use for:

  • Backing up before major changes
  • Transferring settings to new Mac
  • Sharing category setup with team

Import Data

Restore from backup:

  1. Click “Import Data”
  2. Select JSON file
  3. Categories and settings restore
  4. Must reconnect accounts (OAuth)

Clear Data

Reset InboxZebra:

  • Clear processed email IDs
  • Clear email cache
  • Reset categories to defaults
  • Remove all accounts

Warning: This cannot be undone!

Subscription Tab

View Your Plan

See current subscription status:

  • Tier (Free, Pro, or Business)
  • Trial days remaining (if in trial)
  • Usage stats (Free tier)

Activate License

After purchasing:

  1. Enter license key from email
  2. Enter your email address
  3. Click “Activate License”
  4. Features unlock immediately

Manage License

Deactivate license:

  • Removes license from this device
  • Use on different Mac
  • Returns to Free tier

View usage:

  • See emails processed this month (Free tier)
  • Progress bar shows quota

Manage Subscription

Click “Manage Subscription” to open the Paddle customer portal, where you can view billing history, download invoices, update your payment method, or cancel your subscription. You’ll be asked to verify your email via a secure magic link before accessing the portal.

See: Receipts & Invoices for step-by-step instructions.

See: Subscription Guide for details

Advanced Settings

Custom LLM Endpoints (Coming Soon)

This feature is planned for a future release.

Use your own AI:

  1. Set up Ollama on another server
  2. Or use OpenAI, Claude, or custom API
  3. Enter API endpoint URL
  4. Enter API key (if needed)
  5. Test connection

Why you’d want this:

  • Running InboxZebra on Mac with <8GB RAM
  • Want to use different AI model
  • Need faster processing (powerful server)
  • Company policy requires specific AI

Background Sync

InboxZebra syncs your accounts silently in the background after initial onboarding is complete. No manual intervention is required.

Sync Types

Incremental Sync (default: every 5 minutes)

  • Fetches only new and recently changed emails
  • Lightweight and fast
  • Keeps your inbox up to date in near real-time

Full Reconciliation (default: every hour)

  • Compares local state against the server
  • Catches any emails missed by incremental sync
  • Repairs inconsistencies (labels, read status, deletions)

Deep Sync (default: every 24 hours)

  • Performs a comprehensive scan of all synced folders
  • Reconciles category assignments and task state
  • Ensures long-term accuracy across all accounts

All sync intervals are configurable in Settings.

Adaptive Intervals

Sync intervals adjust automatically based on your system resources. When CPU or memory usage is high, InboxZebra extends the interval between syncs to avoid impacting performance. Normal intervals resume once system load decreases.

Sync Status

The status bar shows sync progress, including which account is currently syncing and the type of sync in progress. If a sync encounters errors, InboxZebra retries automatically with exponential backoff to avoid overloading the mail server.

Privacy Settings

InboxZebra is privacy-first by default:

What’s stored:

  • Categories, learning examples, settings (UserDefaults)
  • Email metadata and encrypted bodies (Core Data)
  • OAuth tokens (Keychain, encrypted)

What’s NOT stored:

  • Email content sent to cloud
  • AI processing done on external servers
  • Analytics or tracking data

All AI processing happens on your Mac!

Diagnostic Logging

InboxZebra includes built-in logging to help diagnose issues with sync, categorization, and account connectivity.

Detailed logging toggle: Enable verbose logging in Settings > Diagnostics to capture additional detail for authentication flows, API calls, and LLM responses. Keep this off during normal use to avoid unnecessary disk usage, and enable it temporarily when troubleshooting a specific issue.

Security Tab

Phishing Detection

Enabled by default. Analyzes emails during sync to identify potential phishing attempts.

What it does: Scans email headers and body content for known phishing indicators and assigns a risk level: none, low, medium, or high.

What it checks:

  • Display name spoofing (e.g., “Your Bank” from a non-bank domain)
  • Authentication failures (SPF, DKIM, DMARC)
  • Homoglyph domains (e.g., paypa1.com instead of paypal.com)
  • Suspicious links (mismatched display text and URL)
  • Urgency language and pressure tactics
  • Credential harvesting requests (login links, password resets from unexpected senders)
  • Brand impersonation patterns

Privacy: All analysis runs locally on your Mac. No email data is sent to external services for phishing detection.

When to disable: If you receive persistent false positives on legitimate senders (e.g., marketing platforms using brand display names), toggle off in Settings > Security. This is rare — most legitimate senders pass authentication checks.

Troubleshooting Settings

Settings Not Saving

Symptom: Changes don’t persist after restart

Solution:

  • Check you clicked “Save” (where applicable)
  • Restart InboxZebra
  • Check file permissions on UserDefaults

Ollama Not Responding

Check:

  1. Click “Check Ollama Status” in LLM tab
  2. If “Not responding”:
    • Open Terminal
    • Run: ollama serve
    • Or restart Ollama

Can’t Access Settings

If Settings won’t open:

  • Try keyboard shortcut: Cmd+,
  • Restart InboxZebra
  • Check logs for errors

For New Users

  • Model: qwen2.5:7b (best balance)
  • Max Emails: 500 (start small)
  • Categories: Use defaults first
  • Custom Rules: Start without, add as needed

For Power Users (Pro)

  • Model: qwen2.5:7b or gemma2:9b
  • Max Emails: 5,000-10,000
  • Custom Rules: 5-10 specific rules
  • Per-Account Instructions: Detailed context
  • Custom Labels: 10-20 for projects/clients

For Teams (Business)

  • Model: Custom LLM endpoint (company AI)
  • Shared Mailboxes: Multiple team inboxes
  • Global Rules: Company-wide categorization
  • Custom Analytics: Track team metrics

Resetting Settings

Soft Reset

In Settings → Data:

  • Clear processed IDs (forces re-categorization)
  • Clear email cache
  • Keeps categories and learning

Hard Reset

Complete reset:

defaults delete com.inboxzebra.app

Warning: Deletes everything, including categories, learning, and accounts!

Next Steps