Skip to main content

Cyware Orchestrate

Gmail API

App Vendor: Google

App Category: Messaging

Connector Version: 1.1.0

API Version: v1

About App

With the Gmail API app, a web-based email service provided by Google, you can perform all the supported email-related operations to manage your emails. This app is based on Google authorized library googleapiclient and google auth.

The Gmail API app is configured with Orchestrate to perform the following actions:

Action Name

Description

Delete Email

This action permanently deletes an email.

Get Attachment

This action downloads attachments from an email.

Get Email

This action retrieves an email.

Get Filter Details

This action retrieves the details of a filter.

Get Label Details

This action retrieves the details of a label.

List Emails

This action lists email IDs.

List Filters

This action lists filter IDs.

List Labels

This action lists label names, types, and IDs.

Send Email

This action sends an email.

Trash Email

This action moves a message to the trash folder.

Create Label

This action creates a label in Google Gmail.

Move Mail Under a Label

This action moves an email under a specific label.

Configuration Parameters

The following configuration parameters are required for the Gmail API app to communicate with the Gmail API enterprise application. The parameters can be configured by creating instances in the app.

Parameter

Description

Field Type

Required/Optional

Comments

User Email

Enter the user email ID.

Text

Required

 

Credential File

Upload the credential file in .json format.

File

Required

For more information on generating credentials file, see Generate Credentials File for Gmail API.

Scope

Enter the scope that defines the level of access that you need to perform the required operations on Gmail.

List

Optional

Default value:

https://mail.google.com

Allowed values:

  • https://mail.google.com/

  • https://www.googleapis.com/auth/gmail.modify

  • https://www.googleapis.com/auth/gmail.compose

  • https://www.googleapis.com/auth/gmail.send and more 

    For more information on the allowed values, see Scopes. 

Action: Delete Email

This action permanently deletes an email. This action requires the following OAuth scope:

https://mail.google.com/

Action Input Parameters

Parameter

Description

Field Type

Required/Optional

Comments

Mail ID

Enter the ID of an email to delete.

Example:

"18848e2daxx4693d"

Text

Required

You can retrieve the mail ID using the action List Emails.

Example Request 

[
    {
        "message_id": "18848e2daxx4693d"
    }
]
Action: Get Attachment

This action downloads attachments from an email. This action requires one of the following OAuth scopes:

  • https://mail.google.com/

  • https://www.googleapis.com/auth/gmail.modify

  • https://www.googleapis.com/auth/gmail.readonly

Action Input Parameters

Parameter

Description

Field Type

Required/Optional

Comments

Attachment ID

Enter the attachment ID to download the attachment.

Example:

"ANGjdJ825xg4ZisSwaSsAdgsuvY-btgWrAftZMtNZLaKxZg5NNEzGbYZs1t9UJ1RGCDGtpToxxx9IelG4BirRLHrvrmWMAr46IyAnTu-IKy6At7RLXdBve4AsZ1qNLpou-mI23PUahWtz22xxf2PTi6_Prxxv8SQULqEBYJnOa4ZS25xU51Upx0exxFMI4Ej68jBC1uWmlY0j1SN4-iyO1iaKD0FjQSusmjPJ5MjS6FYccotxbJ9dXjxxe2B3Ti9tmdej7SaJ4cQvNpUSluBLDNamxxZdvJ9lwdhFBq8omJhWexxezXv2cAv4dTwatbRUgVjJHgCKgMsk1aZNVxOjZEtEbzw-bo6ZAYnlK0sqf9EhSOMoFvF-UxrF4DYDFI"

Text

Required

You can retrieve attachment ID using the action Get Email.

Mail ID

Enter the email ID from which you want to download the attachment.

Example:

"188355769xx24deb"

Text

Required

You can retrieve a mail ID using the action List Emails.

File Name

Enter the file name to save the attachment.

Example: "Phishing_attachment_details"

Text

Optional

Default value:

{mail_id}_attachment

Example Request

[
    {
        "mail_id": "18843ba8fxx574d5",
        "file_name": "Phishing Details",
        "attachment_id": "ANGjdJ825xg4ZisSwaSsAdgsuvY-btgWrAftZMtNZLaKxZg5NNEzGbYZs1t9UJ1RGCDGtpToxxx9IelG4BirRLHrvrmWMAr46IyAnTu-IKy6At7RLXdBve4AsZ1qNLpou-mI23PUahWtz22xxf2PTi6_Prxxv8SQULqEBYJnOa4ZS25xU51Upx0exxFMI4Ej68jBC1uWmlY0j1SN4-iyO1iaKD0FjQSusmjPJ5MjS6FYccotxbJ9dXjxxe2B3Ti9tmdej7SaJ4cQvNpUSluBLDNamxxZdvJ9lwdhFBq8omJhWexxezXv2cAv4dTwatbRUgVjJHgCKgMsk1aZNVxOjZEtEbzw-bo6ZAYnlK0sqf9EhSOMoFvF-UxrF4DYDFI"
    }
]
Action: Get Email

This action retrieves an email. This action requires one of the following OAuth scopes:

  • https://mail.google.com/

  • https://www.googleapis.com/auth/gmail.modify

  • https://www.googleapis.com/auth/gmail.readonly

  • https://www.googleapis.com/auth/gmail.metadata

Action Input Parameters

Parameter

Description

Field Type

Required/Optional

Comments

Mail ID

Enter the ID of an email to retrieve.

Example:

"1883557xxb224deb"

Text

Required

You can retrieve the mail ID using the action List Emails.

Get Attachment

Enter true to get an attachment with the email.

Example:

false

Boolean

Optional

Default value:

false

Allowed values:

  • true

  • false

Format

Enter the format to see the email response. 

Example:

full

Text

Optional

Default value:

None

Allowed values:

  • minimal

  • full

  • raw

Example Request

[
    {
        "mail_id": "18843ba8xx2574d5",
        "get_attachment": true
    }
]
Action: Get Filter Details

This action retrieves the details of a filter. This action requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/gmail.settings.basic

  • https://mail.google.com/

  • https://www.googleapis.com/auth/gmail.modify

  • https://www.googleapis.com/auth/gmail.readonly

Action Input Parameters

Parameter

Description

Field Type

Required/Optional

Comments

Filter ID

Enter the ID of a filter to retrieve its details.

Example:

"122xx656"

Text

Required

Example Request 

[
    {
        "filter_id":"122xx656"
    }
]
Action: Get Label Details

This action retrieves the details of a label. This action requires one of the following OAuth scopes:

  • https://mail.google.com/

  • https://www.googleapis.com/auth/gmail.modify

  • https://www.googleapis.com/auth/gmail.readonly

  • https://www.googleapis.com/auth/gmail.labels

  • https://www.googleapis.com/auth/gmail.metadata

Action Input Parameters

Parameter

Description

Field Type

Required/Optional

Comments

Label ID

Enter the label ID.

Example:

"UNREAD"

Text

Required

Example Request 

[
    {
        "label_id":"UNREAD"
    }
]
Action: List Emails

This action lists email IDs. This action requires one of the following OAuth scopes:

  • https://mail.google.com/

  • https://www.googleapis.com/auth/gmail.modify

  • https://www.googleapis.com/auth/gmail.readonly

  • https://www.googleapis.com/auth/gmail.metadata

Action Input Parameters

Parameter

Description

Field Type

Required/Optional

Comments

Filter Query

Enter the query to filter the results. Filter query supports the same query format as the Gmail search box.

Example:

"from:someuser@example.com rfc822msgid:<somemsgid@example.com> is:unread"

Text

Optional

 

Max Result

Enter the number of email IDs you want to retrieve per page.

Example:

10

Integer

Optional

Default value:

100

Maximum allowed value:

500

Include Spam

Enter true to retrieve emails from the trash or spam folder.

Example:

true

Boolean

Optional

 

Label ID

Enter the label ID to retrieve the emails associated with a label.

Example:

"UNREAD"

Text

Optional

 

Next Page Token

Enter the page token to retrieve results from a specific page.

Example:

"15231456423050042906"

Text

Optional

 

Example Request

[
    {
        "label_id":"from:someuser@example.com rfc822msgid:<somemsgid@example.com> is:unread"
    }
]
Action: List Filters

This action lists email filter IDs. This action requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/gmail.settings.basic

  • https://mail.google.com/

  • https://www.googleapis.com/auth/gmail.modify

  • https://www.googleapis.com/auth/gmail.readonly

Action Input Parameters

This action does not require any action input parameter.

Action: List Labels

This action lists label names, types, and IDs. This action requires one of the following OAuth scopes:

  • https://mail.google.com/

  • https://www.googleapis.com/auth/gmail.modify

  • https://www.googleapis.com/auth/gmail.readonly

  • https://www.googleapis.com/auth/gmail.labels

  • https://www.googleapis.com/auth/gmail.metadata

Action Input Parameters

This action does not require any action input parameter.

Action: Send Email

This action sends an email. This action requires one of the following OAuth scopes:

  • https://mail.google.com/

  • https://www.googleapis.com/auth/gmail.modify

  • https://www.googleapis.com/auth/gmail.compose

  • https://www.googleapis.com/auth/gmail.send

Action Input Parameters

Parameter

Description

Field Type

Required/Optional

Comments

Receiver Mail Address

Enter the receivers mail address in comma-separated format.

Example:

"john.doe@org.com,jerry.d@org.com"

Text

Required

 

Subject

Enter the email subject.

Example:

"Phishing Campaign"

Text

Required

 

CC Recipients

Enter the mail address of CC recipients in comma-separated format.

Example:

"jack.carry@org.com,matt.d@org.com"

Text

Optional

 

BCC Recipients

Enter the mail address of BCC recipients in comma-separated format.

Example:

"lerry.k@org.com,john.p@org.com"

Text

Optional

 

Sender Mail Address

Enter the sender's email address.

Example:

"johnathan.rose@org.com"

Text

Optional

Default value:

user_email

Email Body

Enter the email body.

Example:

"Details of a phishing campaign"

Text

Optional

 

HTML Body

Enter the body in HTML format.

Example:

"<h1>List of items<ul><li>Displays the phishing campaign details</li></ul></h1>"

Text

Optional

 

File Path

Enter the file path of attachments to send with the email in list format. Example: ['tmp/1223442/phishing.txt']

List

Optional

 

Example Request

[
    {
        "subject":"Phishing Campaign",
        "email_body":"Details of a phishing campaign",
        "receiver_mail_address":"john.doe@org.com,jerry.d@org.com"
    }
]
Action: Trash Email

This action moves an email to the trash folder. This action requires one of the following OAuth scopes:

  • https://mail.google.com/

  • https://www.googleapis.com/auth/gmail.modify

Action Input Parameters

Parameter

Description

Field Type

Required/Optional

Comments

Mail ID

Enter the ID of the email to move to the trash folder.

Example:

"18848e2daxx4693d"

Text

Required

You can retrieve the mail ID using the action List Emails.

Example Request

[
    {
        "message_id": "18848e2daxx4693d"
    }
]
Action: Create Label

This action creates a label in Google Gmail. This action requires one of the following OAuth scopes:

  • https://mail.google.com/

  • https://www.googleapis.com/auth/gmail.modify

  • https://www.googleapis.com/auth/gmail.labels

Action Input Parameters

Parameter

Description

Field Type

Required/Optional

Comments

Label Query

Enter a query to create a label.

Example:

{'name':'Phishing','labelListVisibility':'labelShow'}

Key Value

Optional

For more information on the allowed keys and values, see Labels.

Example Request

[
    {
        "label_query": {
            "name": "Phishing",
            "labelListVisibility": "labelShow"
        }
    }
]
Action: Move Mail Under a Label

This action moves an email under a specific label. This action requires one of the following OAuth scopes:

  • https://mail.google.com/

  • https://www.googleapis.com/auth/gmail.modify

Action Input Parameters

Parameter

Description

Field Type

Required/Optional

Comments

Mail ID

Enter the mail ID to move the email into specific labels.

Example:

1883557xxb224deb

Text

Required

 

Add Label ID

Enter the label IDs to add to the mail.

Example:

$LIST[Label_3196092558537540937, Label_4578900998537540937]

List

Required

 

Remove Label ID

Enter the label IDs to remove from the mail.

Example:

$LIST[UNREAD]

List

Required

Example Request

[
    {
        "mail_id": "1883557xxb224deb",
        "label_id": [
            "Label_31960925585xx540937"
        ],
        "remove_label_id": [
            "UNREAD"
        ]
    }
]