Gmail
This page provides information on how to connect to Gmail. This integration enables sending emails, fetching messages, searching through inboxes, managing contacts, and more using your Gmail account.
Connect Gmail
To connect to Gmail, you need to authenticate using your Google account. When prompted, sign in with your Gmail credentials and grant access to the required permissions. Once authenticated, the integration can access and manage your emails and contacts.
Query Gmail
The following section is a reference guide that provides a description of the available commands with their parameters to create Gmail queries.
Send Emails
Sends an email from your Gmail account to one or more recipients. You can include a subject, message body, attachments, and custom headers.
To Recipients string | array
Email address(es) of the intended recipients. You can provide a single email or a comma-separated list.
{{ toInput.text }}
From string
The sender’s email address. Usually, this will be your authenticated Gmail address.
Subject string
The subject line of the email. This text appears as the title in the recipient's inbox.
Message Content string
The main body of the email. Supports both plain text and HTML content. When using HTML, ensure the MIME type is correctly set to text/html to enable proper rendering of formatting like bold, links, and images.
<p>Hello {{nameInput.text}},</p>
<p>Thank you for your interest in our product.</p>
<p>Best regards,<br />The Team</p>
Attachments array
A list of file objects to be attached to the email. Each object must include the file name, MIME type, and base64-encoded content of the file. URLs are not supported.
Additional Headers object
Optional custom headers such as "Reply-To", "CC", or "BCC". Provide as a JSON object representing MIME-style headers, using key-value pairs.
{
"Reply-To": "another@example.com",
"CC": "team@example.com"
}
Get Email by ID
Retrieves a specific email message using a user ID and a message ID.
User ID string
The Gmail user ID. For the authenticated user, use the special value me
.
If accessing another user's mailbox (with proper authorization and domain-wide delegation in Google Workspace), the user ID is typically their full email address.
To find your Gmail user ID:
-
For most use cases, especially personal Gmail accounts, use
me
. -
For service or delegated accounts, use the full email address associated with the account, such as:
john.doe@example.com
Message ID string
The unique identifier of the email message. You can get this from results returned by the Search for Email command or from the metadata in a list of messages.
In the Gmail web interface, you can find the message ID in the URL when viewing an individual email. It appears after /mail/u/0/#all/
or /mail/u/0/#inbox/
in the URL.
https://mail.google.com/mail/u/0/#inbox/**179f4e2e8d9f3a3b**
Search for Email
Searches a user's mailbox using Gmail's advanced search syntax and supports pagination for large result sets.
Email Filter Formula string
A Gmail-style search query used to filter emails. This leverages Gmail’s advanced search operators to narrow results by sender, subject, attachments, date, and more.
Common filters include:
from
— Filter by sender email addresssubject
— Search by email subjecthas:attachment
— Only return emails with attachmentsfilename
— Match specific attachment file names
Examples:
- Retrieve all emails from a specific sender:
from:boss@example.com
- Search for emails with "invoice 2024" in the subject line:
subject:(invoice 2024)
- Find emails with PDF attachments:
has:attachment filename:pdf
Pagination Parameters object
Optional parameters to control the number of results and handle paginated responses. This is useful when processing large volumes of email data.
-
maxResults
number
: The maximum number of email messages to return in a single request. -
pageToken
string
: A token to retrieve the next page of results. This is returned in the response of a previous query when more results are available. -
includeSpamTrash
boolean
: Whether to include emails from the Spam and Trash folders.
Example: Retrieve 20 emails from the inbox, including spam and trash.
{
"maxResults": 20,
"includeSpamTrash": true
}
Delete Email
Deletes a specific email message by ID.
User ID string
The Gmail user ID that identifies the mailbox containing the message. For most use cases, especially when working with the authenticated account, use the special value:
me
If you're accessing another user's mailbox in a Google Workspace environment (with domain-wide delegation), provide the user's full email address.
Examples:
For the authenticated user:
me
For a delegated account:
john.doe@example.com
Message ID string
The unique identifier of the email message to be deleted. You can obtain this from the results of the Search for Email command or from the metadata returned when listing or reading messages.
To locate the Message ID manually in Gmail:
-
Open the email in the Gmail web interface.
-
Look at the browser URL — the message ID appears after
/mail/u/0/#inbox/
or/mail/u/0/#all/
.
Example URL:
https://mail.google.com/mail/u/0/#inbox/179f4e2e8d9f3a3b
Deleting a message using this command is permanent unless the email was previously moved to the Trash. If the email is in the Trash folder, it will be permanently removed.
Create a Contact
Adds a new contact to your Google Contacts.
Given Name string
The first name of the contact. Displayed in contact listings.
Family Name string
The last name or surname of the contact.
Email string
The primary email address for the contact.
Additional Fields object
Optional metadata to enrich the contact with more details. This field accepts key-value pairs to define properties such as phone number, company, job title, and more.
Example:
{
"phoneNumber": "+1-555-123-4567",
"organization": "Acme Corp",
"jobTitle": "Marketing Manager",
"notes": "Met at the 2024 tech conference",
"birthday": "1985-07-15",
"address": "123 Main St, Springfield, IL"
}
Get Contact by Resource Name
Fetches a specific contact from Google Contacts using its unique resource name.
Resource Name string
The resource name is the unique identifier assigned to each contact in the Google People API. It is required to retrieve full details of a specific contact.
Resource names follow this format:
people/cXXXXXXXXXXXXXXX
How to obtain the resource name:
-
From the Create a Contact command response — it returns the resourceName of the newly created contact.
-
From the Search for Contact command — each contact entry in the response includes a resourceName field.
Search for Contact
Searches your Google Contacts for entries that match a given text query, such as a name, email address, or phone number.
Search Term string
A text string used to look up contacts. The search is performed across multiple fields, including given name, family name, email addresses, organization names, and phone numbers.
You can provide partial or full values to perform flexible matching.
Examples:
"john.doe"
"Acme Inc."
"555-1234"
Delete Contact
Deletes a contact from your Google Contacts.
Resource Name string
The unique ID of the contact to delete, such as people/c0987654321
.
You can get this from a previous "Search for Contact" or "Create a Contact" response.
Deleting a contact is permanent and cannot be undone.
Create Draft
Creates a draft email message. You can later update or send it using Gmail.
To Recipients string | array
The recipients of the draft message. Accepts a single email or a comma-separated list of email addresses. You may also bind this to widget values.
{{ recipientsInput.text }}
From string
The sender's Gmail address. Normally, this will match the authenticated account.
Subject string
The subject line of the email draft. Appears as the email title in the inbox preview.
{{ subjectInput.text }}
Message Content string
The body content of the draft email. You can use plain text or rich HTML. Ideal for pre-filling email content for user edits.
{{ draftBodyInput.value }}
Attachments array
An array of files to be attached. Each file should be defined with name, content type, and base64-encoded content.
[
{
"filename": "invoice.pdf",
"mimeType": "application/pdf",
"data": "base64string..."
}
]
Additional Headers object
Custom headers such as CC, BCC, or Reply-To. Use a key-value object.
{
"CC": "cc@example.com",
"BCC": "hidden@example.com"
}
Custom Action
Allows you to perform advanced or unsupported operations by directly making calls to the Gmail API using HTTP methods. This is useful when you need to use a Gmail API endpoint that is not covered by predefined commands.
Method string
The HTTP method to use for the request. Example values: "GET"
, "POST"
, "PATCH"
, "DELETE"
.
Endpoint string
The relative Gmail API endpoint you want to call.
Example endpoints:
gmail/v1/users/me/messages
— List messagesgmail/v1/users/me/messages/send
— Send a message (raw format)gmail/v1/users/me/labels
— Manage custom labelsgmail/v1/users/me/settings/filters
— Manage email filters
Headers object
A set of custom headers required by the Gmail API. Often includes content-type and authorization.
{
"Content-Type": "application/json"
}
Params object
Query parameters to be passed in the URL. These control filtering, limits, pagination, etc.
{
"maxResults": 5,
"q": "from:notifications@example.com"
}
Body object
The request body (for POST/PATCH methods). Format should match what the endpoint expects.
Example body to send a raw MIME email:
{
"raw": "{{base64EmailContent}}"
}