Skip to main content

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 address
  • subject — Search by email subject
  • has:attachment — Only return emails with attachments
  • filename — 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 messages
  • gmail/v1/users/me/messages/send — Send a message (raw format)
  • gmail/v1/users/me/labels — Manage custom labels
  • gmail/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}}"
}