Google

Gmail, Drive, Calendar and Sheets. Each access is granted separately.

A Google connection lets Mankomail act on a member's Google account: mirror and send their Gmail mail, and — when the member allows it — upload to Google Drive, create Google Calendar events and append rows to Google Sheets. Each member connects their own account; nobody can connect a mailbox on someone else's behalf.

Access is split into capabilities (mailbox, files, calendar, spreadsheets). Each capability is a separate consent, granted on its own and added to the previous ones: connecting a mailbox gives no access to Drive, and allowing Drive does not ask for mail access again. The setup has two halves: an administrator registers the organisation's own Google OAuth application once ("bring your own app"), then each member connects their account.

At a glance

• Identifier: google
• Family: Account
• Set up by: Each member, for themselves
• Authentication: OAuth sign-in, one capability at a time
• Credential type: gmail_oauth

Capabilities and scopes

Each capability is granted separately, when a member first needs it. Every authorisation also asks for openid, email.

Capability	Scopes	Nodes
mail	https://www.googleapis.com/auth/gmail.readonly, https://www.googleapis.com/auth/gmail.send, https://www.googleapis.com/auth/gmail.modify, https://www.googleapis.com/auth/gmail.labels
drive	https://www.googleapis.com/auth/drive.file	Drive — upload a file, Drive — search files, Drive — create a folder
calendar	https://www.googleapis.com/auth/calendar.events, https://www.googleapis.com/auth/calendar.freebusy, https://www.googleapis.com/auth/calendar.calendarlist.readonly	Calendar — create an event, Calendar — find free slots
sheets	https://www.googleapis.com/auth/spreadsheets	Sheets — append a row

Before you start

• An administrator of the Mankomail instance registers the OAuth application. Members never see the client secret.
• A Google Cloud project in which you can create an OAuth client and enable APIs.
• The public address of your instance. The redirect URI is derived from the PUBLIC_BASE_URL setting; it must be the address your members actually use in their browser. See environment variables.
• An encryption key (ENCRYPTION_KEY) configured on the instance. Without it, the instance cannot store the client secret or the members' tokens, and every connection fails with oauth.encryption_disabled.
• Who your members are. If they all belong to the same Google Workspace organisation, the consent screen can use the Internal user type. Personal Gmail accounts, or accounts from several organisations, need the External user type (see the warning in the next section).

Register the OAuth application (administrator)

In Mankomail, open Administration › OAuth applications and select Google under Provider to configure. The page shows what you need to take to the Google Cloud console: the Redirect URI, and the scopes requested capability by capability. The redirect URI always has this shape:

<PUBLIC_BASE_URL>/api/v1/oauth/google/callback

Then, in the Google Cloud console:

1. Create or select a project.
2. Enable the APIs matching the capabilities your members will use: Gmail API for the mailbox, Google Drive API for files, Google Calendar API for the calendar, Google Sheets API for spreadsheets. An API that is not enabled makes the matching nodes fail even when the member has consented.
3. Configure the consent screen (Google Auth platform › Branding, then Audience). Choose the Internal user type when all your members are in your Google Workspace organisation. You do not need to declare scopes on Google's side: Mankomail requests them itself when a member connects.
4. Create the OAuth client (Google Auth platform › Clients › Create client), with the application type Web application. Under Authorized redirect URIs, add the redirect URI copied from Mankomail, character for character.
5. Copy the client ID and the client secret.

Back in Mankomail, under Application credentials:

1. Paste the Client ID. It must end with .apps.googleusercontent.com; the field refuses anything else (a browser autocomplete that appends an address to the ID is the usual cause).
2. Paste the Client secret.
3. Click Save. The state badge switches to Application registered and the secret is shown only by its last four characters.

External user type

With the External user type and the Testing publishing status, only the test users listed in the console can connect, and Google issues refresh tokens that expire after 7 days: mailboxes then stop syncing and must be reconnected. Gmail scopes are classified as restricted by Google, so publishing an External app that requests them goes through Google's verification. Prefer the Internal type whenever your members share a Google Workspace organisation.

Rotating the secret

The secret is never shown again and is not kept when you save: re-enter it on every save, even to fix only the client ID. To rotate it, create a new secret in the console, paste it with the client ID, and save.

Connect an account (member)

1. Open Connections, click Add a connection, then Connect on the Google card.
2. Google asks you to choose an account and shows the consent screen. Leave every requested access ticked and accept.
3. You come back to Mankomail with the message Mailbox … connected. The mailbox starts syncing; its progress is visible under Mailboxes (see mailboxes and the mirror).

The first connection always grants the mailbox capability. The other capabilities are added from the account's row in Connections, under Mail and cloud accounts: each missing capability has its own button — Connect Google Drive, Connect the calendar, Connect spreadsheets. Each click opens a new consent screen for that access only; once it is granted, the capability appears as a badge on the account.

A few things to know:

• Incremental authorisation. Every authorisation asks Google to keep the scopes already granted, so adding Drive never cuts off the mailbox.
• Tick every box. Google shows some accesses as checkboxes. If you untick one, the connection is refused with You did not grant every access requested and nothing is saved: start again and leave the boxes ticked.
• Ten minutes. An authorisation must be completed within ten minutes of clicking; after that, or if the link is reused, it is refused (oauth.invalid_state).
• Same account, same connection. Authorising the same Google address again updates the existing connection instead of creating a second one.
• Coming from a node. A node that needs a capability you have not granted links to Connections; after the consent you can go back with Back to the workflow.

What each access allows

Mankomail requests the narrowest scopes that make each capability work:

• Mailbox — read, send and file the mail of the connected mailbox (Gmail read, send, modify and labels scopes). These are the Gmail API scopes, not full IMAP access.
• Files — drive.file only: Mankomail reaches the files it created itself or that the member explicitly pointed it to — never the whole Drive. A node therefore cannot see a folder Mankomail did not create, even if the member owns it.
• Calendar — calendar.events: create and change events, not administer calendars or their sharing. Creating an event sends no invitation email unless the node asks for it (see Calendar — create an event).
• Spreadsheets — read and write spreadsheets.

openid and email are requested with every capability: the account's address is what identifies the connection and lets a second capability be attached to the same account.

Disconnect, revoke, reconnect

• Removing the mailbox. A Google account is not deleted from Connections: you disconnect its mailbox from Mailboxes. Disconnecting stops the sync, keeps the history readable and removes the mailbox capability. If the account still carries other capabilities (Drive, calendar…), the connection stays so that those nodes keep working; otherwise it is erased.
• Revoking at Google. Disconnecting in Mankomail does not revoke the access at Google. To cut it entirely, remove the application's access from the Google account's security settings. Google revokes the whole grant, not one capability: every capability of that account stops working.
• When access is lost. Google stops honouring a connection when the member revokes access, changes their password (Gmail scopes), leaves it unused for six months, or exceeds 100 live refresh tokens for the same account and OAuth client. Mankomail then marks the connection as revoked, the mailbox shows an error in Connections and Mailboxes, and nodes that need the account fail with credential.capability_missing.
• Reconnecting. Connect the same account again: start with the mailbox (Reconnect this mailbox under Mailboxes, or the Google card in Connections), then each capability you need. The existing connection and mailbox are reused, history included.

Common errors

Errors of the connection flow are shown as a banner on Connections when you come back from Google.

Message or code	Cause	What to do
oauth.app_not_configured — No application is configured for this provider.	No Google application is registered, or it is disabled.	An administrator registers it under Administration › OAuth applications.
oauth.invalid_client_id — The client ID does not have the shape this provider expects.	The pasted ID does not end with .apps.googleusercontent.com, or carries extra text.	Paste the client ID alone, with no space.
oauth.encryption_disabled	ENCRYPTION_KEY is not configured.	Configure the encryption key and restart the instance.
Google page redirect_uri_mismatch	The URI registered in the console differs from the one Mankomail sends, or PUBLIC_BASE_URL does not match the address in use.	Copy the Redirect URI again from the administration page into Authorized redirect URIs.
oauth.access_denied — You declined the authorisation at the provider.	The member cancelled or refused the consent.	Start the connection again and accept.
oauth.capability_not_granted — You did not grant every access requested.	A checkbox was unticked on Google's consent screen.	Start again and leave every box ticked.
oauth.invalid_state — The authorisation link expired or was already used.	More than ten minutes passed, the link was used twice, or another member is signed in to Mankomail in the same browser.	Start the connection again.
oauth.missing_refresh_token — The provider returned no refresh token.	Google returned no refresh token, so the connection would only last an hour.	Remove the application's access in the Google account, then reconnect.
oauth.exchange_failed	Google refused the authorisation code exchange (wrong client secret, for example).	Try again; if it persists, check the client ID and secret saved by the administrator.
credential.capability_missing — This action needs an extra access (Drive, Calendar…).	The step needs a capability the member never granted, or that was revoked.	Click the matching Connect … button in Connections.
google.insufficient_permissions	The scope was withdrawn on Google's side.	Reconnect the account in Connections.
google.auth_failed	Google refused the token (access revoked).	Reconnect the account in Connections.
google.not_found	The resource does not exist, or drive.file hides it because Mankomail did not create it.	Point the node to a file or folder Mankomail created, or that the member selected.
google.rejected	Google refused the operation itself (invalid parameter).	Check the node's parameters.
google.unavailable	Quota exceeded or transient outage.	Nothing: the step is retried automatically.
google.bad_locator	The pasted value is neither an identifier nor a recognised Google URL.	Paste the resource's identifier or its full URL.

For how failed steps are retried or replayed, see error handling.

Nodes that use this connection

• Drive — upload a file — google_drive.upload (capability drive)
• Drive — search files — google_drive.search (capability drive)
• Drive — create a folder — google_drive.create_folder (capability drive)
• Sheets — append a row — google_sheets.append (capability sheets)
• Calendar — create an event — google_calendar.create_event (capability calendar)
• Calendar — find free slots — google_calendar.find_free (capability calendar)