Inbox Gatekeeper — Unknown Sender Filter for Gmail

How it works

1 Built on Google Apps Script

Google Apps Script is Google's built-in scripting platform — it's like a macro system for your Google account. It runs on Google's servers, not your computer, and has native access to Gmail, Contacts, and Calendar without any third-party dependencies. Think of it like an Excel macro, but for Gmail.

Installing is just copy-paste. You open script.google.com, create a new project, paste in the code, and run a setup function. No terminal, no package manager, no deployment. It takes about 10 minutes and requires zero coding knowledge. Once set up, it runs 24/7 on Google's infrastructure — even when your computer is off.

2 What happens in your inbox

Every 15 minutes, the script checks your recent inbox messages. Each sender is matched against your Google Contacts, your "Other Contacts" (everyone you've ever emailed), a list of 80+ common services, and whitelisted domains you configure. Newsletters with unsubscribe headers also pass through.

If a sender doesn't match any of those checks, they're unknown. Their email gets labeled Unknown Senders and archived — out of your inbox, but easy to find and review whenever you want. Add them to your contacts and they'll pass through next time.

3 Pay to Deliver via Stripe

If you want to go further, you create a free Stripe payment link — takes about 5 minutes. You choose the amount, the framing, and where the money goes. Inbox Gatekeeper then includes this link in its auto-reply to unknown senders.

When someone pays, Stripe sends you a notification. You check your Unknown Senders label, find their email, and decide whether to reply. If they're legitimate and you want to refund them, one click in Stripe handles it. The whole flow is deliberately manual to keep the script simple and dependency-free.

Under the hood

The technical details, for those who want them.

Filter logic

Every 15 minutes, the script pulls your recent inbox messages and checks each sender against five things: your Google Contacts, your "Other Contacts" (everyone you've ever emailed), your whitelisted domains, the common services list, and whether the email has a newsletter-style List-Unsubscribe header. If the sender passes none of those checks, they're unknown.

Unknown senders get a label applied and are archived out of your inbox. The label shows unread counts, so you always know when something's there.

Newsletter passthrough

Most newsletters and marketing emails include a List-Unsubscribe header (it's required by most email providers). The script checks for this header and lets those emails through to your inbox. Some spam also uses this header, so it's not perfect — but in practice it catches the vast majority of legitimate subscriptions.

You can turn this off by setting SKIP_NEWSLETTERS = false if you'd prefer newsletters to be filtered too.

Common services whitelist

The script ships with 80+ pre-configured domains for services most people get email from. It matches subdomains automatically — so amazon.com in the list also covers email.amazon.com, shipment-tracking.amazon.com, and any other subdomain.

amazon.com fedex.com ups.com usps.com linkedin.com paypal.com stripe.com chase.com delta.com airbnb.com uber.com netflix.com spotify.com apple.com github.com substack.com zoom.us slack.com docusign.com + 60 more

You can add or remove domains from the COMMON_SERVICES array in the script at any time.

The auto-reply

When enabled, the script sends a single reply to each unknown sender with your Stripe link. It's smart about it:

Never replies to no-reply, mailer-daemon, or notification addresses
Never replies to bulk mail (newsletters with unsubscribe headers)
Never replies to the same sender twice
Replies from whichever of your email addresses they wrote to

You can fully customize the auto-reply by editing AUTO_REPLY_SUBJECT and AUTO_REPLY_BODY near the top of the script. The ${STRIPE_LINK} variable inserts your payment link; ${YOUR_NAME} inserts your name. Test changes by running testAutoReply to send it to a friend before going live.

What to charge (and where the money goes)

You can set any amount in Stripe and frame it however fits your style:

A coffee for my inbox — low-friction, casual
A carbon credit — set up a Stripe link that donates to a carbon offset provider
A charity donation — link to a charity you care about; senders pay to reach you and the money goes somewhere good
A higher bar — if you want a real filter, set it higher; recruiters and salespeople with budget won't blink
Pay what you want — Stripe supports customer-chosen amounts

Tweak the auto-reply text to match whatever you choose. If you're donating the proceeds, say so — it makes the whole thing feel less like a toll booth and more like a feature.

When someone pays

Right now, there's no automatic Stripe-to-Gmail integration — paying doesn't auto-deliver the email to your inbox. You'll need to check your Stripe dashboard periodically, see who paid, then search for their email in your "Unknown Senders" label to read it and decide whether to reply. Add them to your contacts if you want future emails to come straight through.

This is a manual step by design. It keeps the script simple and dependency-free.

Adding legitimate senders

If a real person gets filtered, just add them to your Google Contacts. Next time the script runs, they'll pass right through. In Gmail, you can hover over a sender's name and click "Add to contacts" — takes two seconds. For an entire domain, add it to WHITELISTED_DOMAINS or COMMON_SERVICES.

Trigger frequency

The script defaults to running every 15 minutes. You can change this by editing the setup function — look for .everyMinutes(15) and change it to .everyMinutes(5) or .everyMinutes(10). After editing, run setup again to replace the old trigger.

Don't go lower than every 5 minutes. Google Apps Script has a daily execution quota — 90 minutes for regular Gmail accounts, 6 hours for Google Workspace. At 15 minutes (96 runs/day), you're well within limits.

Security & permissions

The script runs entirely on Google's servers. No data leaves Google's infrastructure. There are no external API calls — the Stripe link in the auto-reply is just a URL in the email body.

Permission	What it does	Risk
Gmail (full)	Search inbox, add labels, archive, send replies	Medium
People API	Read-only access to your contacts	Low
Gmail API	Read your send-as aliases (read-only)	Low
Script triggers	Create the 15-minute recurring timer	Low

The Gmail "full access" scope is broad because Google doesn't offer fine-grained permissions for Apps Script. The script only reads, labels, archives, and sends — it never deletes anything. Keep the project private and don't share editor access.

Install guide

10 steps. No coding knowledge needed. About 10 minutes.

Step-by-step instructions ▼

Download Script

Open Google Apps Script

Go to script.google.com and click New Project. Make sure you're signed into the Google account whose Gmail you want to filter.

Paste the script

Select all the default code (Cmd+A or Ctrl+A), delete it, and paste in the entire contents of the downloaded gmail-gatekeeper.js file. Hit Cmd+S / Ctrl+S to save.

Add the People API

In the left sidebar, click the + next to Services. Find People API in the list and click Add. This lets the script check your contacts.

Add the Gmail API

Click Services (+) again and add the Gmail API. This lets the script detect your send-as aliases so auto-replies come from the right address.

Configure your settings

Edit the configuration section at the top of the script:

Add your trusted domains to WHITELISTED_DOMAINS (your company domain, etc.)
Review COMMON_SERVICES — add or remove services as needed

Save again.

Run setup

In the toolbar, click the function dropdown (it probably says myFunction), select setup, and hit the ▶ Run button. Google will ask you to authorize — click through the permissions flow.

You'll see a scary "Google hasn't verified this app" screen. Click Advanced → "Go to [project name] (unsafe)". This is normal for personal scripts.

Verify the trigger

Click the clock icon (⏰) in the left sidebar. You should see a trigger listed for processNewMessages, set to run every 15 minutes. If it's there, the filter is live.

Set up Stripe (optional)

Skip this step if you only want the filter without auto-replies. Otherwise:

Go to stripe.com and create a free account
In the dashboard, go to Payment Links and click + New
Create a product, set your price to whatever you want, make sure "Collect email address" is on
Copy the payment link URL and paste it into STRIPE_LINK in the script
Replace Your Name with your name in the config

Save the script again.

Test with a friend

Before turning on auto-replies:

Put a friend's email address in TEST_EMAIL at the top of the script and save
Have them email you from an address that's not in your contacts
Select testRun from the dropdown and run it — their email gets filtered
Select testAutoReply and run it — your friend receives the auto-reply with your Stripe link
Ask them to confirm it looks right and the payment link works

Go live

Change AUTO_REPLY = false to AUTO_REPLY = true at the top of the script, save, and you're done. The filter runs whether auto-reply is on or not — you can always enable it later.

Common problems

Most issues happen during setup. Here's what to look for.

"Google hasn't verified this app" warning

This is normal for personal Apps Scripts. Click Advanced at the bottom left, then click "Go to [project name] (unsafe)". Google shows this because you haven't submitted the script for their app review process, which is only needed for public apps.

"Something went wrong" after clicking Advanced

Usually a multi-account session issue. Your browser is confused about which Google account to authorize. Fix: open an incognito window, sign into only the Google account you want, go to script.google.com, and try again from there.

"ReferenceError: People is not defined"

You haven't added the People API as a service. In the left sidebar, click the + next to Services, find People API, and click Add. Then run the function again.

Function dropdown only shows "myFunction"

The script didn't get pasted in correctly. Go back to the code editor, select all (Cmd+A), delete, and paste the full script again. Save. The dropdown should now show setup, testRun, testAutoReply, and others.

No trigger appears after running setup

Make sure you selected setup from the function dropdown before clicking Run. If you ran a different function, the trigger won't be created. Select setup, run it, then check the Triggers tab (clock icon in the left sidebar).

Script shows the wrong developer email in authorization

If you're logged into multiple Google accounts, the OAuth flow can pick the wrong one. The developer email shown doesn't affect functionality — the script runs under whichever account owns the Apps Script project. If it bothers you, use an incognito window with only one account signed in.

Emails from known senders are getting filtered

The sender isn't in your Google Contacts or "Other Contacts." Add them to your contacts and they'll be whitelisted on the next run. If it's an entire domain, add it to the WHITELISTED_DOMAINS or COMMON_SERVICES array in the script.

Newsletters are getting filtered

Check that SKIP_NEWSLETTERS is set to true at the top of the script. If it already is, the newsletter may not include a List-Unsubscribe header (some smaller ones don't). In that case, add the sender's domain to WHITELISTED_DOMAINS.

Auto-reply isn't being sent

Check: (1) Is AUTO_REPLY set to true? (2) Has the script already replied to that sender? Each sender only gets one reply. (3) Is it a no-reply address or newsletter? The script skips those. (4) Check the Executions tab (left sidebar) for error logs.

Google Workspace admin blocks the script

If you're on Google Workspace (not regular Gmail), your admin may need to allow internal apps. Go to admin.google.com → Security → Access and data control → API controls → Settings. Make sure "Internal apps" is set to "Trust internal apps" and "Unconfigured third-party apps" is set to "Allow."

I want to reset and re-send auto-replies to everyone

Select resetRepliedSenders from the function dropdown and run it. This clears the list of senders who've already received an auto-reply, so the next time they email, they'll get one again.

Will it run if my computer is off?

Yes. Google Apps Script runs on Google's servers, not your computer. Once the trigger is set, it runs 24/7 regardless of whether your computer is on.

Will it work with email clients like Apple Mail or Outlook?

Yes. The script runs server-side on Gmail before your client syncs. Labels show up as folders in IMAP clients. You may need to subscribe to the "Unknown Senders" folder in your client's settings.

What it does

Unknown Sender Filter

Pay to Deliver