Gmail

What it is

A Gmail connection authorizes Honeybase against one mailbox. As with Google Sheets there are three ways to authenticate, and the choice decides who owns the access — but Gmail adds a second decision the Sheets connection does not have: which mailbox the connection acts as.

note

This release adds the connection itself. Gmail workflow nodes are not available yet, so a Gmail connection cannot be selected in the Send Email node — that node still needs an Email (sending) connection.

Before you start

Decide between a person's access and a service account. A connection authorized by signing in acts as that person, sees exactly the mail they can see, and stops working when their account is disabled. A service account has its own identity but no mailbox of its own — on Google Workspace it must be granted domain-wide delegation and told which mailbox to act as.

Personal @gmail.com accounts cannot use the service account option at all; domain-wide delegation is a Workspace feature.

Setup fields

These are the fields the guided setup collects — both the Add integration form and the setup card Barry raises in chat. Additional settings live on the connection's settings page once it exists.

Connection settings

Field	Type	Required	Secret	Notes
name	Text	Yes	No	Display name for this connection. This is what you pick from in a workflow node.
authMethod	Choice	Yes	No	How Honeybase authenticates to Google — sign in through Honeybase, use your own OAuth client, or use a Workspace service account.

Credentials

This integration has 3 credential options. You supply the fields for the one you pick.

Sign in with Google through Honeybase

The quickest option. You approve access in a Google consent screen and Honeybase holds the OAuth client; nothing to create in Google Cloud. The scopes are fixed to the set Honeybase is verified for and cannot be edited per connection.

No credential fields are collected for this option in the guided setup.

Your own Google OAuth client

Your organization's own OAuth client, so consent, branding and revocation stay in your Google Cloud project. Access is still granted by a person signing in, and acts as that person's mailbox.

Field	Type	Required	Secret	Notes
auth.clientId	Text	Yes	No	The OAuth client ID from your Google Cloud project, ending in .apps.googleusercontent.com.
auth.clientSecret	Password	Yes	Yes	The OAuth client secret issued alongside that client ID, from the same Credentials page.

Google service account

A Workspace identity that belongs to no one's account, for unattended automation that must survive someone leaving. It requires domain-wide delegation and a mailbox to impersonate; it is only available on Google Workspace, not on personal Gmail.

Field	Type	Required	Secret	Notes
auth.serviceAccountJson	JSON	Yes	Yes	The service account key file, pasted whole. Google gives you this JSON once, at key creation, and will not show it again.
auth.impersonatedUser	Text	Yes	No	The mailbox this connection acts as, e.g. ops@yourdomain.com. Required — a service account has no mailbox of its own. It is stored with the key but deliberately shown in full rather than masked, because it is the only thing narrowing a domain-wide delegation grant to a single mailbox.

Configured after the connection exists

The guided setup does not ask for OAuth scopes. Open the connection on the Integrations page to change them.

Sign in through Honeybase

Choose it, approve the Google consent screen, and you are done. Honeybase requests read/label/draft access plus send (gmail.modify and gmail.send); it never requests permanent delete or settings access.

These are restricted scopes under Google's OAuth policy, which is why the scope list is fixed for this option: it is tied to the verification Honeybase's own OAuth client carries, not to a per-connection setting. If you need a different scope set, use your own OAuth client.

Your own OAuth client

Use this when consent should show your organization's name, when policy requires the OAuth client to live in your own Google Cloud project, or when you want a narrower scope set than the default.

1. In the Google Cloud console, pick a project and enable the Gmail API under APIs & Services → Library.
2. Configure the OAuth consent screen for your organization. Gmail scopes are restricted, so a production app serving users outside your organization needs Google's verification, including an annual security assessment.
3. Under APIs & Services → Credentials, choose Create Credentials → OAuth client ID, type Web application.
4. Add the redirect URI Honeybase shows on the setup form to Authorized redirect URIs.
5. Copy the client ID and client secret.

Service account with domain-wide delegation

Available on Google Workspace only.

1. In IAM & Admin → Service Accounts, create a service account and note its client ID (a long number, on the service account's details page).
2. On its Keys tab, choose Add Key → Create new key → JSON. The file downloads once and cannot be retrieved again.
3. In the Google Workspace admin console, go to Security → Access and data control → API controls → Domain-wide delegation and add the service account's client ID, granting it the Gmail scopes the connection uses.
4. Paste the whole JSON key into the setup form and enter the mailbox to act as.

Step 3 is the one people miss. Without it Google rejects the connection with unauthorized_client, which says nothing on its own — Honeybase turns that into the specific instruction above, naming the client ID to grant.

warning

A domain-wide delegation grant reaches every mailbox in the domain. The mailbox you enter is the only thing narrowing it to one, which is why Honeybase shows that address in full instead of masking it: a change from one mailbox to another must be visible to whoever reviews the connection.

Testing the connection

Test Connection does more than check that a token can be minted. It calls Gmail's profile endpoint, which is the only thing that proves the Gmail API is actually enabled on the project and — for a service account — that domain-wide delegation was really granted for these scopes. It reports back the mailbox it authenticated as, so you can confirm you connected the account you meant to.

Scopes

After you authorize, Honeybase records the scopes Google actually granted, rather than assuming it received everything it asked for. When a later call is refused, the error names what the connection holds and what the operation needed, instead of telling you to reconnect and hope.

Widening scopes later requires authorizing the connection again.