Gmail with your own Google app

Gmail works with an app password, and mail uses one by default. Use OAuth instead when you cannot make an app password: no 2-Step Verification on the account, or a Google Workspace domain that turns app passwords off. mail has no Google app of its own for mail (Google requires a paid security review for an app that reads mail for others), so you sign in through an app you create. It takes about 20 minutes and costs nothing.

1. A Google Cloud project just for mailCopy Anchor Link

Open Google Cloud Console and choose New Project in the project selector. Name it, for example, "mail for me", and keep it selected for every step below.

Use a new project even if you already have one for drive or gcal. When a sign-in is revoked, Google removes every permission given to that project, for every app in it (installed apps): a shared project would sign drive and gcal out too.

2. Consent screenCopy Anchor Link

Open ☰ → Google Auth platform → Branding (direct link) and choose Get Started. Give an app name ("mail for me"), your address as the support and contact email, and the External audience (or Internal for a Workspace account that only you use). Create it.

3. PermissionCopy Anchor Link

Open Google Auth platform → Data Access (direct link), choose Add or Remove Scopes, and add https://mail.google.com/ by hand in the manual entry field. Save. It is the only scope Gmail gives IMAP and SMTP (XOAUTH2). mail also asks for openid and email, to check that you signed in with the right account.

Google's page does not say whether the Gmail API must be enabled for IMAP alone. If the sign-in works and session status --check then fails, enable the Gmail API in this project and try again.

4. Publish the app (Production), without verificationCopy Anchor Link

Open Google Auth platform → Audience (direct link) and choose Publish app, then confirm. Do not submit it for verification.

While an External app is in Testing, Google ends its sign-ins after 7 days (refresh token expiration), and a scheduled sync stops once a week. A published app keeps the sign-in. Google does not ask a personal app with fewer than 100 users to be verified (exceptions); at sign-in it shows "Google hasn't verified this app": choose Advanced, then Go to mail for me (unsafe). It is your own app.

If you keep the app in Testing, add your address under Test users, and expect to run session start every week; mail doctor warns from the sixth day.

5. Desktop clientCopy Anchor Link

Open Google Auth platform → Clients (direct link), choose Create Client, Application type → Desktop app, a name, and Create. Choose Download JSON and save the file outside any repository. Make it readable by you only, or mail refuses it:

chmod 600 ~/Downloads/client_secret_*.json

The file names the app; it is not your access. mail reads it once, at sign-in, and keeps the app's id and secret with the tokens in the keyring.

6. Sign inCopy Anchor Link

A new profile:

mail gm session start --address [email protected] --client-file ~/Downloads/client_secret_XXXX.json

--client-file is what makes a new Gmail profile sign in with OAuth. A Gmail profile that has an app password now: switch it first, in a terminal (an agent cannot change auth):

mail gm config set auth oauth
mail gm session start --client-file ~/Downloads/client_secret_XXXX.json

The browser opens Google's page. Choose the account, allow access, and mail checks the address and logs in to IMAP before it saves anything. On a profile already switched to OAuth, MAIL_GOOGLE_CLIENT_ID and MAIL_GOOGLE_CLIENT_SECRET can stand in for --client-file.

Signing outCopy Anchor Link

mail gm session end forgets the sign-in on this computer and keeps the mail. --revoke also asks Google to revoke it, which removes every permission of the whole Google project; with a project only for mail, that is just mail.