Skip to main content

Gmail Component

Manage Messages in Google's email service

Component key: google-gmail

Description#

Gmail 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#

OAuth2#

The 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:

  1. Open up the Gmail API console - https://console.cloud.google.com/marketplace/product/google/gmail.googleapis.com
  2. You will be prompted to enable Gmail API for your project. Click ENABLE.
  3. On the sidebar, select APIs & Services and then Credentials.
  4. 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.
    1. Your app will be externally available to your customers, so choose a User Type of External.
    2. Fill out the OAuth consent screen with an app name (your company or product's name), support email, app logo, domain, etc.
    3. You can ignore domains for now.
    4. On the next page, ignore scopes - this component knows what scopes it needs to run and will request the right scopes for you.
    5. 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.
  5. Once your "Consent Screen" is configured open the Credentials page from the sidebar again.
  6. Click +CREATE CREDENTIALS and select OAuth Client ID.
    1. Under Application type select Web application.
    2. Under Authorized redirect URIs enter Prismatic's OAuth 2.0 callback URL: https://oauth2.prismatic.io/callback
    3. Click CREATE.
  7. 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.

InputDefaultNotes
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 User#

Get metadata about the authenticated user | key: getCurrentUser

InputNotes
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 Name#

Get a label (including ID) by its name | key: getLabelByName

InputNotes
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 Message#

Get a message by ID | key: getMessageById

InputNotesExample
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> &lt;<a href=\"mailto:example@gmail.com\" class=\"mp_address_email\">example@gmail.com</a>&gt;</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> &lt;<a href=\"mailto:example@gmail.com\" class=\"mp_address_email\">example@gmail.com</a>&gt;</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 Labels#

List all labels within this account | key: listLabels

InputNotes
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 Messages#

Get a list of messages | key: listMessages

InputNotesExample
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 Request#

Send a raw request to Google Gmail | key: rawRequest

InputDefaultNotesExample
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 Message#

Send a new message | key: sendMessage

InputNotes
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 Message#

Send a message to the trash | key: trashMessageById

InputNotesExample
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 Message#

Remove a message from the trash | key: unTrashMessageById

InputNotesExample
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 Labels#

Add or remove labels from a message | key: updateLabels

InputNotesExample
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