> For the complete documentation index, see [llms.txt](https://docs.planetcrust.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.planetcrust.com/human-connections/google/gmail.md).
# Gmail
Try @HumanBuy @Human SubscriptionJoin @Human Community
Put Gmail to Work with @Human Automations and @Human Agents
The Gmail Connection documents all Triggers, Actions and Query Operations available for creating automations via the Gmail API.
{% embed url="" %}
#### What can you do with the Gmail Connection?
* Connect to the Gmail API in a few clicks
* Use the related Gmail Operations (see below) in @Human Automations or @Human Agents
### Related Operations
#### Trigger Operations
**Email Received**
Triggers on: emails/emailReceived
Triggered when a new email is received in the user's Gmail inbox.
**Label Created**
Triggers on: labels/labelCreated
Triggered when a new label is created in the user's Gmail account.
**Draft Created**
Triggers on: drafts/draftCreated
Triggered when a new draft is created in the user's Gmail account.
#### Action Operations
[Action: Add Label to Email](/human-connections/google/gmail/action-add-label-to-email.md)
[Action: Delete Email](/human-connections/google/gmail/action-delete-email.md)
[Action: Create Draft Reply](/human-connections/google/gmail/action-create-draft-reply.md)
[Action: Send Email](/human-connections/google/gmail/action-send-email.md)
[Action: Remove Label From Conversation](/human-connections/google/gmail/action-remove-label-from-conversation.md)
[Action: Archive Email](/human-connections/google/gmail/action-archive-email.md)
[Action: Create Draft](/human-connections/google/gmail/action-create-draft.md)
[Action: Create Label](/human-connections/google/gmail/action-create-label.md)
[Action: Remove Label From Email](/human-connections/google/gmail/action-remove-label-from-email.md)
[Action: Reply to Email](/human-connections/google/gmail/action-reply-to-email.md)
#### Query Operations
[Query: Get Attachment by Filename](/human-connections/google/gmail/query-get-attachment-by-filename.md)
[Query: Find or Send Email](/human-connections/google/gmail/query-find-or-send-email.md)
[Query: Find Email](/human-connections/google/gmail/query-find-email.md)
### Related Automations
Example link
### Obtaining Access Credentials
This guide covers setting up Gmail for server-side (non-interactive) use via a Google service account with Domain-Wide Delegation (DWD). This allows @Human to send email **as any user in your Google Workspace domain** without requiring individual OAuth consent screens.
> **Important:** Domain-Wide Delegation is only available for **Google Workspace organisations** (paid). It is not supported on personal Gmail accounts.
#### **1. Google Cloud — Enable the Gmail API**
* Go to [**Google Cloud Console**](https://console.cloud.google.com/) and select (or create) your project.
* Navigate to **APIs & Services > Library**.
* Search for **Gmail API** and click **Enable**.
#### **2. Google Cloud — Create a Service Account**
* Navigate to **IAM & Admin > Service Accounts**.
* Click **+ Create Service Account**.
* Fill in a name, e.g. `at-human-gmail`, and click **Create and Continue**.
* Skip role assignment (roles are not needed for DWD) → click **Done**.
* Copy the **Unique ID (Client ID)** of the newly created service account — you will need it in Step 3.
#### **3. Google Workspace Admin — Grant Domain-Wide Delegation**
* Go to [**Google Workspace Admin Console**](https://admin.google.com/) → **Security > API controls > Domain-wide Delegation**. Direct link: `https://admin.google.com/ac/owl/domainwidedelegation`
* Click **+ Add new**.
* **Client ID**: paste the service account's **Unique ID (Client ID)** from Step 2.
* **OAuth Scopes**: add the following scope (grants full Gmail access):
```
https://mail.google.com/
```
> Use the full `https://mail.google.com/` scope. The broader `https://www.googleapis.com` will not work for Gmail API calls.
* Click **Authorize**.
> **Propagation delay**: DWD grants can take up to 15 minutes to propagate before they become effective.
#### **4. Google Cloud — Generate a Service Account Key**
* Go back to **IAM & Admin > Service Accounts** in Google Cloud Console.
* Click on your service account (`at-human-gmail`).
* Go to the **Keys** tab → **Add Key > Create new key**.
* Choose **JSON** format → click **Create**.
* The key file downloads automatically. Store it securely — it cannot be re-downloaded.
### Configuring Webhooks
**1. Enable Cloud Pub/Sub API**
* Go to [**Google Cloud Console**](https://console.cloud.google.com/).
* Select or create a **project**.
* Navigate to **APIs & Services > Library**.
* Search for **"Cloud Pub/Sub API"** and enable it.
**2. Create a Pub/Sub Topic**
* Navigate to **Pub/Sub > Topics**.
* Click **CREATE TOPIC**.
* Enter a **Topic ID** (e.g., `gmail-notifications`).
* Click **CREATE**.
**3. Configure Permissions**
* In the topic details, click **SHOW INFO PANEL** then **ADD PRINCIPAL**.
* Enter `gmail-api-push@system.gserviceaccount.com`.
* Assign the **"Pub/Sub Publisher"** role.
* Click **SAVE**.
**4. Create a Push Subscription**
* Navigate to **Pub/Sub > Subscriptions**.
* Click **CREATE SUBSCRIPTION**.
* Enter a **Subscription ID**.
* Select the **Topic** created in step 2.
* Set **Delivery type** to **Push**.
* Enter your **Endpoint URL**.
* Click **CREATE**.
**5. Register the Mailbox for Notifications**
* Call the Gmail API `users.watch` endpoint.
* In the request body, provide the `topicName`: `projects/{PROJECT_ID}/topics/{TOPIC_NAME}`.
* (Optional) Specify `labelIds` or `labelFilterAction`.
### Code (Apache v2.0): Service Connectivity and Metadata
```
{
"handle": "gmail-v1",
"status": "active",
"meta": {
"short": "Gmail",
"description": "Connect to Gmail API for sending, receiving, and managing emails.",
"icon": "gmail",
"tags": ["email", "google", "communication"]
},
"service": {
"baseURL": {
"value": "https://gmail.googleapis.com/gmail/v1"
},
"protocol": "https",
"contentType": "application/json",
"auth": {
"method": "google_service_account",
"params": {
"googleServiceAccount": {
"value": "{{serviceAccountJSON}}",
"placeholders": [
{
"name": "serviceAccountJSON",
"type": "string",
"description": "The full JSON key file content for the Google service account.",
"required": true,
"default": ""
}
]
},
"subject": {
"value": "{{subject}}",
"placeholders": [
{
"name": "subject",
"type": "string",
"description": "Email of the Workspace user to impersonate via domain-wide delegation (e.g. user@yourcompany.com). Leave empty if not using DWD.",
"required": false,
"default": ""
}
]
}
}
}
}
}
```
### Code (Apache v2.0): List of External Resources and Internal Mapping
```
[
{
"handle": "emails",
"meta": {
"short": "Emails",
"description": "Manage emails in the user's Gmail account"
},
"endpoint": {
"value": "users/{{userId}}/messages",
"placeholders": [
{
"name": "userId",
"type": "String",
"description": "The user's email address or unique identifier",
"required": true,
"default": ""
}
]
},
"operations": {
"list": {
"method": "GET",
"path": {
"value": ""
},
"queryParams": {
"includeSpamTrash": {
"value": "false"
},
"maxResults": {
"value": "50"
}
},
"bodyTemplate": {
"value": ""
}
},
"read": {
"method": "GET",
"path": {
"value": "{{id}}",
"placeholders": [
{
"name": "id",
"type": "String",
"description": "The unique identifier of the email",
"required": true,
"default": ""
}
]
},
"bodyTemplate": {
"value": ""
}
},
"create": {
"method": "POST",
"path": {
"value": "send"
},
"headers": {
"Content-Type": {
"value": "application/json"
}
},
"bodyTemplate": {
"value": "{\"raw\": \"{{raw}}\"}",
"placeholders": [
{
"name": "raw",
"type": "String",
"description": "The raw email content in base64url format",
"required": true,
"default": ""
}
]
}
},
"delete": {
"method": "DELETE",
"path": {
"value": "{{id}}",
"placeholders": [
{
"name": "id",
"type": "String",
"description": "The unique identifier of the email",
"required": true,
"default": ""
}
]
},
"bodyTemplate": {
"value": ""
}
}
},
"fields": [
{
"name": "id",
"type": "String",
"selector": [
"id"
],
"meta": {
"description": "The unique identifier of the email"
}
},
{
"name": "threadId",
"type": "String",
"selector": [
"threadId"
],
"meta": {
"description": "The unique identifier of the thread"
}
},
{
"name": "snippet",
"type": "String",
"selector": [
"snippet"
],
"meta": {
"description": "A short snippet of the email"
}
},
{
"name": "subject",
"type": "String",
"selector": [
"payload",
"headers",
"",
"value"
],
"meta": {
"description": "The subject of the email"
}
},
{
"name": "from",
"type": "String",
"selector": [
"payload",
"headers",
"",
"value"
],
"meta": {
"description": "The sender of the email"
}
},
{
"name": "to",
"type": "String",
"selector": [
"payload",
"headers",
"",
"value"
],
"meta": {
"description": "The recipient of the email"
}
},
{
"name": "date",
"type": "String",
"selector": [
"payload",
"headers",
"",
"value"
],
"meta": {
"description": "The date the email was sent"
}
}
],
"webhooks": [
{
"event": "emailReceived",
"path": "/webhooks/gmail/emails",
"payload": [
{
"name": "emailId",
"type": "String",
"selector": [
"message",
"id"
],
"meta": {
"description": "The unique identifier of the email"
}
},
{
"name": "threadId",
"type": "String",
"selector": [
"message",
"threadId"
],
"meta": {
"description": "The unique identifier of the thread"
}
},
{
"name": "snippet",
"type": "String",
"selector": [
"message",
"snippet"
],
"meta": {
"description": "A short snippet of the email"
}
}
]
}
]
},
{
"handle": "labels",
"meta": {
"short": "Labels",
"description": "Manage labels in the user's Gmail account"
},
"endpoint": {
"value": "users/{{userId}}/labels",
"placeholders": [
{
"name": "userId",
"type": "String",
"description": "The user's email address or unique identifier",
"required": true,
"default": ""
}
]
},
"operations": {
"list": {
"method": "GET",
"path": {
"value": ""
},
"bodyTemplate": {
"value": ""
}
},
"read": {
"method": "GET",
"path": {
"value": "{{id}}",
"placeholders": [
{
"name": "id",
"type": "String",
"description": "The unique identifier of the label",
"required": true,
"default": ""
}
]
},
"bodyTemplate": {
"value": ""
}
},
"create": {
"method": "POST",
"path": {
"value": ""
},
"headers": {
"Content-Type": {
"value": "application/json"
}
},
"bodyTemplate": {
"value": "{\"name\": \"{{name}}\", \"labelListVisibility\": \"{{labelListVisibility}}\", \"messageListVisibility\": \"{{messageListVisibility}}\"}",
"placeholders": [
{
"name": "name",
"type": "String",
"description": "The name of the label",
"required": true,
"default": ""
},
{
"name": "labelListVisibility",
"type": "String",
"description": "The visibility of the label in the label list",
"required": false,
"default": "labelShow",
"options": [
"labelShow",
"labelHide"
]
},
{
"name": "messageListVisibility",
"type": "String",
"description": "The visibility of the label in the message list",
"required": false,
"default": "show",
"options": [
"show",
"hide"
]
}
]
}
},
"update": {
"method": "PATCH",
"path": {
"value": "{{id}}",
"placeholders": [
{
"name": "id",
"type": "String",
"description": "The unique identifier of the label",
"required": true,
"default": ""
}
]
},
"headers": {
"Content-Type": {
"value": "application/json"
}
},
"bodyTemplate": {
"value": "{\"name\": \"{{name}}\", \"labelListVisibility\": \"{{labelListVisibility}}\", \"messageListVisibility\": \"{{messageListVisibility}}\"}",
"placeholders": [
{
"name": "name",
"type": "String",
"description": "The name of the label",
"required": false,
"default": ""
},
{
"name": "labelListVisibility",
"type": "String",
"description": "The visibility of the label in the label list",
"required": false,
"default": "",
"options": [
"labelShow",
"labelHide"
]
},
{
"name": "messageListVisibility",
"type": "String",
"description": "The visibility of the label in the message list",
"required": false,
"default": "",
"options": [
"show",
"hide"
]
}
]
}
},
"delete": {
"method": "DELETE",
"path": {
"value": "{{id}}",
"placeholders": [
{
"name": "id",
"type": "String",
"description": "The unique identifier of the label",
"required": true,
"default": ""
}
]
},
"bodyTemplate": {
"value": ""
}
}
},
"fields": [
{
"name": "id",
"type": "String",
"selector": [
"id"
],
"meta": {
"description": "The unique identifier of the label"
}
},
{
"name": "name",
"type": "String",
"selector": [
"name"
],
"meta": {
"description": "The name of the label"
}
},
{
"name": "type",
"type": "String",
"selector": [
"type"
],
"meta": {
"description": "The type of the label"
}
}
],
"webhooks": [
{
"event": "labelCreated",
"path": "/webhooks/gmail/labels",
"payload": [
{
"name": "labelId",
"type": "String",
"selector": [
"label",
"id"
],
"meta": {
"description": "The unique identifier of the label"
}
},
{
"name": "labelName",
"type": "String",
"selector": [
"label",
"name"
],
"meta": {
"description": "The name of the label"
}
}
]
}
]
},
{
"handle": "drafts",
"meta": {
"short": "Drafts",
"description": "Manage drafts in the user's Gmail account"
},
"endpoint": {
"value": "users/{{userId}}/drafts",
"placeholders": [
{
"name": "userId",
"type": "String",
"description": "The user's email address or unique identifier",
"required": true,
"default": ""
}
]
},
"operations": {
"list": {
"method": "GET",
"path": {
"value": ""
},
"bodyTemplate": {
"value": ""
}
},
"read": {
"method": "GET",
"path": {
"value": "{{id}}",
"placeholders": [
{
"name": "id",
"type": "String",
"description": "The unique identifier of the draft",
"required": true,
"default": ""
}
]
},
"bodyTemplate": {
"value": ""
}
},
"create": {
"method": "POST",
"path": {
"value": ""
},
"headers": {
"Content-Type": {
"value": "application/json"
}
},
"bodyTemplate": {
"value": "{\"message\": {\"raw\": \"{{raw}}\"}}",
"placeholders": [
{
"name": "raw",
"type": "String",
"description": "The raw email content of the draft in base64url format",
"required": true,
"default": ""
}
]
}
},
"update": {
"method": "PUT",
"path": {
"value": "{{id}}",
"placeholders": [
{
"name": "id",
"type": "String",
"description": "The unique identifier of the draft",
"required": true,
"default": ""
}
]
},
"headers": {
"Content-Type": {
"value": "application/json"
}
},
"bodyTemplate": {
"value": "{\"message\": {\"raw\": \"{{raw}}\"}}",
"placeholders": [
{
"name": "raw",
"type": "String",
"description": "The raw email content of the updated draft in base64url format",
"required": true,
"default": ""
}
]
}
},
"delete": {
"method": "DELETE",
"path": {
"value": "{{id}}",
"placeholders": [
{
"name": "id",
"type": "String",
"description": "The unique identifier of the draft",
"required": true,
"default": ""
}
]
},
"bodyTemplate": {
"value": ""
}
}
},
"fields": [
{
"name": "id",
"type": "String",
"selector": [
"id"
],
"meta": {
"description": "The unique identifier of the draft"
}
},
{
"name": "messageId",
"type": "String",
"selector": [
"message",
"id"
],
"meta": {
"description": "The unique identifier of the draft message"
}
},
{
"name": "messageThreadId",
"type": "String",
"selector": [
"message",
"threadId"
],
"meta": {
"description": "The thread ID of the draft message"
}
},
{
"name": "messageSnippet",
"type": "String",
"selector": [
"message",
"snippet"
],
"meta": {
"description": "A short snippet of the draft message content"
}
}
],
"webhooks": [
{
"event": "draftCreated",
"path": "/webhooks/gmail/drafts",
"payload": [
{
"name": "draftId",
"type": "String",
"selector": [
"draft",
"id"
],
"meta": {
"description": "The unique identifier of the draft"
}
},
{
"name": "messageId",
"type": "String",
"selector": [
"draft",
"message",
"id"
],
"meta": {
"description": "The ID of the message in the draft"
}
}
]
}
]
},
{
"handle": "threads",
"meta": {
"short": "Threads",
"description": "Manage email threads (conversation groups) in the user's Gmail account"
},
"endpoint": {
"value": "users/{{userId}}/threads",
"placeholders": [
{
"name": "userId",
"type": "String",
"description": "The user's email address or 'me'",
"required": true,
"default": ""
}
]
},
"operations": {
"list": {
"method": "GET",
"path": {
"value": ""
},
"queryParams": {
"includeSpamTrash": {
"value": "false"
},
"maxResults": {
"value": "50"
}
},
"bodyTemplate": {
"value": ""
}
},
"read": {
"method": "GET",
"path": {
"value": "{{id}}",
"placeholders": [
{
"name": "id",
"type": "String",
"description": "The thread identifier",
"required": true,
"default": ""
}
]
},
"bodyTemplate": {
"value": ""
}
},
"delete": {
"method": "DELETE",
"path": {
"value": "{{id}}",
"placeholders": [
{
"name": "id",
"type": "String",
"description": "The thread identifier",
"required": true,
"default": ""
}
]
},
"bodyTemplate": {
"value": ""
}
}
},
"fields": [
{
"name": "id",
"type": "String",
"selector": [
"id"
],
"meta": {
"description": "The unique identifier of the thread"
}
},
{
"name": "snippet",
"type": "String",
"selector": [
"snippet"
],
"meta": {
"description": "A short snippet of the thread"
}
},
{
"name": "historyId",
"type": "String",
"selector": [
"historyId"
],
"meta": {
"description": "The ID of the last history record that modified this thread"
}
}
]
},
{
"handle": "history",
"meta": {
"short": "History",
"description": "List the history of changes to the user's mailbox"
},
"endpoint": {
"value": "users/{{userId}}/history",
"placeholders": [
{
"name": "userId",
"type": "String",
"description": "The user's email address or 'me'",
"required": true,
"default": ""
}
]
},
"operations": {
"list": {
"method": "GET",
"path": {
"value": ""
},
"queryParams": {
"historyTypes": {
"value": "{{historyTypes}}"
},
"maxResults": {
"value": "100"
},
"startHistoryId": {
"value": "{{startHistoryId}}"
}
},
"bodyTemplate": {
"value": ""
}
}
},
"fields": [
{
"name": "id",
"type": "String",
"selector": [
"id"
],
"meta": {
"description": "The mailbox history record ID"
}
},
{
"name": "messagesAdded",
"type": "String",
"selector": [
"messagesAdded"
],
"meta": {
"description": "Messages added to the mailbox in this history record"
}
},
{
"name": "messagesDeleted",
"type": "String",
"selector": [
"messagesDeleted"
],
"meta": {
"description": "Messages deleted from the mailbox in this history record"
}
},
{
"name": "labelsAdded",
"type": "String",
"selector": [
"labelsAdded"
],
"meta": {
"description": "Labels added to messages in this history record"
}
},
{
"name": "labelsRemoved",
"type": "String",
"selector": [
"labelsRemoved"
],
"meta": {
"description": "Labels removed from messages in this history record"
}
}
]
},
{
"handle": "attachments",
"meta": {
"short": "Message Attachments",
"description": "Retrieve attachments from Gmail messages"
},
"endpoint": {
"value": "users/{{userId}}/messages/{{messageId}}/attachments",
"placeholders": [
{
"name": "userId",
"type": "String",
"description": "The user's email address or 'me'",
"required": true,
"default": ""
},
{
"name": "messageId",
"type": "String",
"description": "The ID of the message containing the attachment",
"required": true,
"default": ""
}
]
},
"operations": {
"read": {
"method": "GET",
"path": {
"value": "{{id}}",
"placeholders": [
{
"name": "id",
"type": "String",
"description": "The attachment identifier",
"required": true,
"default": ""
}
]
},
"bodyTemplate": {
"value": ""
}
}
},
"fields": [
{
"name": "attachmentId",
"type": "String",
"selector": [
"attachmentId"
],
"meta": {
"description": "The ID of the attachment"
}
},
{
"name": "size",
"type": "Number",
"selector": [
"size"
],
"meta": {
"description": "The size of the attachment in bytes"
}
},
{
"name": "data",
"type": "String",
"selector": [
"data"
],
"meta": {
"description": "The attachment data encoded in base64url"
}
}
]
},
{
"handle": "profile",
"meta": {
"short": "User Profile",
"description": "Retrieve the authenticated user's Gmail profile"
},
"endpoint": {
"value": "users/{{userId}}/profile",
"placeholders": [
{
"name": "userId",
"type": "String",
"description": "The user's email address or 'me'",
"required": true,
"default": ""
}
]
},
"operations": {
"read": {
"method": "GET",
"path": {
"value": ""
},
"bodyTemplate": {
"value": ""
}
}
},
"fields": [
{
"name": "emailAddress",
"type": "String",
"selector": [
"emailAddress"
],
"meta": {
"description": "The user's email address"
}
},
{
"name": "messagesTotal",
"type": "Number",
"selector": [
"messagesTotal"
],
"meta": {
"description": "The total number of messages in the mailbox"
}
},
{
"name": "threadsTotal",
"type": "Number",
"selector": [
"threadsTotal"
],
"meta": {
"description": "The total number of threads in the mailbox"
}
},
{
"name": "historyId",
"type": "String",
"selector": [
"historyId"
],
"meta": {
"description": "The ID of the mailbox's current history record"
}
}
]
}
]
```
Try @HumanBuy @Human SubscriptionJoin @Human Community
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.planetcrust.com/human-connections/google/gmail.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.