Skip to main content
Learn how to connect Engini to Gmail. Using Engini’s Gmail activities, you can check for new and sent emails, get emails and their attachments, send and reply to emails (with attachments), create and send drafts, move emails between labels, mark emails as read or unread, delete emails, list your labels, and send custom requests to the Gmail API. To get started with the gmail app, create an free account at Google.com or use your organizational google mailbox.

Getting Started with Gmail

Prerequisites

  • An Gmail account.

Add a connection to Gmail in Engini

  1. Enter your Engini account at https://app.engini.io.
  2. Navigate to Connections page by clicking on the Connections on the left sidebar or by clicking here. Engini - Connections page
  3. Click on the “New Integration” option located at the top bar. Engini - New Integration button
  4. Choose Gmail option from the available applications. Gmail - Choose Application
  5. Enter the following details in the “New Integration” form and press Save:
Note : There are two different authentication methods available, and the required fields differ depending on the option you choose. Please follow the relevant instructions based on your selected method.

OAuth2

This method uses a predefined authentication flow. You don’t need to provide a Client Id or Client Secret, you simply sign in using your account. Gmail - OAuth2 connection
  1. Connection name - Choose a unique identifier for the connection within Engini.
  2. Authentication Method - Select OAuth2.
  3. Sign in with Google - Click the “Sign in with Google” button and choose the Google account you want to connect.
  4. Save - Click on the Save button to save the connection.

Custom OAuth2

This method requires you to configure your own OAuth2 credentials. You must provide both a valid Client Id and Client Secret obtained from your Google Cloud Console project. Gmail - Custom OAuth2 connection
  1. Connection name - Choose a unique identifier for the connection within Engini.
  2. Authentication Method - Select Custom OAuth2 when connecting to Google services using a custom OAuth client. To learn more about this authentication, enter here.
  3. Callback URL - A read-only field that shows the address Google sends you back to after you sign in (https://webhooks.engini.io/api/auth/OAuthRedirectUrl). Click the copy button next to it, then add this address under Authorized redirect URIs in the OAuth client you create in your Google Cloud console. Do this before you enter the Client Id and Client Secret, so that the sign-in works.
  4. Client Id - Enter the Client Id from the OAuth 2.0 credentials in the Google Cloud project we created.
  5. Client Secret - Enter the Client Secret from the same set of OAuth 2.0 credentials in the Google Cloud project.
  6. Sign in with Google - Click Sign in with Google and log in with the Google account used to create the project in Google Cloud. This ensures access to the correct OAuth credentials and permissions.
  7. Save - Click on the Save button to save the connection.

Trigger

Check for new emails

The trigger monitors the mailbox, listening for new emails sent to the connected mailbox at scheduled intervals as defined. Gmail - Check for new emails trigger
  1. Starting (UTC) - Select the start date and time for the scheduled trigger. The date defaults to today and the time to 00:00.
  2. Recur every - Enter how often the trigger checks for new emails and choose the unit: Minute, Hour, Day, Week or Month. The default is 15 minutes. The shortest interval you can set depends on your Engini plan (15 minutes by default). If you set a shorter one, Engini shows a warning that the interval is below the minimum allowed on your plan. Below these fields, Next Run at shows when the trigger will run next, in UTC and in your local time.
  3. Add time frame - Click Add time frame to limit the hours in which the trigger runs, then select the From and To times of the time frame. For example, set the trigger to run every 15 minutes between 8 AM and 5 PM, so it stays idle outside those hours.
  4. Add Filter - Click Add Filter to define conditions that narrow down the emails the trigger returns. You can filter by Label, To, From, Subject, Importance, Starred, Has Attachment and Include Attachment. After you select a connection, Label lists the labels of that Gmail mailbox. To learn more about using filters, click here.
Each new email is passed to the next steps with these properties:
  • attachments - The files attached to the email. Each attachment has:
    • Attachment Id - The Id of the attachment. Use it with the Get Attachment action to get the file.
    • Filename - The name of the file.
    • Size - The size of the file, in bytes.
    • Content (base64) - The content of the file, in base64.
  • Body - The email body as plain text when the email has a plain-text part, otherwise as HTML. Empty if the email has no body.
  • CC - The email’s CC header, as text with the addresses separated by commas.
  • CC emails - The addresses extracted from the CC header.
  • From - The sender as it appears in the From header, for example Name <address>.
  • From email - The sender’s email address, extracted from the From header.
  • Label Ids - The Gmail label Ids of the email, for example INBOX or UNREAD.
  • Message Id - The Gmail message Id. Use it in later actions.
  • Received Datetime - When Gmail received the email, in UTC.
  • Size Estimate - Gmail’s estimated size of the email, in bytes.
  • Snippet - Gmail’s short preview text of the email.
  • Subject - The email subject. Empty if there is none.
  • Thread Id - The Gmail thread Id.
  • To - The email’s To header, as text with the addresses separated by commas.
  • To emails - The addresses extracted from the To header.

Check for sent emails

The trigger monitors the connected mailbox and fires for each email you send from it, at scheduled intervals as defined. Gmail adds the SENT label to every sent email automatically, so this trigger has no Label filter. Gmail - Check for sent emails trigger
  1. Starting (UTC) - Select the start date and time for the scheduled trigger. The date defaults to today and the time to 00:00.
  2. Recur every - Enter how often the trigger checks for sent emails and choose the unit: Minute, Hour, Day, Week or Month. The default is 15 minutes. The shortest interval you can set depends on your Engini plan (15 minutes by default). If you set a shorter one, Engini shows a warning that the interval is below the minimum allowed on your plan. Below these fields, Next Run at shows when the trigger will run next, in UTC and in your local time.
  3. Add time frame - Click Add time frame to limit the hours in which the trigger runs, then select the From and To times of the time frame. For example, set the trigger to run every 15 minutes between 8 AM and 5 PM, so it stays idle outside those hours.
  4. Add Filter - Click Add Filter to define conditions that narrow down the sent emails the trigger returns. You can filter by To, From, Subject, Importance, Starred, Has Attachment and Include Attachment. To learn more about using filters, click here.
Each sent email is passed to the next steps with these properties:
  • attachments - The files attached to the email. Each attachment has:
    • Attachment Id - The Id of the attachment. Use it with the Get Attachment action to get the file.
    • Filename - The name of the file.
    • Size - The size of the file, in bytes.
    • Content (base64) - The content of the file, in base64.
  • Body - The email body as plain text when the email has a plain-text part, otherwise as HTML. Empty if the email has no body.
  • CC - The email’s CC header, as text with the addresses separated by commas.
  • CC emails - The addresses extracted from the CC header.
  • From - The sender as it appears in the From header, for example Name <address>.
  • From email - The sender’s email address, extracted from the From header.
  • Label Ids - The Gmail label Ids of the email, for example INBOX or UNREAD.
  • Message Id - The Gmail message Id. Use it in later actions.
  • Received Datetime - When Gmail received the email, in UTC.
  • Size Estimate - Gmail’s estimated size of the email, in bytes.
  • Snippet - Gmail’s short preview text of the email.
  • Subject - The email subject. Empty if there is none.
  • Thread Id - The Gmail thread Id.
  • To - The email’s To header, as text with the addresses separated by commas.
  • To emails - The addresses extracted from the To header.

Actions

Filling in fields: Click an empty field to open a tooltip that lists the properties returned by the steps before it (the trigger and earlier actions), and select the one you need. You can also type a static value, a number or a string. Enclose strings in single quotes (‘). For more about managing activity data, click here. Note: Create Draft, Send Draft, Mark Email as Read, Mark Email as Unread, Delete Email and Move Email work with the OAuth2 authentication method. A connection that uses Custom OAuth2 does not have the Google permissions they need, and they return a permission error (403).

Create Draft

Creates a draft in your Gmail account without sending it. Give Engini the recipient, subject and body, and it builds the email itself. The draft stays in your Drafts folder, and the action returns the draft details, including the draft Id that you can use in the Send Draft action. Gmail - Create Draft action
  1. To - Required. The email address of the recipient, for example name@company.com. Select it from the tooltip, or type it as a static value in single quotes.
  2. Subject - Required. The subject line of the draft, for example 'Your order has shipped'. You can type a static text or combine it with a property from a previous step.
  3. Body - Required. The text of the draft. Click the empty field to open a window where you write the body, and use the tooltip inside it to insert properties from previous steps.
  4. Add Field - Click Add Field to add and populate additional fields for the selected activity. To learn more about managing activity data, click here.
All of the following are optional and are added through Add Field:
  • Cc - People who receive a copy, for example name@company.com. Separate several addresses with a comma or a semicolon.
  • Send As - The address the draft is sent from. Pick it from the list of the addresses your Gmail account can send as (the “Send mail as” addresses in Gmail). Leave it empty to send from the connected account. The address must already be set up in Gmail under Settings > Accounts > “Send mail as”; otherwise the action fails and nothing is sent.
  • Bcc - People who receive a blind copy. Separate several addresses with a comma or a semicolon.
  • Content Type - Choose Text (the default) to create the draft as plain text, or HTML to create it as formatted HTML.
  • Thread Id - The Id of an existing Gmail thread. When you fill it, the draft is created inside that thread. Click the field and open Field Options to pick the thread from the list of your 50 latest threads, shown by their first line of text, or map the Thread Id from an earlier step. Leave it blank to start a new thread.

Create Label

Creates a new label in your Gmail account. The action returns the new label, including its Id, which you can use in the Label Ids fields of other actions. Gmail - Create Label action
  1. Name - Required. The name of the new label, for example Invoices.
  2. Add Field - Click Add Field to add and populate additional fields for the selected activity. To learn more about managing activity data, click here.
All of the following are optional and are added through Add Field:
  • Label List Visibility - Whether the label appears in Gmail’s list of labels: Show, Show If Unread or Hide. If you leave it empty, the label is shown.
  • Message List Visibility - Whether emails that carry the label appear in Gmail’s message list: Show or Hide. If you leave it empty, they are shown.

Delete Draft

Deletes a draft from your Gmail account. The action returns nothing. Gmail - Delete Draft action
  • Draft Id - The Id of the draft to delete, for example the draft Id returned by the Create Draft or Get Drafts action. You can also pick it from the list: click the field and open Field Options to choose from your latest drafts, shown by their first line of text (a draft that holds only a signature shows the signature).

Delete Email

Moves an email to the Trash folder. The email is not permanently deleted, so you can still recover it from Trash in Gmail. Gmail - Delete Email action
  • Message Id - The Id of the email to move to Trash. Map the Message Id property from a previous step in your workflow, for example from the Check for new emails trigger, or pick it from the list: click the field and open Field Options to choose from your 15 latest emails, shown by their first line of text.

Get Attachment

Gets one file attached to an email. The action returns the attachment Id, its size and its content in base64, which you can pass on to another step, for example a step that saves the file. Gmail - Get Attachment action
  1. Message Id - The Id of the email that holds the attachment. Map the Message Id property from a previous step, for example from the Check for new emails trigger, or pick it from the list: click the field and open Field Options to choose from your 15 latest emails, shown by their first line of text.
  2. Attachment Id - The Id of the attachment. Map it from the attachments property of the Check for new emails trigger, which lists the Attachment Id of each attached file.

Get Draft

Gets one draft from your Gmail account. The action returns the draft Id, the message Id, the thread Id and the label Ids. To read the content of the draft, pass its message Id to the Get Email action. Gmail - Get Draft action
  • Draft Id - The Id of the draft to read, for example the draft Id returned by the Create Draft or Get Drafts action. You can also pick it from the list: click the field and open Field Options to choose from your latest drafts, shown by their first line of text (a draft that holds only a signature shows the signature).

Get Drafts

Gets the list of drafts in your Gmail account. For each draft the action returns the draft Id, the message Id, the thread Id and the label Ids. To read the content of a draft, pass its message Id to the Get Email action. This action has no fields to fill. Gmail - Get Drafts action

Get Email

Gets one email from your mailbox. Gmail - Get Email action
  • Message Id - The Id of the email to read. Map the Message Id property from a previous step in your workflow, for example from Get Emails or the Check for new emails trigger.

Get Emails

Gets a list of emails from your mailbox. Use the filters to narrow the list. Engini collects the results page by page automatically, so you don’t set paging yourself. Gmail - Get Emails action
  1. Top N - The maximum number of emails to return in total, for example 20. If you leave it empty, Engini returns up to 100 emails. The maximum is 500.
  2. Add Filter - Click Add Filter to define conditions that narrow down the data list and return only the relevant items. To learn more about using filters, click here.
All of the following are optional and are added through Add Filter:
  • Search Query - A Gmail search query, written the same way as in the Gmail search box, for example from:ann is:unread.
  • Label Ids - Return only emails that carry the labels you pick from the list.
  • Include Spam Trash - Choose Yes to also return emails from Spam and Trash, or No to leave them out.

Get Labels

Gets the list of labels in your mailbox. This action has no fields to fill. Gmail - Get Labels action

Get Thread

Gets one thread from your mailbox. The action returns the thread Id and its history Id. Gmail - Get Thread action
  • Thread Id - The Id of the thread to read. Map the Thread Id property from a previous step, for example from the Get Threads action or the Check for new emails trigger, or pick it from the list: click the field and open Field Options to choose from your 50 latest threads, shown by their first line of text.

Get Threads

Gets a list of conversation threads from your mailbox. The action returns the Id, the snippet and the history Id of each thread. Use the Thread Id with the Get Thread action. Gmail - Get Threads action
  1. Top N - The maximum number of threads to return. The default is 100 and the maximum is 500.
  2. Add Filter - Click Add Filter to define conditions that narrow down the data list and return only the relevant items. To learn more about using filters, click here.
All of the following are optional and are added through Add Filter:
  • Search Query - A Gmail search query, written the same way as in the Gmail search box, for example from:ann is:unread.
  • Label Ids - Return only threads that carry the labels you pick from the list.

Mark Email as Read

Marks an email as read. Gmail - Mark Email as Read action
  • Message Id - The Id of the email to mark as read. Map the Message Id property from a previous step in your workflow, for example from the Check for new emails trigger, or pick it from the list: click the field and open Field Options to choose from your 15 latest emails, shown by their first line of text.

Mark Email as Unread

Marks an email as unread, so it appears as new in your mailbox again. Gmail - Mark Email as Unread action
  • Message Id - The Id of the email to mark as unread. Map the Message Id property from a previous step in your workflow, for example from the Check for new emails trigger, or pick it from the list: click the field and open Field Options to choose from your 15 latest emails, shown by their first line of text.

Move Email

Moves an email by adding labels to it or removing labels from it. Gmail - Move Email action
  1. Message Id - The Id of the email to move. Map the Message Id property from a previous step in your workflow, for example from the Check for new emails trigger, or pick it from the list: click the field and open Field Options to choose from your 15 latest emails, shown by their first line of text.
  2. Add Field - Click Add Field to add and populate additional fields for the selected activity. To learn more about managing activity data, click here.
All of the following are optional and are added through Add Field:
  • Add Label Ids - The labels to add to the email, picked from the list of your labels.
  • Remove Label Ids - The labels to remove from the email, picked from the same list. For example, add the label you want and remove INBOX to move an email out of the inbox.

Reply Email

Replies to an existing email from your Gmail account. Give Engini the email you are answering and your reply text, and it builds the rest itself: the reply goes to the sender (or to the address in the email’s Reply-To header, if it has one), the subject becomes “Re:” followed by the original subject, and the reply stays in the same conversation. There is no need to build or encode the email yourself. Gmail - Reply Email action
  1. Message Id - The Id of the email you are replying to. Map the Message Id property from a previous step in your workflow, for example from the Check for new emails trigger, or pick it from the list: click the field and open Field Options to choose from your 15 latest emails, shown by their first line of text. Give a Message Id or a Thread Id. If you give both, the Message Id is used.
  2. Thread Id - The Id of the conversation to reply in, for example the Thread Id returned by the Get Threads action. Click the field and open Field Options to choose from your recent threads. When you give only a Thread Id, the reply goes to the newest email in that thread. If you give neither a Message Id nor a Thread Id, the action fails and nothing is sent.
  3. Body - Required. The text of your reply, for example 'Thanks, we received your request and will get back to you tomorrow.'. Click the empty field to open a window where you write the body, and use the tooltip inside it to insert properties from previous steps. By default the reply is sent as HTML, so you can format it; to send plain text instead, set Content Type to Text.
  4. Add Field - Click Add Field to add and populate additional fields for the selected activity. To learn more about managing activity data, click here.
All of the following are optional and are added through Add Field:
  • Reply All - Choose Yes to also send the reply to everyone who was on the original email: its other recipients (To) and the people in copy (Cc). Choose No (the default) to reply only to the sender.
  • Content Type - Leave it empty (the default) to send the reply as HTML, or choose Text to send it as plain text.
  • attachments - The files to send, built with the Initialize attachment array and Append to attachments array actions below.
  • BCC - Recipients who receive a blind copy, for example name@example.com.
  • Cc - Additional people who receive a copy of the reply, for example name@example.com. Separate several addresses with a comma or a semicolon.
  • Send As - The address the reply is sent from. Pick it from the list of the other addresses your Gmail account can send as (the “Send mail as” addresses in Gmail). The connected account itself is not in the list, and the list is empty if no other addresses are set up. Leave the field empty to send from the connected account. The address must already be set up in Gmail under Settings > Accounts > “Send mail as”; otherwise the action fails and nothing is sent.
The action returns the Thread Id of the conversation, which you can use in later steps. Note: Sending cannot be undone.

Restore Email

Restores an email from the Trash folder back to your mailbox. Use it to bring back an email that the Delete Email action moved to Trash. Gmail - Restore Email action
  • Message Id - The Id of the email to restore. Map the Message Id property from a previous step in your workflow, for example from the Delete Email action, or pick it from the list: click the field and open Field Options to choose from your 15 latest emails in the Trash, shown by their first line of text.

Send Draft

Sends an existing draft from your Gmail account. Gmail - Send Draft action
  • Draft Id - Required. The Id of the draft to send, for example the draft Id returned by the Create Draft action. You can also pick it from the list: click the field and open Field Options to choose from your latest drafts, shown by their first line of text (a draft that holds only a signature shows the signature).
Note: Sending cannot be undone. Once the draft is sent, it leaves your Drafts folder and appears in your Sent folder.

Send Email

Sends an email from your Gmail account. Fill in the recipient, subject and body, and use Add Field for copies, attachments or a different sender address. Gmail - Send Email action
  1. To - The email address of the recipient, for example name@example.com. Select it from the tooltip, for example the From email property of the Check for new emails trigger to answer the sender, or type it as a static value in single quotes. Separate several addresses with a comma.
  2. Subject - The subject line of the email, for example 'Your order has shipped'. You can type a static text or combine it with a property from a previous step.
  3. Body - The main content of the message. Click the empty field to open a window where you write the email body, and use the tooltip inside it to insert properties from previous steps. Gmail - Email body window
  4. Add Field - Click Add Field to add and populate additional fields for the selected activity. To learn more about managing activity data, click here.
All of the following are optional and are added through Add Field:
  • attachments - The files to send, built with the Initialize attachment array and Append to attachments array actions below.
  • BCC - Recipients who receive a blind copy, for example name@example.com.
  • CC - Recipients who receive a copy, for example name@example.com.
  • From (Display name) - The sender name recipients see, for example 'Acme Support'. If you leave it empty, recipients see only your email address.
  • Send As - The address the email is sent from. Pick it from the list of the other addresses your Gmail account can send as (the “Send mail as” addresses in Gmail). The connected account itself is not in the list, and the list is empty if no other addresses are set up. Leave the field empty to send from the connected account. The address must already be set up in Gmail under Settings > Accounts > “Send mail as”; otherwise the action fails and nothing is sent.
Note: Sending cannot be undone.

Update Draft

Replaces the whole content of an existing draft with a new message. Give Engini the draft Id and the full new email, and it builds the email itself. The action returns the draft Id, the message Id, the thread Id and the label Ids. Gmail - Update Draft action
  1. Draft Id - Required. The Id of the draft to update, for example the draft Id returned by the Create Draft action. You can also pick it from the list: click the field and open Field Options to choose from your latest drafts, shown by their first line of text (a draft that holds only a signature shows the signature).
  2. To - Required. The email address of the recipient, for example name@company.com. Select it from the tooltip, or type it as a static value in single quotes.
  3. Subject - Required. The new subject line of the draft, for example 'Your order has shipped'.
  4. Body - Required. The new text of the draft. Click the empty field to open a window where you write the body, and use the tooltip inside it to insert properties from previous steps.
  5. Add Field - Click Add Field to add and populate additional fields for the selected activity. To learn more about managing activity data, click here.
All of the following are optional and are added through Add Field:
  • Cc - People who receive a copy, for example name@company.com. Separate several addresses with a comma or a semicolon.
  • Bcc - People who receive a blind copy. Separate several addresses with a comma or a semicolon.
  • Content Type - Choose Text (the default) to save the draft as plain text, or HTML to save it as formatted HTML.
  • Thread Id - The Id of the Gmail thread the draft belongs to. Click the field and open Field Options to pick the thread from the list of your 50 latest threads, shown by their first line of text, or map the Thread Id from an earlier step. Leave it blank to start a new thread.
Note: The new message replaces the whole draft, so To, Subject and Body are required every time, even if you only want to change one of them.

Initialize attachment array

To create multiple files that will be sent in the email, you need to initialize an array for the files. Choose this action to initialize the array and give it a name. Gmail - Initialize attachment array action
  • Name - The name of the array. It opens with the default attachments array, which you can keep or change, for example to invoices. You choose this name later in the Variable field of the Append to attachments array action.

Append to attachments array

Append files to attachments array. Gmail - Append to attachments array action
  1. Variable - The array to add the file to. Select it from the list, which shows the arrays you created with the Initialize attachment array action earlier in the workflow.
  2. File name - The name the file has when the recipient receives it, including its extension, for example invoice.pdf.
  3. Content - The content of the file, in base64 format. Map it from a previous step, for example the content returned by the Get Attachment action.
Note: To use this action, you first need to initialize an array.

Send API Request

Sends a custom request directly to the Gmail API. Use it for Gmail features that the actions above don’t cover. Gmail - Send API Request action
  1. Base Url - The root URL of the Gmail API (https://gmail.googleapis.com/gmail/v1/). Engini adds the Relative url to the end of it.
  2. Relative url - The path to add to the end of the Base Url. This lets you choose the specific request you want to perform, for example users/me/profile.
  3. Method - Select the HTTP method (for example Get, Post, Put, Delete, Patch). The default is POST.
  4. Body Type - Defines the format of the data in the body of your request. The default, application/json, means the body contains a JSON-formatted payload.
  5. Body - The data you send to the server.
  6. Add Headers - Additional metadata about the request, such as the type of data Engini can accept and the length of the request body.
  7. Add Queries - The parameters that are added to the URL of the request to give the server more information or instructions.
For the full list of endpoints, see the Gmail API reference.