Gmail Activities

Version: 1.0.4 · ID: zoan-packages-gmail · Author: Zoan Software

The Gmail package sends, searches, reads and organizes email in a Gmail or Google Workspace mailbox through Zoan Cloud OAuth2 connections. It automates email without an installed client, so it works the same in attended and unattended robots.

Concept 1: authentication

Connect supports two modes:

Mode	What you need
OAuth (default)	A Zoan Cloud Google OAuth connection authorized with the mailbox account: `credential = credential("gmail-support")`.
Service account	The JSON key stored as a credential, the mailbox in `impersonateUser`, and domain-wide delegation authorized in Google Workspace with the `https://mail.google.com/` scope. Ideal for unattended processes on mailboxes of your domain.

Gmail scopes the OAuth connection needs:

Scope	Covers
`https://www.googleapis.com/auth/gmail.modify`	The whole package except permanent deletion: search, read, send, reply, forward, label, archive, move to trash.
`https://mail.google.com/`	Everything, including Delete with `permanent = true`.

Concept 2: the session

Connect opens a session (ZoanGmailSession) on a mailbox:

With body: the activities inside inherit it, and it closes by itself when they finish.
Without body: store it in a variable, pass it through session and close it with Close.

In OAuth mode the session uses the token that was valid when it connected, which lasts about one hour: in long processes, work in batches and connect once per batch.

Concept 3: an email is a dictionary

Get emails and Get email by ID return each email as a Dictionary<string,object> with the keys id, threadId, from, to, cc, subject, date, snippet, labels, unread and, with the body, body, bodyHtml and attachments (details in Get emails). Read each value by key: email["subject"]. Headers (from, to, date) come exactly as the sender wrote them, with name and address.

An email’s id does not change when you label, archive or mark it: you can chain several activities on the same id.

Concept 4: labels instead of folders

In Gmail an email is not “in” a folder: it has labels. The inbox is the INBOX label, unread emails carry UNREAD. That’s why Archive removes INBOX, Mark read/unread adds or removes UNREAD, and Apply label / Remove label classify. Look up names and IDs with Get labels.

Activities

Activity	Type	Output	Description
Gmail — Connect	`gmail-connect`	`ZoanGmailSession`	Opens an authenticated Gmail session (OAuth or service account)
Gmail — Send	`gmail-send`	`string`	Sends an email from the session’s account
Gmail — Reply	`gmail-reply`	`string`	Replies to an existing email, keeping the thread
Gmail — Forward	`gmail-forward`	`string`	Forwards an existing email to new recipients, with its attachments
Gmail — Get emails	`gmail-get-emails`	`List<Dictionary<string,object>>`	Searches emails with Gmail’s syntax and returns a list
Gmail — Get email by ID	`gmail-get-email`	`Dictionary<string,object>`	Gets a full email by its ID (body, headers and attachments)
Gmail — Download attachments	`gmail-download-attachments`	`List<string>`	Downloads an email’s attachments to a folder
Gmail — Mark read/unread	`gmail-mark-read`	—	Marks an email as read or unread
Gmail — Apply label	`gmail-apply-label`	—	Applies one or more labels to an email (by name or ID)
Gmail — Remove label	`gmail-remove-label`	—	Removes one or more labels from an email (by name or ID)
Gmail — Archive	`gmail-archive`	—	Archives an email (takes it out of the inbox) or moves it back
Gmail — Get labels	`gmail-get-labels`	`List<Dictionary<string,object>>`	Lists the mailbox labels
Gmail — Delete	`gmail-delete`	—	Moves an email to Trash (or deletes it permanently)
Gmail — Close	`gmail-close`	—	Closes a Gmail session

Full process example

Gmail — Connect   credential = credential("gmail-invoices")
 └─ body:
      Gmail — Get emails   query = "in:inbox is:unread has:attachment subject:invoice"   → output: pending
      For each   email in pending
       └─ Gmail — Download attachments   id = email["id"]   folder = "C:\invoices\inbox"
          Gmail — Reply         id = email["id"]   body = "We received your invoice and will record it in the next few days."
          Gmail — Apply label   id = email["id"]   labels = "Processed"
          Gmail — Archive       id = email["id"]