Download for Mac
Setup guide

Your own Gmail app, in about five minutes.

InboxMinder reads your mail through a Google Cloud app that belongs to you, so no shared app ever sees it. You create it once, in your own account, with no code. Every click is here, on video and in writing.

Last updated 8 October 2026Video 1:29Questions: hi@kelviq.com

Watch it

Every click in the Google Cloud console, from a new project to the two values you paste into the app. The written steps below match it exactly.
The short version
  • Why your own app: Gmail's scopes are in Google's restricted category. A shared InboxMinder client would be a middleman with access to your mail and would need annual third-party audits. Yours needs neither.
  • What you end up with: a Client ID and a Client secret, pasted into the setup wizard (or into inboxminder init).
  • What it costs: nothing. The Gmail API has no charge for this kind of use and billing never needs enabling.

Before you start

You need a Google account with Gmail: either a Google Workspace account (mail on your own domain, such as you@yourcompany.com) or a personal @gmail.com account. Which one you have changes exactly one step, the consent screen in step 3, and it is worth knowing now.

  • Workspace: the best case. You mark the app "Internal", there is no warning screen, and your sign-in never expires.
  • Personal @gmail.com: fully supported, with one caveat about token expiry that step 3 explains and shows you how to avoid.

Step 1: Create a project

  1. Open console.cloud.google.com and sign in with the Google account whose mailbox you want minded.
  2. At the top of the page, click the project picker (the dropdown next to the Google Cloud logo; it may say "Select a project").
  3. Click New project.
  4. Name it anything you like: inboxminder works. Leave organization and location as they are.
  5. Click Create, wait a few seconds, then make sure the new project is selected in the picker. The console sometimes stays on your old project, and everything below must happen inside this one.

Step 2: Enable the Gmail API

  1. In the left navigation, or the search bar at the top, go to APIs & Services → Library.
  2. Search for Gmail API.
  3. Click it, then click Enable.

That is the only API InboxMinder needs.

The consent screen is the page Google shows you, and only you, when you authorize the app in your browser.

Google has been renaming this area of the console. Depending on when you read this, it is either APIs & Services → OAuth consent screen or a section called Google Auth Platform with Branding, Audience and Clients pages. The settings are the same; only the navigation labels differ.

  1. Go to APIs & Services → OAuth consent screen. Click Get started if the console asks you to configure it first.
  2. App name: InboxMinder. This is only what the consent page shows you; call it anything.
  3. User support email: pick your own address.
  4. Audience / User type: this is the fork in the road.
    • Google Workspace account: choose Internal. Done: no test users, no verification warnings, and refresh tokens that never expire. If you have the choice, this is the setup to want.
    • Personal @gmail.com: Internal is greyed out; choose External.
  5. Contact email: your address again.
  6. Agree to the user data policy checkbox and click Create or Finish.

External only: add yourself as a test user

  1. Still in the consent screen area, find Test users. On newer consoles this lives under Audience.
  2. Click Add users and enter your own Gmail address.
  3. Save.

An External app starts in Testing status, which is fine, but comes with one real annoyance.

The 7-day token expiry (External + Testing only). While an External app is in Testing status, Google expires its refresh tokens after 7 days. In practice: about once a week, InboxMinder loses access, shows a "Google needs you to sign in again" notice, and you sign in again from the menu bar (30 seconds in the browser).

To make it permanent: on the consent screen page, click Publish app to move it to Production status. You do not need to submit it for Google's verification review; publish and ignore the "needs verification" notices. From then on, when you authorize you see a "Google hasn't verified this app" warning once; click Advanced → Go to inboxminder (unsafe). That warning is Google talking about your own app, in your own account. After that, tokens no longer expire on a timer.

Step 4: Create the OAuth client

This is what produces the two strings you actually need.

  1. Go to APIs & Services → Credentials, or Clients in the newer console.
  2. Click Create credentials → OAuth client ID.
  3. Application type: choose Desktop app. Not "Web application": Desktop app is what allows the localhost redirect InboxMinder uses, and there are no redirect URIs to configure.
  4. Name it anything (inboxminder again is fine) and click Create.
  5. A dialog shows your Client ID (ends in .apps.googleusercontent.com) and Client secret (starts with GOCSPX-). Copy both, or download the JSON. You can come back and view them any time from the Credentials page.

A note on the word "secret": for Desktop apps, Google itself documents that the client secret is not treated as confidential the way a server secret is. InboxMinder still stores both values in your macOS Keychain, never in config files.

Step 5: Give the values to InboxMinder

Using the Mac app

The setup wizard's "Connect your own Gmail app" screen is waiting for exactly these two values. Paste the Client ID and Client secret, click Continue, then click Authorize in Browser on the next screen. That is it; skip the rest of this section.

Using the command line

If you are running inboxminder init, it asks for both values at the right moment. Otherwise, store them any time:

inboxminder set-key gmail-client-id
inboxminder set-key gmail-client-secret

Each command prompts for the value and writes it to the macOS Keychain. Then authorize:

inboxminder auth

Either way, your browser opens Google's consent page. Sign in with the same account, accept (clicking through the unverified-app warning if you published an External app), and the browser tab says authorization is complete. Tokens land in the Keychain. InboxMinder's local web server for the redirect only ever listens on localhost, and only during this flow.

The requested scope is gmail.modify: read mail, write labels, save drafts. There is no send scope and no delete capability in what you just granted.

One app, every mailbox: if you later mind a second account with an InboxMinder profile, it reuses this same Google app. You never repeat this walkthrough.

Verify it works

Mac app: finish the wizard's last step and the menu bar leaf switches to watching your inbox. Send yourself an email and watch the label land.

Command line:

inboxminder agent status

should report the agent running (install it with inboxminder up if you have not yet). Or preview a single classification without touching anything:

inboxminder classify <gmail-message-id>

Troubleshooting

"Access blocked: inboxminder has not completed the Google verification process"

Your app is External and your address is not in Test users (step 3), or you are signing into a different Google account than the one you added. Add the exact address and retry.

"Google hasn't verified this app"

Expected for an External app published to Production. Click Advanced, then Go to inboxminder (unsafe). It is your own app; "unverified" means you did not submit it for Google's review, not that anything is wrong.

Gmail authorization expired after about a week

The External + Testing token expiry described in step 3. Either sign in again weekly, or publish the app to Production to stop the timer.

"Error 403: access_denied", or the consent page never lists Gmail access

The Gmail API is not enabled in the same project as your OAuth client (step 2), or the project picker was on the wrong project when you created one of the two. Both must live in the same project.

"invalid_client" when authorizing

The Client ID or secret was pasted with a stray space or line break, or one value went into the other's field. Paste both again carefully.

The browser flow completes but InboxMinder says auth failed

Another process may be holding the local callback port, or the flow sat open too long. Authorize again; the flow is safe to repeat.

Workspace account: "Internal" is greyed out

You are signed into a personal @gmail.com account, or your Workspace admin has restricted project creation. Check the account in the console's top-right corner first.

FAQ

Does Google charge for this?

No. The Gmail API has no charge for this kind of use, and nothing in this setup requires billing to be enabled on the project.

Can I revoke access later?

Any time: at myaccount.google.com/permissions, which kills the tokens immediately, or by deleting the OAuth client or the whole project in the console.

Can I use one app for two mailboxes?

Yes. The OAuth client is just a door; each InboxMinder profile stores its own tokens for whichever account authorizes. For a Workspace Internal app, both accounts must be on the same domain; otherwise make the app External and add both addresses as test users.

Why "Desktop app" and not "Web application"?

Desktop clients get the loopback (localhost) redirect flow, which is exactly how an app on your own machine should authorize. A Web client would demand redirect URIs and a hosted callback, which InboxMinder does not have, by design.

Last updated 8 October 2026PrivacyTermsRefundsSupport