Gmail — Connect

Gmail — Connect

Type: gmail-connect  ·  Package: Gmail v1.0.4  ·  Output: ZoanGmailSession

Opens an authenticated session with Gmail. It is the package’s required starting point: every other activity (send, search, reply, label…) works on this session, which represents access to a specific mailbox.

How it works

It authenticates with a Zoan Cloud Google OAuth connection (or a service account) and opens the session on the mailbox. There are two ways to use it:

• With body: the activities you place inside inherit the session automatically and run on that mailbox; when the block ends (also if something inside fails), the session closes by itself.
• Without body: it returns the session as output; store it in a variable, pass it through the session parameter to the other activities and close it at the end with Gmail — Close.

When connecting, it reads the mailbox profile from Gmail to learn its address (the sender of the emails you send). So if the authorization doesn’t work, the error shows up here and not halfway through the process.

Authentication modes (authType)

Mode	What you need	When to use it
oauth (default)	A Google OAuth connection in credential, authorized with the mailbox account.	A person’s account, or a team mailbox someone can authorize.
service-account	A service account’s JSON key stored as a credential in serviceAccount, and the mailbox in impersonateUser.	Google Workspace, unattended processes and several mailboxes in the domain without each person’s consent.

With a service account, the Google Workspace administrator must authorize the service account’s client ID under domain-wide delegation with the https://mail.google.com/ scope, which is the one the activity requests. It does not work with personal Gmail accounts (@gmail.com).

The OAuth token is taken at connect time

In oauth mode the session uses the token the connection had when it connected; Zoan Cloud renews it for later connections, but not inside a session that is already open, and Google tokens last about one hour. In long processes, work in batches and connect for each batch. In service-account mode the token renews itself.

Required parameters

None. In practice you need credential (oauth mode) or serviceAccount + impersonateUser (service-account mode).

Optional parameters

Parameter	Type	Default	Description
authType	string	"oauth"	Authentication mode: oauth or service-account. The Designer shows only the fields of the chosen mode.
credential	credential	—	oauth mode: Zoan Cloud Google OAuth connection. Pick it in the Designer’s selector or write credential("key-name").
serviceAccount	credential	—	service-account mode: Zoan Cloud credential holding the service account key’s full JSON.
impersonateUser	string	—	service-account mode: email of the Workspace mailbox to work on (e.g. billing@example.com). Required in that mode.

Sub-flows

body optional

Activities to run inside the session. They inherit the session automatically and it closes when they finish.

Output

Returns a ZoanGmailSession only when you don’t use body; with body the activity returns nothing (the session is inherited). The session exposes:

Property	Type	Content
EmailAddress	string	Address of the connected mailbox (the connection’s user or the impersonateUser).
UserId	string	Always me: the authenticated mailbox.

Common errors

Message	Cause and fix
'credential' does not contain a valid access_token. Check the OAuth Connection in Zoan Cloud.	The connection returned no token: it is pending authorization or was revoked. Check in Zoan Cloud that it is Connected.
'serviceAccount' must reference a Zoan Cloud credential containing the service account JSON key.	The serviceAccount credential is empty.
The service account credential is not a valid Google service account JSON key. …	The stored value is not the full JSON key. Download it again from Google Cloud and paste the whole file.
Gmail with a service account requires 'impersonateUser' …	impersonateUser is missing in service-account mode.
unauthorized_client	Domain-wide delegation is not set up for that service account or does not include the https://mail.google.com/ scope.
Request had insufficient authentication scopes.	The OAuth connection lacks Gmail permissions. Edit the connection, select the Gmail scopes and authorize it again.

Example

Gmail — Connect   credential = credential("gmail-support")
 └─ body:
      Gmail — Get emails   query = "is:unread in:inbox"   → output: newEmails
      For each   email in newEmails
       └─ Gmail — Reply   id = email["id"]   body = "We received your message and will get back to you shortly."

With a service account, without body:

Gmail — Connect   authType = service-account   serviceAccount = credential("google-sa")   impersonateUser = "billing@example.com"   → output: mbx
Gmail — Get emails   session = mbx   query = "has:attachment subject:invoice"   → output: invoices
Gmail — Close   session = mbx

Powerful search

Get emails uses the same syntax as Gmail’s search box (is:unread, from:supplier@example.com, has:attachment, after:2026/01/01).

Related activities

• Gmail — Send — send an email.
• Gmail — Get emails — search emails.
• Gmail — Close — close the session (no-body mode).
• All Gmail activities