Contents
4.2Connecting a Gmail or Google Workspace mailbox
Gmail does not accept your ordinary Google account password from an external mail application. If you enter your standard password, Google refuses the connection with a message containing "Application-specific password required". This refusal is Google's security rule, not an error in Bmator.
Note: Google renames its screens over time; external settings and prompts referenced below reflect Google's wording as of October 2026.
Which route should I take?
- Addresses on your own domain (Google Workspace): Use your own private Google connection configured as Internal. This setup is free, does not expire, and shows no recurring sign-in prompts.
- Personal addresses ending in @gmail.com: Use an app password. Setting up your own Google connection for an @gmail.com address forces you to sign in again roughly every seven days.
- Personal addresses that cannot generate an app password: If 2-Step Verification is disabled and you do not wish to enable it, or if your account uses Advanced Protection, use your own private Google connection and anticipate the weekly sign-in.
Detailed walkthroughs are provided in the follow-up guides:
Route 1: Your own private Google connection
Setting up your own private connection takes about fifteen minutes and is completed once inside your Google account. When configured, you authenticate on Google's own page, Bmator never receives your password, and mailbox synchronisation continues in the background.
This setup exists because Google requires any multi-tenant application that reads Gmail mailboxes to undergo an annual third-party security assessment. For details on Google's verification requirements, visit Google Cloud restricted scopes verification. Because Bmator has not undergone that paid audit, Bmator allows each user or organisation to create their own private connection, which Google permits without an independent audit.
The behaviour and maintenance depend on your account type:
- Google Workspace accounts: The connection is marked Internal to your organisation. Google displays no security warnings during sign-in, and the authentication token does not expire.
- Personal Google accounts (@gmail.com): Google sets the connection state to Testing. In this mode, Google invalidates authentication tokens periodically, requiring you to re-authenticate approximately every seven days.
Do not attempt to bypass the seven-day expiration by choosing "Publish app" in the Google Cloud console. Because reading mail requires a restricted scope, Google immediately blocks a published connection until it completes the official security assessment.
For organisations, one person (typically a Google Workspace administrator) creates the project in the Google Cloud console. Other team members can then paste that project's Client ID and Client secret into Bmator to connect their mailboxes without repeating the console setup.
Route 2: An app password
An app password is a generated 16-character code created directly inside your Google account. For setup requirements, see Google's app password documentation.
Setup takes about two minutes, requires no Google Cloud project, and does not expire. However, it requires 2-Step Verification to be enabled on your Google account. Additionally, Google Workspace administrators have the ability to disable app password creation across their organisation.
Starting connection setup in Bmator
- Navigate to Connect a mailbox.
- Enter your Gmail or Google Workspace email address. The screen automatically displays the setup instructions for Route 1 (your own connection).
- To use Route 2 instead, select Use an app password instead directly below the setup instructions to display the password input field.
Managing existing Gmail mailboxes
To view or update a mailbox that has already been connected, go to Mail, select Mailboxes, and click your mailbox.
Mailboxes connected with an app password
- Updating the password: Select Replace the password, enter the new app password, and click Replace and reconnect. Your existing mail and items filed from it remain intact.
- Switching to a private connection: Select Connect through your own Google client and choose Set it up. No mail or filed data is lost.
Mailboxes connected with your own connection
- Weekly sign-ins: If the mailbox status displays Reconnect needed (common every seven days on personal @gmail.com accounts), click Reconnect and sign in on Google's authentication page.
- Switching to an app password: You cannot convert a private Google client connection directly into an app password connection in place. To change routes, choose Remove this mailbox and reconnect it using an app password. Any emails saved to the knowledge base remain unaffected; other imported items are cleared from Bmator and re-imported from the new connection.