Gmail

Gmail Connection

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.

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

Action: Delete Email

Action: Create Draft Reply

Action: Send Email

Action: Remove Label From Conversation

Action: Archive Email

Action: Create Draft

Action: Create Label

Action: Remove Label From Email

Action: Reply to Email

Query Operations

Query: Get Attachment by Filename

Query: Find or Send Email

Query: Find Email

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 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 → 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.

• 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 [e-mail].

• 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. [e-mail]). 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"
        }
      }
    ]
  }
]