Gmail Component

Manage Messages in Google's email service
Component key: google-gmail#
DescriptionGmail is Google's email service. This component allows you to fetch and filter and manage messages, and send new messages from a Google Gmail account.
Documentation for the Node.js client used in this component can be found at https://googleapis.dev/nodejs/googleapis/latest/gmail/index.html
Most actions in this component have a Gmail User ID input.
You can safely leave this input blank, and the default value, me
will be used, indicating that the user who authenticated is the user whose Gmail account your integration will use.
Use labels to organize messages
Gmail uses labels in place of folders to organize messages.
Messages in a user's inbox have a label of INBOX
.
You can apply custom labels to a message (so, you can loop only over messages with a particular label, etc).
#
Gmail Connections#
OAuth2The Gmail component authenticates requests through the Google Cloud Platform (GCP) OAuth 2.0 service. You'll need to create a GCP OAuth 2.0 app so your integration can authenticate and perform Gmail tasks on your customers' behalf.
To create a Gmail OAuth 2.0 app, first make sure you have a Google Developer account - you can sign up at https://console.cloud.google.com/. Then:
- Open up the Gmail API console - https://console.cloud.google.com/marketplace/product/google/gmail.googleapis.com
- You will be prompted to enable Gmail API for your project. Click ENABLE.
- On the sidebar, select APIs & Services and then Credentials.
- An OAuth 2.0 app includes a "Consent Screen" (the page that asks "Do you want to allow (Your Company) to access Gmail on your behalf?"). Click CONFIGURE CONSENT SCREEN.
- Your app will be externally available to your customers, so choose a User Type of External.
- Fill out the OAuth consent screen with an app name (your company or product's name), support email, app logo, domain, etc.
- You can ignore domains for now.
- On the next page, ignore scopes - this component knows what scopes it needs to run and will request the right scopes for you.
- Enter some test users for your testing purposes. Your app will only work for those testing users until it is "verified" by Google. When you are ready for verification (they verify your privacy policy statement, etc), click PUBLISH APP on the OAuth consent screen. That'll allow your customers to authorize your integration to access their Gmail account.
- Once your "Consent Screen" is configured open the Credentials page from the sidebar again.
- Click +CREATE CREDENTIALS and select OAuth Client ID.
- Under Application type select Web application.
- Under Authorized redirect URIs enter Prismatic's OAuth 2.0 callback URL:
https://oauth2.prismatic.io/callback
- Click CREATE.
- Take note of the Client ID and Client Secret that are generated.
info
Make sure to publish your OAuth 2.0 app after you've tested it so users outside of your test users can authorize your integration to interact with Gmail on their behalf.
Now that you have a Client ID and Client Secret, add Gmail step to your integration in Prismatic. Open the Configuration Wizard Designer by clicking Configuration Wizard, select your Gmail Connection and enter your client ID and secret.
A note on scopes
You can keep the default Gmail scope, https://mail.google.com/
.
This will grant you full permission over your users' Gmail accounts.
If you would like to limit permissions, you can select a subset of scopes, like https://www.googleapis.com/auth/gmail.readonly https://www.googleapis.com/auth/gmail.send
.
Input | Default | Notes |
---|---|---|
Input Authorize URL string / Required Hidden Field authorizeUrl | Default https://accounts.google.com/o/oauth2/v2/auth?access_type=offline&prompt=consent | Notes The Authorization URL for Gmail |
Input Client ID string / Required clientId | Default | Notes Your Gmail app's Client ID |
Input Client Secret password / Required clientSecret | Default | Notes Your Gmail app's Client Secret |
Input Scopes string / Required scopes | Default https://mail.google.com/ | Notes Space delimited listing of scopes. See https://developers.google.com/gmail/api/auth/scopes |
Input Token URL string / Required Hidden Field tokenUrl | Default https://oauth2.googleapis.com/token | Notes The Token URL for Gmail |
#
Actions#
Get Current UserGet metadata about the authenticated user | key: getCurrentUser
Input | Notes |
---|---|
Input Connection connection / Required connection | Notes The Connection to use for authorization. |
#
Output Example Payload{ "data": { "emailAddress": "example@gmail.com", "historyId": "1234567", "messagesTotal": 12345, "threadsTotal": 12345 }}
#
Get Label by NameGet a label (including ID) by its name | key: getLabelByName
Input | Notes |
---|---|
Input Connection connection / Required connection | Notes The Connection to use for authorization. |
Input Label Name string / Required labelName | Notes |
Input Gmail User ID (optional) string userId | Notes A user whose account to query (defaults to currently authenticated user) |
#
Get MessageGet a message by ID | key: getMessageById
Input | Notes | Example |
---|---|---|
Input Connection connection / Required connection | Notes The Connection to use for authorization. | Example |
Input Message ID string / Required messageId | Notes | Example 1234abcd |
Input Gmail User ID (optional) string userId | Notes A user whose account to query (defaults to currently authenticated user) | Example |
#
Output Example Payload{ "data": { "id": "1234abcd", "threadId": "5678efgh", "labelIds": [ "IMPORTANT", "SENT", "INBOX" ], "message": { "headers": { "mime-version": "1.0", "date": "2022-09-19T20:09:01.000Z", "message-id": "<Test-message-id@mail.gmail.com>", "subject": "Test Message", "from": { "value": [ { "address": "example@gmail.com", "name": "Example Example" } ], "html": "<span class=\"mp_address_group\"><span class=\"mp_address_name\">Example Example</span> <<a href=\"mailto:example@gmail.com\" class=\"mp_address_email\">example@gmail.com</a>></span>", "text": "Example Example <example@gmail.com>" }, "to": { "value": [ { "address": "example@gmail.com", "name": "Example Example" } ], "html": "<span class=\"mp_address_group\"><span class=\"mp_address_name\">Example Example</span> <<a href=\"mailto:example@gmail.com\" class=\"mp_address_email\">example@gmail.com</a>></span>", "text": "Example Example <example@gmail.com>" }, "content-type": { "value": "multipart/mixed", "params": { "boundary": "000000000000680fa005e90d488f" } } }, "attachments": [], "text": "Example email body", "html": "<div dir=\"ltr\">Example email body<div><br></div></div>\n" } }}
#
List LabelsList all labels within this account | key: listLabels
Input | Notes |
---|---|
Input Connection connection / Required connection | Notes The Connection to use for authorization. |
Input Gmail User ID (optional) string userId | Notes A user whose account to query (defaults to currently authenticated user) |
#
List MessagesGet a list of messages | key: listMessages
Input | Notes | Example |
---|---|---|
Input Connection connection / Required connection | Notes The Connection to use for authorization. | Example |
Input Labels string Value List labelIds | Notes Show only messages with labels that match these label IDs | Example |
Input Page Token string pageToken | Notes If you're looping over pages of results, this is the page token from the result of the previous 'list messages' step. | Example |
Input Query String string query | Notes Only return messages matching the specified query. Supports the same query format as the Gmail search box. | Example from:someuser@example.com rfc822msgid:<somemsgid@example.com> is:unread |
Input Gmail User ID (optional) string userId | Notes A user whose account to query (defaults to currently authenticated user) | Example |
#
Output Example Payload{ "data": { "messages": [ { "id": "abcd1234", "threadId": "efgh5678" } ] }}
#
Raw RequestSend a raw request to Google Gmail | key: rawRequest
Input | Default | Notes | Example |
---|---|---|---|
Input Connection connection / Required connection | Default | Notes The Connection to use for authorization. | Example |
Input Data string data | Default | Notes The HTTP body payload to send to the URL. | Example {"exampleKey": "Example Data"} |
Input Debug Request boolean debugRequest | Default false | Notes Enabling this flag will log out the current request. | Example |
Input File Data string Key Value List fileData | Default | Notes File Data to be sent as a multipart form upload. | Example [{key: "example.txt", value: "My File Contents"}] |
Input File Data File Names string Key Value List fileDataFileNames | Default | Notes File names to apply to the file data inputs. Keys must match the file data keys above. | Example |
Input Form Data string Key Value List formData | Default | Notes The Form Data to be sent as a multipart form upload. | Example [{"key": "Example Key", "value": new Buffer("Hello World")}] |
Input Header string Key Value List headers | Default | Notes A list of headers to send with the request. | Example User-Agent: curl/7.64.1 |
Input Max Retry Count string maxRetries | Default 0 | Notes The maximum number of retries to attempt. | Example |
Input Method string / Required method | Default | Notes The HTTP method to use. | Example |
Input Query Parameter string Key Value List queryParams | Default | Notes A list of query parameters to send with the request. This is the portion at the end of the URL similar to ?key1=value1&key2=value2. | Example |
Input Response Type string / Required responseType | Default json | Notes The type of data you expect in the response. You can request json, text, or binary data. | Example |
Input Retry On All Errors boolean retryAllErrors | Default false | Notes If true, retries on all erroneous responses regardless of type. | Example |
Input Retry Delay (ms) string retryDelayMS | Default 0 | Notes The delay in milliseconds between retries. | Example |
Input Timeout string timeout | Default | Notes The maximum time that a client will await a response to its request | Example 2000 |
Input URL string / Required url | Default | Notes This is the URL to call. | Example /v1/users/{userId}/messages |
Input Use Exponential Backoff boolean useExponentialBackoff | Default false | Notes Specifies whether to use a pre-defined exponential backoff strategy for retries. | Example |
#
Send MessageSend a new message | key: sendMessage
Input | Notes |
---|---|
Input Attachments string Key Value List attachments | Notes Specify a file name as the key (i.e. 'my-file.pdf'), and the file as the value |
Input BCC string Value List bcc | Notes |
Input CC string Value List cc | Notes |
Input Connection connection / Required connection | Notes The Connection to use for authorization. |
Input HTML body string html | Notes For email clients that support HTML |
Input Subject string / Required subject | Notes |
Input Plain text body string text | Notes For email clients that do not support HTML |
Input To string / Required Value List to | Notes |
Input Gmail User ID (optional) string userId | Notes A user whose account to query (defaults to currently authenticated user) |
#
Trash MessageSend a message to the trash | key: trashMessageById
Input | Notes | Example |
---|---|---|
Input Connection connection / Required connection | Notes The Connection to use for authorization. | Example |
Input Message ID string / Required messageId | Notes | Example 1234abcd |
Input Gmail User ID (optional) string userId | Notes A user whose account to query (defaults to currently authenticated user) | Example |
#
Untrash MessageRemove a message from the trash | key: unTrashMessageById
Input | Notes | Example |
---|---|---|
Input Connection connection / Required connection | Notes The Connection to use for authorization. | Example |
Input Message ID string / Required messageId | Notes | Example 1234abcd |
Input Gmail User ID (optional) string userId | Notes A user whose account to query (defaults to currently authenticated user) | Example |
#
Update Message LabelsAdd or remove labels from a message | key: updateLabels
Input | Notes | Example |
---|---|---|
Input Labels to Add string Value List addLabels | Notes A list of labels to add (optional) | Example |
Input Connection connection / Required connection | Notes The Connection to use for authorization. | Example |
Input Message ID string / Required messageId | Notes | Example 1234abcd |
Input Labels to Remove string Value List removeLabels | Notes A list of labels to add (optional) | Example |
Input Gmail User ID (optional) string userId | Notes A user whose account to query (defaults to currently authenticated user) | Example |