Cloud AI Processing (Business Feature)

Use Google’s Gemini AI for faster email categorization with your own API key.

Overview

InboxZebra supports two AI options:

  • Local (Ollama) - Free, private, runs on your Mac
  • Cloud (Gemini) - Faster, requires Business subscription and Google API key

Cloud processing benefits:

  • No local model download (saves disk space)
  • Faster categorization (no model loading)
  • Works on lower-spec Macs

You bring your own API key - You pay Google directly (~$0.0001 per email).

Requirements

  • Business subscription (or active trial)
  • Google AI Studio API key (free tier available)
  • Internet connection during processing

Getting Your API Key

Step 1: Get Free Gemini API Key

  1. Visit: https://aistudio.google.com/app/apikey
  2. Sign in with Google account
  3. Click “Create API key”
  4. Copy the key (looks like: AIzaSy...)

Google’s free tier rate limits:

  • 5 requests per minute (RPM)
  • 250K tokens per minute (TPM)
  • 20 requests per day (RPD)

⚠️ Privacy Warning: Google’s free tier may use your data for training. For better privacy, we recommend:

  • Get a paid API key (Tier 1: 1000+ RPM, 1M TPM, 10K RPD)
  • Or use Local (Ollama) for 100% privacy

Pricing:

  • Paid tier: ~$0.0001 per email (very cheap)

Step 2: Keep Your Key Safe

  • Don’t share it publicly
  • InboxZebra encrypts it in your Mac’s Keychain
  • You can delete it anytime in Settings

Setting Up Cloud AI

Step 1: Open Settings

  1. Go to Settings (Cmd+,)
  2. Click LLM tab

Step 2: Select Gemini

  1. Under “LLM Provider”, click Cloud (Gemini)
  2. If you’re on Free/Pro tier, you’ll see upgrade prompt
  3. Business users see API key field

Step 3: Enter API Key

  1. Paste your API key from Google AI Studio
  2. Click “Validate & Save”
  3. Wait for validation (2-3 seconds)
  4. See ✓ “API Key is valid!”

That’s it! InboxZebra now uses Gemini for categorization.

Automatic Speed Optimization

InboxZebra automatically optimizes processing speed using adaptive parallel processing.

How It Works

  1. Starts Fast: Begins with high concurrency (20 parallel requests)
  2. Learns Limits: Backs off if rate limited by Google
  3. Self-Optimizes: Gradually increases speed on sustained success
  4. Remembers: Saves optimal speed for future sessions

Performance

No configuration required - InboxZebra learns your API key’s optimal speed:

  • Free tier (5 RPM): ~2x faster (learns 2 concurrent requests)
  • Paid tier (1000 RPM): ~10-15x faster (learns 15-20 concurrent requests)

What You’ll See

During processing, the status shows current concurrency:

Categorized 47/100 (⚡12 concurrent)

This number adjusts automatically based on your API tier and rate limits.

Managing Your Usage

Setting Monthly Quota

Protect yourself from surprise bills by setting a monthly limit:

  1. In LLM Settings, find “Monthly API Call Quota”
  2. Drag slider to set your limit (default: 10,000 calls/month)
  3. See estimated cost (e.g., ”≈ $1.00/month”)

Example quotas:

  • 1,000 calls = ~$0.10/month (light use)
  • 10,000 calls = ~$1.00/month (default)
  • 50,000 calls = ~$5.00/month (heavy use)

Viewing Usage

See your current usage:

  • This Month: “342 / 10,000”
  • Progress bar (green/orange/red)
  • Resets: Shows next reset date
  • Remaining: Shows calls left

What Happens at Quota Limit

When you reach your self-imposed monthly limit:

  1. Modal appears mid-processing
  2. Shows: Current usage, limit, reset date
  3. Choose an action:
    • Continue with Ollama - Switches to local AI, keeps processing
    • Open Settings - Adjust your quota
    • Cancel - Stop processing

No data loss - Emails already processed are saved.

Switching Between Local & Cloud

To Switch to Cloud (Gemini)

  1. Settings → LLM tab
  2. Select Cloud (Gemini)
  3. Enter API key if needed
  4. Click “Process Emails”

To Switch to Local (Ollama)

  1. Settings → LLM tab
  2. Select Local (Ollama)
  3. Make sure Ollama is running
  4. Click “Process Emails”

Switching is instant - Takes effect on next processing run.

Cost Management

How Billing Works

  • You pay Google directly via your Google Cloud account
  • InboxZebra never charges for API usage
  • Gemini 2.5 Flash pricing: ~$0.0001 per email categorization
  • Google bills monthly based on usage

Checking Google Costs

  1. Visit: https://console.cloud.google.com/billing
  2. View your actual Gemini usage
  3. See exact costs

Staying in Budget

InboxZebra helps you:

  • Set monthly quota (your safety limit)
  • Track usage in real-time
  • Show cost estimates
  • Warn before exceeding quota
  • Fall back to Ollama if needed

Troubleshooting

”Invalid API Key”

Check:

  • Copied entire key (no spaces)
  • Using Gemini API key (not other Google API)
  • Key not expired or disabled

Solution: Generate new key at https://aistudio.google.com/app/apikey

”Quota Exceeded”

Two types of limits:

Your InboxZebra limit:

  • Adjust slider in Settings → LLM
  • Or switch to Ollama temporarily

Google’s API limit:

  • Free tier: 5 RPM, 20 requests/day
  • Paid tier (Tier 1): 1000+ RPM, 10K requests/day
  • Wait until next day (free tier)
  • Or upgrade to paid tier at https://console.cloud.google.com

”API Key Validation Failed”

Causes:

  • No internet connection
  • Google servers temporarily down
  • API key revoked

Solution:

  • Check internet
  • Try again in a minute
  • Verify key at Google AI Studio

Slow Processing

Cloud processing is usually faster than local, but if slow:

  • Check your internet speed
  • Google API might be rate-limiting
  • Try processing fewer emails at once

Privacy & Security

What’s Sent to Google

InboxZebra sends to Gemini:

  • Email subject
  • Email sender
  • Email body snippet (first ~500 words)
  • Your categories and descriptions

Not sent:

  • OAuth tokens
  • Password
  • Full email archives
  • Other account data

Your API Key Security

  • Encrypted in macOS Keychain (AES-256-GCM)
  • Never logged
  • Never sent anywhere except Google
  • You can delete anytime

Data Privacy

Important Privacy Note:

  • Free tier: Google may use your data for training their models
  • Paid tier: Your data is not used for training
  • Google processes your emails to provide categorization
  • Check Google’s AI Studio terms: https://ai.google.dev/terms

For maximum privacy:

  • Use Local (Ollama) processing (100% private)
  • Or upgrade to a paid Google API key (Tier 1: $0.0001/email)

Common Questions

Q: How much does Cloud AI cost? A: ~$0.0001 per email. For 10,000 emails/month = ~$1.00. You pay Google directly.

Q: Is my email data private? A: Free tier: Google may use your data for training. Paid tier: Data not used for training. For 100% privacy, use Local (Ollama).

Q: Can I use both Local and Cloud? A: Yes! Switch anytime in Settings → LLM. Takes effect immediately.

Q: What if I exceed my quota? A: InboxZebra prompts you to either switch to Ollama or adjust your quota.

Q: Do I need Business tier? A: Yes, Cloud AI is a Business feature. Free/Pro users can use Local (Ollama).

Q: What if Google changes pricing? A: You control your quota in InboxZebra. Set a low limit to protect your budget.

Q: Can I use other cloud AI (ChatGPT, Claude)? A: Not yet, but we’re considering it! Currently Gemini only.

Next Steps