Credentials

Create a Gmail app password.

MailGlass never asks for your Google account password. It needs an app password: a 16-character credential you can revoke at any time without changing your real password.

Before you start

App passwords do not exist until 2-Step Verification is turned on. If you have never set it up, do that first or the app password page will simply refuse.

Step 1. Sign in as the right account

The app password page always issues a credential for whoever is currently signed in. If you manage more than one Google account, use a private window or the account switcher, or you will create a password for the wrong mailbox.

Step 2. Turn on 2-Step Verification

Open myaccount.google.com/signinoptions/twosv and complete the setup. Any second factor works: an authenticator app, a phone prompt, or a security key.

Step 3. Create the app password

Open myaccount.google.com/apppasswords.
Enter a name, for example MailGlass.
Click Create.
Copy the 16-character value. Google shows it once and never again.

Spaces are cosmetic

Google displays the password as four groups, like abcd efgh ijkl mnop. The spaces are presentation only: the credential is the 16 letters. MailGlass strips whitespace for you either way.

Step 4. Enable IMAP

In Gmail, open Settings, See all settings, Forwarding and POP/IMAP and choose Enable IMAP, then save. Without this the password authenticates but the mailbox cannot be opened.

Step 5. Store it where MailGlass can read it

MailGlass never creates or writes the secret file. Save the value yourself and restrict it:

terminal

      mkdir -p ~/.secrets
printf '%s' 'abcdefghijklmnop' > ~/.secrets/gmail_app_password
chmod 600 ~/.secrets/gmail_app_password
    

Then reference it from the config file:

config.json

      {
  "accounts": [
    {
      "id": "work",
      "provider": "gmail",
      "email": "you@gmail.com",
      "auth": { "password": { "file": "~/.secrets/gmail_app_password" } }
    }
  ]
}
    

You can also use { "env": "GMAIL_APP_PASSWORD" } and pass the value through the environment, which is easier in Docker.

Verify

terminal

      mailglass --check
    

Exit 0 means the credential works. Exit 2 means Google rejected it.

If the app password page is unavailable

Cause	Fix
2-Step Verification is off	Most common. Complete step 2 first.
2SV uses security keys only	Add an authenticator app or phone prompt; app passwords stay hidden otherwise.
Advanced Protection Program is on	App passwords are unavailable by design.
Google Workspace account	An admin may have disabled app passwords. Only the admin can re-enable them.
Family Link or school account	Not supported by Google for app passwords.

If authentication still fails

Spaces: paste the 16 letters, not the grouped display.
Trailing newline: use printf rather than echo when writing the file.
Revoked: a password deleted in your Google account fails immediately. Create a new one.
Wrong account: the most common cause of "invalid credentials" for people with several mailboxes.

Treat it like a password

An app password grants full IMAP access to the mailbox, including write access. MailGlass only ever reads, but the credential itself is not scoped. Use one password per client and revoke it at myaccount.google.com/security when you stop using the tool.