🍎 Mac only, for now

The Inbox
Intervention

Take back your inbox. No apps. No subscriptions.
Just a few scripts that do exactly what you tell them.

Let's do this →

What you'll be able to do

Pick one thing or do all three. Either way, you'll end up with an inbox that finally works for you.

🔍

See who's cluttering your inbox

Scan your inbox and get a ranked list of every sender — then choose who to unsubscribe from, right then and there.

🗓️

Hold emails until you're ready

Pick a time each day. Newsletters, Substacks, whatever. They wait in a folder and arrive all at once.

📁

Auto-sort straight to folders

Retailers, promos, specific senders. Routed straight to a folder and out of your inbox.

Setup Guide

Do this once. Takes about 20 minutes. Check things off as you go. Your progress saves automatically.

0 of 6 steps complete

1

Open Terminal

▾

Terminal is your Mac's command line, a text window where you can give your computer direct instructions. You'll only need a handful of commands throughout this guide.

To open it: press ⌘ Space, type Terminal, press Enter. Keep it open as you work through these steps.

💡 Each command block below has a Copy button. Use it to avoid typos.
2

Install Homebrew

▾

Homebrew is a package manager that makes installing software on a Mac much easier. Paste this into Terminal and press Enter:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/homebrew/install/HEAD/install.sh)"

It will ask for your Mac password. Type it and press Enter. Nothing will appear as you type, and that's normal. Just type your password and hit Enter.

When it finishes, it may show a few extra commands to run (to add Homebrew to your path). Run those too before moving on.

3

Install Python

▾

Python is the programming language that powers your scripts. Install it with:

brew install python

When it's done, verify it worked:

python3 --version

You should see something like Python 3.14.x. If you do, you're good.

4

Create your project folder

▾

This is where your scripts and Gmail credentials will live. Run these commands one at a time:

mkdir ~/gmail-toolkit
cd ~/gmail-toolkit

Now set up a virtual environment. This keeps your Gmail packages tidy and separate from the rest of your Mac:

python3 -m venv venv

Then install the packages your scripts need:

venv/bin/pip install google-auth google-auth-oauthlib google-api-python-client requests
5

Set up Gmail API access

▾

This is the most involved step. You're giving your scripts permission to access your Gmail. Google requires this for security. It takes about 10 minutes.

💡 You'll do this once. After that, your scripts run automatically without any extra login steps.
💡 If your script suddenly asks you to log in again months later, that's normal — just follow the same browser login prompt and it'll continue working.
  1. Go to console.cloud.google.com and sign in with your Google account.
  2. Click Select a project at the top → New Project. Name it anything (e.g. "Gmail Toolkit") → click Create.
  3. In the search bar at the top, search for Gmail API → click it → click Enable.
  4. In the left sidebar, go to APIs & Services → OAuth consent screen.
    • Choose External → click Create
    • Fill in an app name (anything works), your email address in two places
    • Click Save and Continue through the remaining screens. You don't need to add anything else
  5. Go to APIs & Services → Credentials → click + Create Credentials → OAuth 2.0 Client ID.
    • Application type: Desktop app
    • Click Create → then click the download icon to download the JSON file
  6. Rename the downloaded file to credentials.json and move it into your gmail-toolkit folder.
6

Download your script and run it

▾

Use the Script Builder below to generate your custom script. Move the downloaded file into your gmail-toolkit folder, then run it:

💡 Replace your_script_name.py with the actual filename of the script you downloaded from the Script Builder below, for example, gmail_scan.py or gmail_auto_sort.py.
cd ~/gmail-toolkit && venv/bin/python3 your_script_name.py

The first time you run it, a browser window will pop up asking you to log in to Google and grant access. That's expected. Do it, close the browser, and your script will continue running.

💡 After the first run, you won't need to log in again.
💡 If you set up the auto-sort script, note that it runs every 30 minutes — so a new email might sit in your inbox briefly before it gets moved. That's normal.

Script Builder

Tell us what you want. We'll write the script for you.

What do you want your inbox to do?

Select all that apply. You can combine them or download separately.

Frequently Asked Questions

How often should I run the inbox scan?

Run it once a week for the first month or so. Each scan only catches senders currently in your inbox, so the more you run it, the more complete your picture becomes. Once you feel like you've seen everything, you can stop or run it occasionally as a check-in.

Does the scan check every email in my inbox, or only certain ones?

It scans for emails that contain an unsubscribe link, which is how it identifies marketing and subscription senders. It won't surface emails from your actual contacts, so you don't have to worry about it flagging real conversations.

Is this safe? Am I handing over access to my Gmail?

You're giving access to your own scripts running on your own computer. Nothing goes to a third party. The credentials.json file you download from Google stays on your Mac and never leaves it. Google's OAuth system is the same login method used by apps like Calendly and Zoom.

Will any of my emails get deleted?

No. The scripts only move emails between folders and labels. Nothing is deleted unless you delete it yourself.

Can I add more senders to my auto-sort script later?

Yes. Open the script in any text editor, find the list of domains, add new ones, and save. Then run it again. Takes about 30 seconds.

What if my Mac is closed at my scheduled delivery time?

No problem. The delivery script checks every 15 minutes. If your Mac was sleeping when delivery was supposed to happen, it'll automatically deliver your held emails within 15 minutes of the next time you open it.

Get Stuck?

Tell us more.