Build a Free AI Email Organizer

Use the Gemini API and Google Apps Script to sort, summarize, and manage your inbox automatically — no coding required.

What You'll Build

  • An AI bot that lives inside your Google account
  • Sorts emails into categories you define
  • Sends you a daily digest
  • Can draft replies and auto-archive low-priority mail
  • Runs on autopilot every day

The Gemini API costs pennies per day for this kind of usage — typically under $1/month. Paid email organizer services that do the same thing charge $20/month or more.

Before You Start

  • A Gmail account (personal or Google Workspace)
  • About 15 minutes
  • Willingness to copy and paste
  • Access to any AI chatbot (Claude, Gemini, ChatGPT, etc.)

Step-by-Step Walkthrough

Step 1: Open Google Apps Script

  1. Go to script.google.com and sign in with the Gmail account you want to organize.
  2. Click New project and name it Email Organizer.

Make sure you're signed into the right Google account if you have multiple.

Step 2: Get a Gemini API Key

  1. Go to aistudio.google.com/apikey.
  2. Click Create API key and copy it.
  3. In Apps Script, go to Project Settings > Script Properties > add a property named GEMINI_API_KEY (exact spelling, no spaces, case-sensitive) with your key as the value.

Keep your API key out of chat windows. Never paste the key itself into the AI that writes your script — only tell it the property name. If you ever paste the key into any chat, document, or screenshot, treat it as leaked and rotate it at aistudio.google.com/apikey.

Step 3: Decide Free Tier vs. Paid (and enable billing if you need it)

Gemini has a generous free tier. Most people never pay a cent. But if you have a 10k+ backlog or want very frequent runs, you'll hit the free-tier rate limits and the script will start failing with 429 errors. Here's how to tell which camp you're in, and what to do if you need the paid tier.

You're almost certainly fine on the free tier if:

  • Your backlog is under ~5,000 emails.
  • The bot runs once an hour or less often.
  • You're just maintaining a normal inbox going forward.

You'll want to enable paid billing if:

  • You're running Backlog Blitz mode on a 10k+ inbox — you'll want the bot processing nonstop for a few days.
  • You want runs every 15 minutes.
  • You're seeing repeated 429 RESOURCE_EXHAUSTED errors in the Apps Script execution log.

Realistic cost: Even in Backlog Blitz mode cleaning 20,000 emails, expect <$2 total. Steady-state after your inbox is tidy: usually under $1/month. Compare that to commercial inbox-sorting subscriptions at $20+/month.

How to enable billing (only if you need it):

  1. Go to console.cloud.google.com/billing.
  2. Click Create billing account (or use an existing one) and add a payment method.
  3. Go to the Generative Language API page and click Enable on the project that owns your Gemini API key.
  4. Link your billing account to that project: Billing > Link a billing account.
  5. Set a budget alert so you can't accidentally overspend: Billing > Budgets & alerts > Create budget. A $5 monthly cap with email alerts at 50% and 90% is a sensible default.

Start free, upgrade only if you hit limits. You can always enable billing later — the same API key keeps working. If you're unsure, skip this step and come back only if the execution log shows rate-limit errors.

Step 4: Generate Your Custom Script

  1. Complete the questionnaire below.
  2. Copy the generated prompt.
  3. Paste it into your AI of choice and ask it to generate the Apps Script code.
  4. Copy the code the AI gives you back.

Step 5: Paste the Code

  1. Back in the Apps Script editor, select all the default code and delete it.
  2. Paste the AI-generated code.
  3. Click the save icon.

Step 6: Authorize & Test

  1. Click Run on the main function.
  2. Click Review Permissions, choose your account, and click Allow.
  3. Check your inbox to confirm it worked.

Google will warn you the app isn't verified. This is normal for personal scripts — click Advanced then Go to Email Organizer (unsafe) to proceed.

Step 7: Set Up the Daily Trigger

  1. In the Apps Script sidebar, click Triggers (clock icon), then Add Trigger.
  2. Set it to run the main function on a time-driven timer at your preferred interval.
  3. If you enabled a digest, add a second trigger for the digest function.

You can always come back and change the schedule or re-run the questionnaire to update your prompt.

Customize Your Email Organizer

Answer these questions to generate a personalized AI prompt for your email organizer.

Start Here: Your Inbox Situation

Pick the two that best describe you. Everything below auto-tunes from these two choices — most people never need to touch the Advanced panel.

How big is your current backlog?
How aggressive should the bot be?
Email Categories
Quick presets — click to populate a starter set
Which categories do you want?
Create a catch-all ‘Other’ label for uncategorized email?
Actions & Automation
Low-priority emails (newsletters, promotions)
Draft reply suggestions for which categories?
Reply tone
Daily Digest

A daily email that tells you what the bot did. Strongly recommended so you can catch issues early.

Send a daily digest?
Schedule & Preferences
Run frequency
Which days?
Advanced controls (sliders & tuning)

Defaults auto-tune from your Inbox Situation above. Most people never need to touch these. Open only if the bot is too slow, too aggressive, too timid, or hitting quota limits.

Frequently Asked Questions

I got a scary Google permissions warning

When you authorize a personal Apps Script project, Google shows an "unverified app" screen. This is standard for any script you write yourself — it simply means Google hasn't reviewed it (and doesn't need to for personal use). Click Advanced, then Go to Email Organizer (unsafe). The "unsafe" label is misleading; the script only accesses your own account with the permissions you grant.

The script ran but nothing happened

First, check the Execution log in Apps Script (View > Execution log) for error messages. The most common cause is a label spelling mismatch — make sure the label names in your script match real Gmail labels exactly, including capitalization. Also confirm the script is looking at recent emails and not an empty time window.

I want to change my categories later

Re-run the questionnaire on this page with your updated preferences, copy the new prompt, paste it into your AI chatbot to generate fresh code, and replace the old code in Apps Script. Your triggers and API key stay the same.

How much will this cost?

The Gemini API offers a generous free tier, and even beyond that, processing a typical inbox costs well under $1/month. You can monitor your usage at Google AI Studio. Compare that to commercial email organizer subscriptions that charge $20/month or more for similar features.

I'm getting a 401 UNAUTHENTICATED error

Nine times out of ten the Script Property name doesn't match what the code reads. Check three things: (1) the property is named exactly GEMINI_API_KEY — no trailing spaces, no quotes around the value, case-sensitive; (2) the key itself is valid (test it with curl "https://generativelanguage.googleapis.com/v1beta/models?key=YOUR_KEY" in a terminal); (3) the Generative Language API is enabled on the GCP project that owns the key. If you regenerated the key, you have to paste the new value into Script Properties — Apps Script does not auto-update.

I renamed my labels and now nothing sorts

The script's search query excludes already-processed threads by label name. If you rename the processed label in Gmail without updating the constant at the top of the script, the query breaks silently — the script keeps "finding" zero new threads. Fix: open the script, find the label-name constant (usually PROCESSED_LABEL or similar), update it to match, and save.

Gmail quota exceeded / the script keeps timing out

Apps Script has daily quotas (~20k Gmail reads, ~10k modifications) and each run is capped at 6 minutes. If you're hitting limits: lower BATCH_SIZE (try 15), lengthen your trigger interval (every 30–60 min instead of every 15), and add quiet hours so the script skips overnight runs. The digest run should be on its own trigger, not chained onto the sort run.

My old trigger is still firing the old function

If you regenerated the script and renamed main() to something else, the old trigger still points at the old function name and will throw "function not found" errors. Go to Triggers in the left sidebar of Apps Script, delete stale triggers, and create a new one pointing at the current function.

Can I use this with Outlook or Yahoo?

This guide is built specifically for Gmail and Google Apps Script. However, the prompt-based approach works elsewhere: you can take the generated prompt, ask an AI to adapt the code for Outlook (using Office Scripts or Power Automate) or another email provider. The logic and categories transfer — only the platform integration code changes.