Google Gmail

1. Overview

Google Gmail is a widely-used free email service provided by Google. The Gmail API allows developers to programmatically access and manage Gmail mailboxes, including reading, sending, and organizing emails and drafts.

With the GoInsight Google Gmail node, you can integrate email management directly into your automated workflows. This enables you to perform a wide range of tasks without leaving the GoInsight platform, including:

• Sending and Receiving: Send new emails, reply to existing ones, and forward messages.
• Draft Management: Create, update, find, send, and delete draft emails.
• Organization: Manage labels by creating, deleting, and applying them to emails and conversations.
• Email Management: Search for specific emails, retrieve their full content, and move them to trash or mark them as read/unread.

2. Prerequisites

Before using this node, you need to have:

• A valid Google Gmail account.
• Appropriate permissions within your Google Cloud project to create and manage API credentials (OAuth 2.0 Client IDs).

3. Credentials

For a detailed guide on how to obtain and configure your credentials, please refer to our official documentation: Credentials Configuration Guide.

4. Supported Operations

This node provides a comprehensive set of operations to interact with various Gmail resources like emails, drafts, and labels.

Summary

The following table summarizes all the supported operations, grouped by the resource they manage.

Operation Details

Add Label to Conversation

Remove one or more Gmail labels from all emails within a conversation.

Input Parameters:

• ThreadId: The unique identifier of the Gmail conversation (thread) to label.
• LabelIds: A single Gmail label ID or a comma-separated list of label IDs to be added.

Output:

• Added (bool): Indicates whether all specified labels were added.
• StatusCode (number): The HTTP status code returned. 204 indicates success, -1 indicates parameter error, 500 indicates an exception.
• ErrorMessage (string): A string detailing any error encountered during the request or exception thrown.

Add Label to Email

Add one or more Gmail labels to a message by its ID, using a comma-separated string of label IDs

Input Parameters:

• MessageId: The unique identifier of the Gmail message to label.
• LabelIds: A single Gmail label ID or a comma-separated list of label IDs to be added.

Output:

• Added (bool): Indicates whether the label was added successfully.
• StatusCode (number): The HTTP status code returned by the Gmail API (e.g., 200 for a successful list request, 204 for a successful delete) or 500 if an internal error occurred during processing.
• ErrorMessage (string): A string detailing any error encountered during the request or exception thrown; it is empty when the operation succeeds.

Create a Draft

Create a Gmail draft using the provided recipient, subject, and body.

Input Parameters:

• To: Comma‑separated recipient addresses (e.g. “a@x.com,b@y.com”).
• Subject: The email subject.
• Body: The email body text (plain or html).

Output:

• DraftCreated (bool): Indicating whether the draft was successfully created.
• draftId (string): The ID of the created draft if successful, otherwise an empty string.
• StatusCode (number): The HTTP status code returned. 204 indicates success, -1 indicates parameter error, 500 indicates an exception.
• ErrorMessage (string): A string detailing any error encountered during the request or exception thrown.

Create a Label

Creates a new Gmail label.

Input Parameters:

• LabelName: The display name for the new Gmail label.

Output:

• Created (bool): Indicates whether the label was added successfully.
• LabelId (string): The ID of the newly created label (empty on failure).
• StatusCode (number): The HTTP status code returned by the Gmail API (e.g., 200 for a successful list request, 204 for a successful delete) or 500 if an internal error occurred during processing.
• ErrorMessage (string): A string detailing any error encountered during the request or exception thrown; it is empty when the operation succeeds.

Delete Draft

Deletes one or more Gmail drafts specified by their draft IDs.

Input Parameters:

• DraftId: A single Gmail draft ID or a comma-separated list of draft IDs to be deleted.

Output:

• AllDeleted (bool): Indicates whether the draft was successfully deleted.
• FailedItems (object-array): A JSON list of failed deletion items with fields: draftId, statusCode, errorMessage.
• StatusCode (number): Overall operation status (-1 for parameter errors, 200 for all successes, 207 for partial success, 500 for all failures).
• ErrorMessage (string): Overall error message if parameter validation fails, empty otherwise.

Delete Label

Deletes one or more Gmail labels specified by their label IDs.

Input Parameters:

• LabelId: The Gmail label ID that you wish to delete.

Output:

• AllDeleted (bool): Indicates whether all specified labels were successfully deleted.
• FailedItems (object-array): A JSON list of failed deletion items with fields: labelId, statusCode, errorMessage.
• StatusCode (number): Overall operation status (-1 for parameter errors, 200 for all successes, 207 for partial success, 500 for all failures).
• ErrorMessage (string): Overall error message if parameter validation fails, empty otherwise.

Delete Mail

Deletes one or more Gmail messages specified by their message IDs.

Input Parameters:

• MessageId: A single Gmail message ID or a comma-separated list of message IDs to be deleted.

Output:

• AllDeleted (bool): Indicates whether all specified messages were successfully deleted.
• FailedItems (object-array): A JSON list of failed deletion items with fields: messageId, statusCode, errorMessage.
• StatusCode (number): Overall operation status: 200 (all succeeded), 207 (partial success), 500 (all failed), -1 (parameter error).
• ErrorMessage (string): Overall error message if parameter validation fails, empty otherwise.

Get Send As

Retrieve the list of sendAs addresses for authenticated Gmail users.

Output:

• SendAs (object-array): SendAs sets a list of objects, each of which contains fields such as sendAsEmail, showName, isDefault, etc.
• StatusCode (number): HTTP response code or custom code: 200 (successful), 500 (request error), -1 (parameter validation error).
• ErrorMessage (string): Error details (if any), empty when successful.

Get a Mail

Retrieves detailed information of a Gmail message by its message ID, including full email body content and headers.

Input Parameters:

• MessageId: The unique identifier of the Gmail message.

Output:

• Id (string): Email unique identifier.
• ThreadId (string): The ID of the email thread.
• Snippet (string): A preview snippet of the email.
• From (string): Sender's email address.
• To (string): Recipient's email address.
• CC (string): CC email addresses.
• Subject (string): Email subject.
• Date (string): Email date.
• HasAttachment (bool): Indicates whether the email contains attachments.
• LabelIds (string-array): An array of strings representing Gmail label IDs associated with the email.
• Body (string): The complete email body content.
• StatusCode (number): The HTTP status code returned. 204 indicates success, -1 indicates parameter error, 500 indicates an exception.
• ErrorMessage (string): A string detailing any error encountered during the request or exception thrown.

Get many Labels

Retrieves all Gmail labels for the authenticated user.

Output:

• Labels (object-array): A list of label objects:Id,Name,Type
• StatusCode (number): Operation result code: -1 for parameter validation error; 200 for success; other HTTP codes for API errors; 500 for internal exceptions.
• ErrorMessage (string): Error message if any; empty if successful.

Get many Messages

Retrieves a list of Gmail messages with optional pagination and search query support.

Input Parameters:

• MaxResults: Maximum number of messages to return (1-500).

Options:

• PageToken: Token to retrieve the next page of results.
• Query: Gmail search query string (e.g., "from:alice@example.com").
• AfterTime: Filters messages sent on or after this date (YYYY/MM/DD).
• BeforeTime: Filters messages sent on or before this date (YYYY/MM/DD).

Output:

• Messages (object-array): List of messages with fields:Id,ThreadId
• NextPageToken (string): Token to fetch the next page of data.
• ResultSizeEstimate (number): Estimated total number of messages matching the request.
• StatusCode (number): Operation status code: 200 (success), -1 (parameter error), other HTTP error codes.
• ErrorMessage (string): Error description if any; empty if no error.

Remove Label from Conversation

Remove one or more Gmail labels from all emails within a conversation.

Input Parameters:

• ThreadId: The unique identifier of the Gmail conversation (thread) to label.
• LabelIds: A single Gmail label ID or a comma-separated list of label IDs to be removed.

Output:

• Removed (bool): Indicates whether all specified labels were removed.
• StatusCode (number): The HTTP status code returned by the Gmail API (e.g., 200 for a successful list request, 204 for a successful delete) or 500 if an internal error occurred during processing.
• ErrorMessage (string): A string detailing any error encountered during the request or exception thrown; it is empty when the operation succeeds.

Remove Label from Email

Remove one or more Gmail labels from a message by its ID, using a comma-separated string of label IDs.

Input Parameters:

• MessageId: The unique identifier of the Gmail message to label.
• LabelIds: A single Gmail label ID or a comma-separated list of label IDs to be removed.

Output:

• Removed (bool): Indicates whether the label was removed successfully.
• StatusCode (number): The HTTP status code returned by the Gmail API (e.g., 200 for a successful list request, 204 for a successful delete) or 500 if an internal error occurred during processing.
• ErrorMessage (string): A string detailing any error encountered during the request or exception thrown; it is empty when the operation succeeds.

Reply to Email

Sends a reply to an email message.

Input Parameters:

• MessageId: The unique identifier of the Gmail message to reply.
• ReplyText: The body text/html of the reply.

Options:

• ReplyALL: Whether to reply to all recipients (sender, To, and Cc) or just the sender.
• AdditionalCc: A comma-separated list of email addresses to append to the original CC list; does not replace existing CC.
• SaveToDraft: Whether to save the reply as a draft instead of sending.

Output:

• Responded (bool): Indicates whether the reply was sent successfully.
• StatusCode (number): The HTTP status code returned by the Gmail API (e.g., 200 for a successful list request, 204 for a successful delete) or 500 if an internal error occurred during processing.
• ErrorMessage (string): A string detailing any error encountered during the request or exception thrown; it is empty when the operation succeeds.
• DraftId (string): The ID of the saved draft; empty if the message was sent.

Send Draft

Send an existing Gmail draft.

Input Parameters:

• DraftId: The unique identifier of the Gmail draft to send.

Output:

• Sent (bool): Indicates whether the draft was successfully sent.
• StatusCode (number): The HTTP status code returned by the Gmail API (e.g., 200 for a successful list request, 204 for a successful delete) or 500 if an internal error occurred during processing.
• ErrorMessage (string): A string detailing any error encountered during the request or exception thrown; it is empty when the operation succeeds.

Send Mail

Create and send a new Gmail message with specified reipients (to), subject, and body.

Input Parameters:

• To: Comma‑separated recipient addresses (e.g. "Alice ,b@y.com").
• Subject: The email subject.
• Body: The email body text (plain or html).

Output:

• Sent (bool): Indicates whether the email was sent successfully.
• StatusCode (number): The HTTP status code returned by the Gmail API (e.g., 200 for a successful list request, 204 for a successful delete) or 500 if an internal error occurred during processing.
• ErrorMessage (string): A string detailing any error encountered during the request or exception thrown; it is empty when the operation succeeds.

Find Draft

Search for drafts matching criteria and return a list of draft IDs with snippets.

Input Parameters:

• SearchString: The keywords for searching or a specific draft ID. Must be a non-empty string.

Options:

• MaxResults: An integer (1–20) specifying the maximum number of messages to return.

Output:

• Drafts (object-array): A JSON list representing a list of matching draft email objects. Each object contains the fields id, threadId, snippet, from, to, cc, subject, date, hasAttachment, and labelIds.
• StatusCode (number): The HTTP status code returned. 204 indicates success, -1 indicates parameter error, 500 indicates an exception.
• ErrorMessage (string): A string detailing any error encountered during the request or exception thrown.

Find Email

Search for emails matching criteria and return a list of message IDs with snippets.

Input Parameters:

• SearchString: A Gmail search string using the same syntax as the Gmail web interface (e.g., from:alice@example.com is:unread).

Options:

• MaxResults: An integer (1–500) specifying the maximum number of messages to return; defaults to 10.

Output:

• Mails (object-array): A JSON list containing objects with id and snippet fields for each matched message.
• StatusCode (number): The HTTP status code returned by the Gmail API (e.g., 200 for a successful list request, 204 for a successful delete) or 500 if an internal error occurred during processing.
• ErrorMessage (string): A string detailing any error encountered during the request or exception thrown; it is empty when the operation succeeds.

Forward Email

Forwards a Gmail message, including all original content and attachments, to specified recipients.

Input Parameters:

• MessageId: The unique identifier of the Gmail message to reply.
• ForwardTo: One or more recipient email addresses, separated by commas.

Options:

• ForwardText: Optional HTML content to include before the original message. Use empty string for no additional text.

Output:

• Forwarded (bool): Indicates whether the message was successfully forwarded.
• MessageId (string): The ID of the newly forwarded message.
• StatusCode (number): Operation status code: 200 (success), other HTTP codes for failures, -1 for parameter errors, 500 for internal exceptions.
• ErrorMessage (string): Error details if forwarding failed or parameter validation error; empty string if successful.

Mark Messages as Read

Marks one or more Gmail messages as read.

Input Parameters:

• MessageId: A single Gmail message ID or a comma-separated list of message IDs to mark as read.

Output:

• AllMarked (bool): Indicates whether all specified messages were successfully marked as read.
• FailedItems (object-array): A JSON list containing failed messages with MessageId, StatusCode, and ErrorMessage for each item.
• StatusCode (number): Overall operation status: 200 (all succeeded), 207 (partial success), 500 (all failed), -1 (parameter error).
• ErrorMessage (string): Overall error message if parameter validation fails; empty otherwise.

Mark Messages as Unread

Marks one or more Gmail messages as unread.

Input Parameters:

• MessageId: A single Gmail message ID or a comma-separated list of message IDs to mark as unread.

Output:

• AllMarked (bool): Indicates whether all specified messages were successfully marked as unread.
• FailedItems (object-array): A JSON list containing failed messages with MessageId, StatusCode, and ErrorMessage for each item.
• StatusCode (number): Overall operation status: 200 (all succeeded), 207 (partial success), 500 (all failed), -1 (parameter error).
• ErrorMessage (string): Overall error message if parameter validation fails; empty otherwise.

Trash Conversation

Moves one or more Gmail conversations (thread) to the trash.

Input Parameters:

• ThreadId: A single Gmail conversation ID or a comma-separated list of conversation IDs to be trashed.

Output:

• AllTrashed (bool): Indicates whether all specified conversations were successfully trashed.
• FailedItems (object-array): A JSON list of failed items with fields: threadId, statusCode, errorMessage.
• StatusCode (number): Overall operation status (-1 for parameter errors, 200 for all succeeded, 207 for partial success, 500 for all failed).
• ErrorMessage (string): Overall error description if parameter validation fails; otherwise, it is empty.

Trash Mail

Moves one or more Gmail messages to the trash.

Input Parameters:

• MessageId: A single Gmail message ID or a comma-separated list of message IDs to be trashed.

Output:

• AllTrashed (bool): Indicates whether all specified messages were successfully moved to trash.
• FailedItems (object-array): A JSON list of failed items with fields: messageId, statusCode, errorMessage.
• StatusCode (number): Overall operation status (-1 for parameter errors, 200 for all successes, 207 for partial success, 500 for all failures).
• ErrorMessage (string): Overall error message if parameter validation fails, empty otherwise.

Update Draft

Updates a Gmail draft by using PATCH to modify only the specified fields.

Input Parameters:

• DraftId: The unique identifier of the Gmail draft to update.

Options:

• To: Comma‑separated recipient addresses (e.g. “a@x.com,b@y.com”).
• Subject: The email subject.
• Body: The email body text (plain or html).

Output:

• Updated (bool): Indicates whether the draft was successfully updated
• StatusCode (number): The HTTP status code returned. 204 indicates success, -1 indicates parameter error, 500 indicates an exception.
• ErrorMessage (string): A string detailing any error encountered during the request or exception thrown.

5. Example Usage

This section will guide you through creating a simple workflow to send an email using the Google Gmail node.

The workflow will consist of three nodes: Start -> Send Mail -> Answer.

Step 1: Add the Tool Node

1. In the workflow canvas, click the + button to add a new node.
2. In the pop-up panel, select the "Tools" tab.
3. Find and select "Google Gmail" from the list of tools.
4. In the list of supported operations for Google Gmail, click on "Send Mail". This will add a "Send Mail" node to your canvas.

Step 2: Configure the Node

1. Click on the newly added "Send Mail" node to open its configuration panel on the right.
2. Credentials Configuration: At the top of the panel, find the credentials field. Click the dropdown menu and select your pre-configured Google Gmail credential.
3. Parameter Configuration: Fill in the required input parameters for the "Send Mail" operation.
   • To: Enter the recipient's email address, for example, recipient@example.com. For multiple recipients, separate them with a comma: recipient1@example.com,recipient2@example.com.
   • Subject: Enter the subject line for your email, such as "Workflow Test from GoInsight".
   • Body: Enter the content of your email. You can use plain text or HTML, for example, "This is a test email sent automatically from a GoInsight workflow."

Step 3: Run and Verify

1. Once all required parameters are correctly filled, any error indicators on the workflow canvas should disappear.
2. Click the "Run Test" button in the top-right corner of the canvas to execute the workflow.
3. After a successful execution, you can click the logs icon in the top-right corner to view the detailed input and output of the node, confirming that the operation was successful. The recipient should also receive the email in their inbox.

After completing these steps, your workflow is fully configured. When executed, it will automatically send an email with the content you specified.

6. FAQs

Q: Why am I getting a 401 or 403 error?

A: This typically indicates an issue with authentication or authorization. Please check the following:

• Credentials: Ensure your credentials are correctly configured in GoInsight and have not expired.
• API Enabled: Verify that the Gmail API is enabled in your Google Cloud Platform project.
• OAuth Scopes: Make sure the OAuth consent screen is configured with the necessary scopes to read, compose, and send emails.

Q: How can I find the ID for a specific label?

A: You can use the Get many Labels operation in a separate workflow or test run. This operation will return a list of all labels in your Gmail account, each with its corresponding Id and Name. You can then use this ID in other operations like Add Label to Email.

Q: Can I send emails with attachments using this node?

A: Based on the current operations, direct file attachment is not supported through simple input fields. The Send Mail and Create a Draft operations focus on the text/HTML body. For advanced use cases involving attachments, you may need to refer to the official Gmail API documentation.

7. Official Documentation

For more detailed information about the API's capabilities and advanced features, please refer to the Google Gmail official API documentation.