Gmail Connector Reference

The following operations allow you to work with the Gmail Connector. Click an operation name to see parameter details and samples on how to use it.

---

Connection configuration

The Gmail API uses OAuth2 authentication with Tokens. For more information on authentication, go to Authorizing Your App with Gmail.

GMAIL Connection

Parameter Name	Description	Required
clientId	Value of the Client ID you obtained when you registered your application with Gmail API.	Yes
clientSecret	Value of the Client Secret you obtained when you registered your application with the Gmail API.	Yes
refreshToken	Value of the Refresh Token, which generates a new Access Token when the previous one gets expired.	Yes
apiUrl	The API URL of Gmail (https://www.googleapis.com/gmail).	Yes
apiVersion	Version of the Gmail API.	Yes
userId	User mail ID.	Yes
tokenEndpoint	The token endpoint URL for OAuth authentication.	Yes

Sample configuration

<gmail.init>
    <connectionType>GMAIL</connectionType>
    <clientId>00339149310-2h1dc24k9d5sn22k309dc578agjjwso2.apps.googleusercontent.com</clientId>
    <clientSecret>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</clientSecret>
    <refreshToken>1//04CeqvBsifESwCgYIARAAGAQSNwF-L9IrBtD40NRB0jiWSO20x5hOHhNppXnB9S9VKvguwUVVkZSp_OkL-MI-tFwahvF5K7reXUI</refreshToken>
    <apiUrl>https://www.googleapis.com/gmail</apiUrl>
    <apiVersion>v1</apiVersion>
    <userId>me</userId>
    <tokenEndpoint>https://oauth2.googleapis.com/token</tokenEndpoint>
    <name>CONN</name>
</gmail.init>

Mail Management

listAllMails

The listAllMails operation lists all messages. See the related API documentation for more information.

Parameter Name	Description	Required
includeSpamTrash	Includes messages from SPAM and TRASH in the results (default: false).	Yes
labelIds	Only returns messages with labels that match all of the specified label IDs.	Yes
maxResults	Maximum number of messages to return.	Yes
pageToken	Page token to retrieve a specific page of results in the list.	Yes
q	Only returns messages matching the specified query. Supports the same query format as the Gmail search box.	Yes

Sample configuration

<gmail.listAllMails configKey="GmailConnection">
    <includeSpamTrash>{${payload.includeSpamTrash}}</includeSpamTrash>
    <labelIds>{${payload.labelIds}}</labelIds>
    <maxResults>{${payload.maxResults}}</maxResults>
    <pageToken>{${payload.pageToken}}</pageToken>
    <q>{${payload.q}}</q>
    <responseVariable>gmail_listAllMails_1</responseVariable>
    <overwriteBody>false</overwriteBody>
</gmail.listAllMails>

Sample request

{
    "maxResults":"10",
    "includeSpamTrash":"true",
    "pageToken":"00965906535058580458",
    "labelIds":"UNREAD",
    "q":"Jira"
}

readMail

The readMail operation retrieves a message by its ID. See the related API documentation for more information.

Parameter Name	Description	Required
id	The ID of the message to retrieve.	Yes
format	The format to return.	Yes
metadataHeaders	When the format is METADATA, only include the headers specified in this property.	Yes

Sample configuration

<gmail.readMail ConfigKey="GmailConnection">
    <id>{${payload.id}}</id>
    <format>{${payload.format}}</format>
    <metadataHeaders>{${payload.metadataHeaders}}</metadataHeaders>
    <responseVariable>gmail_readMail_1</responseVariable>
    <overwriteBody>false</overwriteBody>
</gmail.readMail>

Sample request

{
    "id":"14bbb686ba287e1d",
    "format":"minimal"
}

sendMail

The sendMail operation sends a plain message. See the related API documentation for more information.

Parameter Name	Description	Required
to	The email address of the recipient of the message.	Yes
subject	Subject of the message.	Yes
from	The email address of the sender of the message.	Yes
cc	The email addresses of recipients who will receive a copy of this message.	Yes
bcc	The email addresses of recipients who will privately receive a copy of this message (their email addresses will be hidden).	Yes
messageBody	The content of the message.	Yes
contentType	If the message body is in the format of html or need to send a rich text then we must give the parameter value as "text/html; charset=UTF-8" otherwise it takes the default value as text/plain.	Yes

Sample configuration

<gmail.sendMail configKey="GmailConnection">
    <to>{${payload.to}}</to>
    <subject>{${payload.subject}}</subject>
    <from>{${payload.from}}</from>
    <cc>{${payload.cc}}</cc>
    <bcc>{${payload.bcc}}</bcc>
    <messageBody>{${payload.messageBody}}</messageBody>
    <contentType>{${payload.contentType}}</contentType>
    <responseVariable>gmail_sendMail_1</responseVariable>
    <overwriteBody>false</overwriteBody>
</gmail.sendMail>

Sample request

{
    "to":"[email protected]",
    "subject":"Hello",
    "cc":"[email protected]",
    "bcc":"[email protected]",
    "messageBody":"Hello! Thank you for contacting us.",
    "contentType":"text/html; charset=UTF-8"
}

modifyExistingMessage

The modifyExistingMessage operation modifies an existing message. See the related API documentation for more information.

Parameter Name	Description	Required
id	The ID of the message to modify.	Yes
addLabelIds	A list of IDs of labels to add to this message.	Yes
removeLabelIds	A list of IDs of labels to remove from this message.	Yes

Sample configuration

<gmail.modifyExistingThread configKey="GmailConnection">
    <id>{${payload.id}}</id>
    <addLabelIds>{${payload.addLabelIds}}</addLabelIds>
    <removeLabelIds>{${payload.removeLabelIds}}</removeLabelIds>
    <responseVariable>gmail_modifyExistingThread_1</responseVariable>
    <overwriteBody>false</overwriteBody>
</gmail.modifyExistingThread>

Sample request

{
    "id":"14ba5cd56fcb61ee",
    "addLabelIds": [
        "Label_33",
        "Label_24"],
    "removeLabelIds": [
        "Label_28",
        "Label_31"]
}

trashMessage

The trashMessage operation sends a message to the trash. See the related API documentation for more information.

Parameter Name	Description	Required
id	The ID of the message to send to trash.	Yes

Sample configuration

<gmail.trashMessage configKey="GmailConnection">
    <id>{${payload.id}}</id>
    <responseVariable>gmail_trashMessage_1</responseVariable>
    <overwriteBody>false</overwriteBody>
</gmail.trashMessage>

Sample request

{
    "id":"4647683792802"
}

unTrashMessage

The unTrashMessage operation removes a message from trash. See the related API documentation for more information.

Parameter Name	Description	Required
id	The ID of the message to untrash.	Yes

Sample configuration

<gmail.unTrashMessage configKey="GmailConnection">
    <id>{${payload.id}}</id>
    <responseVariable>gmail_unTrashMessage_1</responseVariable>
    <overwriteBody>false</overwriteBody>
</gmail.unTrashMessage>

Sample request

{
    "id":"4647683792802"
}

deleteMessage

The deleteMessage operation permanently deletes a message. The message cannot be recovered after it is deleted. You can use trashMessages instead if you do not want to permanently delete the message. See the related API documentation for more information.

Parameter Name	Description	Required
id	The ID of the message to delete.	Yes

Sample configuration

<gmail.deleteMessage configKey="GmailConnection">
    <id>{${payload.id}}</id>
    <responseVariable>gmail_deleteMessage_1</responseVariable>
    <overwriteBody>false</overwriteBody>
</gmail.deleteMessage>

Sample request

{
    "id":"4647683792802"
}

sendMailWithAttachment

The sendMailWithAttachment operation sends a message with attachments. See the related API documentation for more information.

Parameter Name	Description	Required
to	The email addresses of the recipients of the message.	Yes
subject	Subject of the message.	Yes
cc	The email addresses of recipients who will receive a copy of this message.	Yes
bcc	The email addresses of recipients who will privately receive a copy of this message (their email addresses will be hidden).	Yes
fileName	A comma-seperated list of file names of the attachments you want to include with the message.	Yes
filePath	A comma-seperated list of file paths of the attachments you want to include with the message.	Yes
messageBody	Content of the message.	Yes

Sample configuration

<gmail.sendMailWithAttachment configKey="GmailConnection">
    <subject>{${payload.subject}}</subject>
    <to>{${payload.to}}</to>
    <cc>{${payload.cc}}</cc>
    <bcc>{${payload.bcc}}</bcc>
    <messageBody>{${payload.messageBody}}</messageBody>
    <fileName>{${payload.fileName}}</fileName>
    <filePath>{${payload.filePath}}</filePath>
    <responseVariable>gmail_sendMailWithAttachment_1</responseVariable>
    <overwriteBody>false</overwriteBody>
</gmail.sendMailWithAttachment>

Sample request

{
    "subject":"WSO2 Gmail Connector",
    "to":"[email protected]",
    "cc":"[email protected]",
    "bcc":"[email protected]",
    "messageBody":"Welcome to WSO2 ESB Gmail Connector!!!!!",
    "fileName":"/home/rajjaz/Documents/ESB/esb-connector-gmail/src/test/resources/artifacts/ESB/config/smile.png",
    "filePath":"smile.png"
}

Drafts Management

listDrafts

The listDrafts operation lists all drafts in Gmail. See the related API documentation for more information.

Parameter Name	Description	Required
maxResults	Maximum number of messages to return.	Yes
pageToken	Page token to retrieve a specific page of results in the list.	Yes

Sample configuration

<gmail.listDrafts configKey="GmailConnection">
    <maxResults>{${payload.maxResults}}</maxResults>
    <pageToken>{${payload.pageToken}}</pageToken>
    <responseVariable>gmail_listDrafts_1</responseVariable>
    <overwriteBody>false</overwriteBody>
</gmail.listDrafts>

Sample request

{
    "maxResults":"10",
    "pageToken":"09876536614133772469"
}

readDraft

The readDraft operation retrieves a particular draft email. See the related API documentation for more information.

Parameter Name	Description	Required
id	The ID of the draft email to be retrieve	Yes
format	The format to return the draft in	Yes

Sample configuration

<gmail.readDraft configKey="GmailConnection">
    <id>{${payload.id}}</id>
    <format>{${payload.format}}</format>
    <responseVariable>gmail_readDraft_1</responseVariable>
    <overwriteBody>false</overwriteBody>
</gmail.readDraft>

Sample request

{
    "id": "1492984134337920839",
    "format":"raw"
}

deleteDraft

The deleteDraft operation deletes an existing draft. See the related API documentation for more information.

Parameter Name	Description	Required
id	The ID of the draft email to be deleted.	Yes

Sample configuration

<gmail.deleteDraft configKey="GmailConnection">
    <id>{${payload.id}}</id>
    <responseVariable>gmail_deleteDraft_1</responseVariable>
    <overwriteBody>false</overwriteBo`dy>
</gmail.deleteDraft>

Sample request

{
    "id":"1491513685150755887"
}

createDraft

The createDraft operation creates a new draft. See the related API documentation for more information.

Parameter Name	Description	Required
to	The email address of the recipient of this email.	Yes
subject	Subject of the email.	Yes
from	The email address of the sender of the email.	Yes
cc	The email addresses of recipients who will receive a copy of this email.	Yes
bcc	The email addresses of recipients who will privately receive a copy of this email (their email addresses will be hidden from each other).	Yes
threadId	ID of the thread.	Yes
id	ID of the email.	Yes
messageBody	Content of the email.	Yes
contentType	If the message body is in the format of HTML or if you need to send a rich text then you must give the parameter value as "text/html; charset=UTF-8" otherwise it takes the default value as text/plain.	Yes

Sample configuration

<gmail.createDraft configKey="GmailConnection">
    <to>{${payload.to}}</to>
    <subject>{${payload.subject}}</subject>
    <from>{${payload.from}}</from>
    <cc>{${payload.cc}}</cc>
    <bcc>{${payload.bcc}}</bcc>
    <id>{${payload.id}}</id>
    <threadId>{${payload.threadId}}</threadId>
    <messageBody>{${payload.messageBody}}</messageBody>
    <contentType>{${payload.contentType}}</contentType>
    <responseVariable>gmail_createDraft_1</responseVariable>
    <overwriteBody>false</overwriteBody>
</gmail.createDraft>

Sample request

{
    "to":"[email protected]",
    "from":"[email protected]",
    "subject":"test",
    "messageBody":"Hi hariprasath",
    "cc":"[email protected]",
    "bcc":"[email protected]",
    "id":"154b8c77e551c509",
    "threadId":"154b8c77e551c509",
    "contentType":"text/html; charset=UTF-8"
}

Labels Management

listLabels

The listLabels operation lists all existing labels. See the related API documentation for more information.

Sample configuration

</gmail.listLabels configKey="GmailConnection">
    <responseVariable>gmail_listLabels_1</responseVariable>
    <overwriteBody>false</overwriteBody>
</gmail.listLabels>

readLabel

The readLabel operation gets a label's details. See the related API documentation for more information.

Parameter Name	Description	Required
id	The ID of the label whose details you want to retrieve.	Yes

Sample configuration

<gmail.readLabel configKey="GmailConnection">
    <id>{${payload.id}}</id>
    <responseVariable>gmail_readLabel_1</responseVariable>
    <overwriteBody>false</overwriteBody>
</gmail.readLabel>

Sample request

{
    "id":"Label_1"
}

deleteLabel

The deleteLabel operation deletes a label. See the related API documentation for more information.

Parameter Name	Description	Required
id	The ID of the label to be deleted.	Yes

Sample configuration

<gmail.deleteLabel configKey="GmailConnection">
    <id>{${payload.id}}</id>
    <responseVariable>gmail_deleteLabel_1</responseVariable>
    <overwriteBody>false</overwriteBody>
</gmail.deleteLabel>

Sample request

{
    "id":"57648478394803"
}

createLabel

The createLabel operation creates a new label. See the related API documentation for more information.

Parameter Name	Description	Required
name	The display name of the label.	Yes
messageListVisibility	The visibility of messages with this label in the message list in the Gmail web interface.	Yes
labelListVisibility	The visibility of the label in the label list in the Gmail web interface.	Yes
type	The owner type for the label.	Yes
messagesTotal	The total number of messages with the label.	Yes
messagesUnread	The number of unread messages with the label.	Yes
threadsTotal	The total number of threads with the label.	Yes
threadsUnread	The number of unread threads with the label.	Yes

Sample configuration

<gmail.createLabel configKey="GmailConnection">
    <name>{${payload.name}}</name>
    <messageListVisibility>{${payload.messageListVisibility}}</messageListVisibility>
    <labelListVisibility>{${payload.labelListVisibility}}</labelListVisibility>
    <type>{${payload.type}}</type>
    <messagesTotal>{${payload.messagesTotal}}</messagesTotal>
    <messagesUnread>{${payload.messagesUnread}}</messagesUnread>
    <threadsTotal>{${payload.threadsTotal}}</threadsTotal>
    <threadsUnread>{${payload.threadsUnread}}</threadsUnread>
    <responseVariable>gmail_createLabel_1</responseVariable>
    <overwriteBody>false</overwriteBody>
</gmail.createLabel>

Sample request

{
    "name": "TestESB2",
    "threadsUnread": 100,
    "messageListVisibility": "show",
    "threadsTotal": 100,
    "type": "user",
    "messagesTotal": 100,
    "messagesUnread": 100,
    "labelListVisibility": "labelShow"
}

updateLabel

The updateLabel operation updates an existing label. See the related API documentation for more information.

Parameter Name	Description	Required
name	The display name of the label.	Yes
messageListVisibility	The visibility of messages with this label in the message list in the Gmail web interface.	Yes
labelListVisibility	The visibility of the label in the label list in the Gmail web interface.	Yes
type	The owner type for the label.	Yes
messagesTotal	The total number of messages with the label.	Yes
messagesUnread	The number of unread messages with the label.	Yes
threadsTotal	The total number of threads with the label.	Yes
threadsUnread	The number of unread threads with the label.	Yes
id	The ID of the label to update.	Yes

Sample configuration

<gmail.updateLabel configKey="GmailConnection">
    <name>{${payload.name}}</name>
    <messageListVisibility>{${payload.messageListVisibility}}</messageListVisibility>
    <labelListVisibility>{${payload.labelListVisibility}}</labelListVisibility>
    <type>{${payload.type}}</type>
    <messagesTotal>{${payload.messagesTotal}}</messagesTotal>
    <messagesUnread>{${payload.messagesUnread}}</messagesUnread>
    <threadsTotal>{${payload.threadsTotal}}</threadsTotal>
    <threadsUnread>{${payload.threadsUnread}}</threadsUnread>
    <id>{${payload.id}}</id>
    <responseVariable>gmail_updateLabel_1</responseVariable>
    <overwriteBody>false</overwriteBody>
</gmail.updateLabel>

Sample request

{
    "id":"426572682792",
    "name": "TestESB2",
    "threadsUnread": 100,
    "messageListVisibility": "show",
    "threadsTotal": 100,
    "type": "user",
    "messagesTotal": 100,
    "messagesUnread": 100,
    "labelListVisibility": "labelShow"
}

Threads

listAllThreads

The listAllThreads operation lists all the existing email threads. See the related API documentation for more information.

Parameter Name	Description	Required
includeSpamTrash	Include messages from SPAM and TRASH in the results (default: false).	Yes
labelIds	Only returns threads with labels that match all of the specified label IDs.	Yes
maxResults	Maximum number of messages to return.	Yes
pageToken	Page token to retrieve a specific page of results in the list.	Yes
q	Only returns messages matching the specified query. Supports the same query format as the Gmail search box.	Yes

Sample configuration

<gmail.listAllThreads configKey="GmailConnection">
    <includeSpamTrash>{${payload.includeSpamTrash}}</includeSpamTrash>
    <labelIds>{${payload.labelIds}}</labelIds>
    <maxResults>{${payload.maxResults}}</maxResults>
    <pageToken>{${payload.pageToken}}</pageToken>
    <q>{${payload.q}}</q>
    <responseVariable>gmail_listAllThreads_1</responseVariable>
    <overwriteBody>false</overwriteBody>
</gmail.listAllThreads>

Sample request

{
    "maxResults":"10",
    "includeSpamTrash":"true",
    "pageToken":"00965906535058580458",
    "labelIds":"UNREAD",
    "q":"Jira"
}

readThread

The readThread operation retrieves an existing thread. See the related API documentation for more information.

Parameter Name	Description	Required
id	The ID of the thread to retrieve.	Yes
format	The format in which to return the messages in the thread.	Yes
metadataHeaders	When the format is METADATA, only include the headers specified with this property.	Yes

Sample configuration

<gmail.readThread configKey="GmailConnection">
    <id>{${payload.id}}</id>
    <format>{${payload.format}}</format>
    <metadataHeaders>{${payload.metadataHeaders}}</metadataHeaders>
    <responseVariable>gmail_readThread_1</responseVariable>
    <overwriteBody>false</overwriteBody>
</gmail.readThread>

Sample request

{
    "id":"14bbb686ba287e1d",
    "format":"minimal"
}

trashThreads

The trashThreads operation sends a thread to the trash. See the related API documentation for more information.

Parameter Name	Description	Required
id	The ID of the thread to trash.	Yes

Sample configuration

<gmail.trashThread configKey="GmailConnection">
    <id>{${payload.id}}</id>
    <responseVariable>gmail_trashThread_1</responseVariable>
    <overwriteBody>false</overwriteBody>
</gmail.trashThread>

Sample request

{
    "id":"14bbb686ba287e1d"
}

unTrashThreads

The unTrashThreads operation removes a thread from the trash. See the related API documentation for more information.

Parameter Name	Description	Required
id	The ID of the thread to untrash.	Yes

Sample configuration

<gmail.unTrashThread configKey="GmailConnection">
    <id>{${payload.id}}</id>
    <responseVariable>gmail_unTrashThread_1</responseVariable>
    <overwriteBody>false</overwriteBody>
</gmail.unTrashThread>

Sample request

{
    "id":"14bbb686ba287e1d"
}

modifyExistingThread

The modifyExistingThread operation modifies an existing thread. See the related API documentation for more information.

Parameter Name	Description	Required
id	The ID of the thread to modify.	Yes
addLabelIds	A list of IDs of labels to add to this thread.	Yes
removeLabelIds	A list of IDs of labels to remove from this thread.	Yes

Sample configuration

<gmail.modifyExistingThread configKey="GmailConnection">
    <id>{${payload.id}}</id>
    <addLabelIds>{${payload.addLabelIds}}</addLabelIds>
    <removeLabelIds>{${payload.removeLabelIds}}</removeLabelIds>
    <responseVariable>gmail_modifyExistingThread_1</responseVariable>
    <overwriteBody>false</overwriteBody>
</gmail.modifyExistingThread>

Sample request

{
    "id":"14b31c7af7b778f4",
    "addLabelIds": [
        "Label_33",
        "Label_24"],
    "removeLabelIds": [
        "Label_28",
        "Label_31"]
}

deleteThread

The deleteThreads operation deletes the specified thread`. See the related API documentation for more information.

Parameter Name	Description	Required
id	The ID of the thread to delete.	Yes

Sample configuration

<gmail.deleteThread configKey="GmailConnection">
    <id>{${payload.id}}</id>
    <responseVariable>gmail_deleteThread_1</responseVariable>
    <overwriteBody>false</overwriteBody>
</gmail.deleteThread>

Sample request

{
    "id":"14b31c7af7b778f4"
}

Account Management

listTheHistory

The listTheHistory operation lists the history of changes to the user's mailbox. See the related API documentation for more information.

Parameter Name	Description	Required
startHistoryId	Returns history records after the specified startHistoryId.	Yes
maxResults	The maximum number of history records to return.	Yes
pageToken	Page token to retrieve a specific page of results in the list.	Yes

Sample configuration

<gmail.listTheHistory configKey="GmailConnection">
    <startHistoryId>{${payload.startHistoryId}}</startHistoryId>
    <labelId>{${payload.labelId}}</labelId>
    <maxResults>{${payload.maxResults}}</maxResults>
    <pageToken>{${payload.pageToken}}</pageToken>
    <responseVariable>gmail_listTheHistory_1</responseVariable>
    <overwriteBody>false</overwriteBody>
</gmail.listTheHistory>

Sample request

{
    "startHistoryId":"7399652",
    "labelId":"Label_31",
    "maxResults":"10"
}

getUserProfile

The getUserProfile operation lists all details about the user's profile. See the related API documentation for more information.

Sample configuration

<gmail.getUserProfile configKey="GmailConnection">
    <responseVariable>gmail_getUserProfile_1</responseVariable>
    <overwriteBody>false</overwriteBody>
</gmail.getUserProfile>

endSession

The endSession operation terminates the authenticated IMAP and SMTP connections with Gmail.

Sample configuration

<gmail.endSession configKey="GmailConnection">
    <responseVariable >gmail_endSession_1</responseVariable>
    <overwriteBody >false</overwriteBody>
</gmail.endSession>