InsightConnect Marketplace

Gmail

Back to Marketplace

Gmail

v6.0.1

Gmail is a free cloud-based email service from Google. Using the Gmail plugin for Rapid7 InsightConnect, users can interact with and manage both consumer and G Suite Gmail accounts, including monitoring incoming email, managing email, and more

Tags: google, gmail, email

Triggers
  • Email Received

Actions
  • Batch Modify Emails
  • Batch Modify Emails by Query
  • Delete Email by ID
  • Find Emails
  • Find One Email
  • Get Email by ID
  • Modify Email
  • Send Email

Description

Gmail is a free cloud-based email service from Google. Using the Gmail plugin for Rapid7 InsightConnect, users can interact with and manage both consumer and G Suite Gmail accounts, including monitoring incoming email, managing email, and more. Perform phishing analysis, attachment analysis, email deletion, and more when using this plugin in a Rapid7 InsightConnect workflow.

Key Features

  • Email monitoring
  • Email management
  • Send email

Requirements

  • Project ID
  • Private Key ID
  • Private Key
  • Client email (from service credentials)
  • Client ID
  • Client x509 Certificate URL
  • Authentication URI
  • Token URI
  • Authentication Provider x509 Certificate URL
  • OAuth scope (full API scopes are listed here.
  • Service account with the appropriate access to the Gmail API
  • Service account must have 'domain-wide' delegation enabled

Documentation

Setup

Check out the plugin guide for more details on how to configure this plugin.

The connection configuration accepts the following parameters:

|Name|Type|Default|Required|Description|Enum|Example| |----|----|-------|--------|-----------|----|-------| |auth_provider_x509_cert_url|string|https://www.googleapis.com/oauth2/v1/certs|True|OAUTH2 Auth Provider x509 Cert URL|None|https://www.googleapis.com/oauth2/v1/certs| |auth_uri|string|https://accounts.google.com/o/oauth2/auth|True|OAUTH2 Auth URI|None|https://accounts.google.com/o/oauth2/auth| |client_email|string|None|True|Client email from service credentials|None|example@sincere-hybrid-125985.iam.gserviceaccount.com| |client_id|string|None|True|Client ID|None|102790495738029996994| |client_x509_cert_url|string|None|True|x509 cert URL from service credentials|None|https://www.googleapis.com/robot/v1/metadata/x509/icon%40ssincere-hybrid-125985.iam.gserviceaccount.com| |oauth_scope|string|https://mail.google.com/|True|Gmail OAuth scope to use for the connection, note that read only will result in some actions not working.|['https://mail.google.com/', 'https://www.googleapis.com/auth/gmail.readonly']|https://mail.google.com/| |private_key|credential_asymmetric_key|None|True|Private Key from service credentials|None|-----BEGIN RSA PRIVATE KEY----- MIIEpQIBAAKCAQEAjGnoUtfPHqvX3PIU6N9FKmwQ3Zl+NoaWb4yMLhudkdEBJ3Au...8/dqUH5yjRKs2qxkBWG4HmT3Nx6A8sYIrUYxyqVLBpG8yKngbnaYPV4= -----END RSA PRIVATE KEY-----| |private_key_id|string|None|True|Private Key ID from service credentials|None|02699626f388ed830012e5b787640e71c56d42d8| |project_id|string|None|True|Project ID from service credentials|None|sincere-hybrid-125985| |token_uri|string|https://oauth2.googleapis.com/token|True|OAUTH2 Token URI|None|https://oauth2.googleapis.com/token|

Example input:

{
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "client_email": "example@sincere-hybrid-125985.iam.gserviceaccount.com",
  "client_id": "102790495738029996994",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/icon%40ssincere-hybrid-125985.iam.gserviceaccount.com",
  "private_key": {
    "privateKey": "-----BEGIN RSA PRIVATE KEY-----
                   MIIEpQIBAAKCAQEAjGnoUtfPHqvX3PIU6N9FKmwQ3Zl+NoaWb4yMLhudkdEBJ3Au...8/dqUH5yjRKs2qxkBWG4HmT3Nx6A8sYIrUYxyqVLBpG8yKngbnaYPV4=
                   -----END RSA PRIVATE KEY-----"
  },
  "private_key_id": "02699626f388ed830012e5b787640e71c56d42d8",
  "project_id": "sincere-hybrid-125985",
  "token_uri": "https://accounts.google.com/o/oauth2/token",
  "oauth_scope": "https://mail.google.com/"
}

Technical Details

Actions

Delete Email by ID

This action is used to delete an email by ID if it exists.

Input
Name Type Default Required Description Enum Example
deletion_method string None True Deletes an email. Emails can be deleted or moved to trash ['Delete', 'Trash'] Trash
email string None True The user's email address None users@example.com
email_id string None True ID of the email to delete None 168e311c98148e0d
flatten_attachments boolean False False Flattens attachments to a single list None True

Example input:

{
  "deletion_method": "Trash",
  "email": "users@example.com",
  "email_id": "168e311c98148e0d",
  "flatten_attachments": True
}
Output
Name Type Required Description
email email False Email
success boolean False True if successful

Example output:

{
  "email": {
    "account": "bob@test.com",
    "attached_emails": [
      {
        "account": "bob@test.com",
        "attached_emails": [],
        "attached_files": [
          {
            "name": "Test.png",
            "content": "iVBORw0KGgoAAAANSUhEUgAAAgAAAAIACAYAAAD0eNT6AAAACXBIWXMAAA7EAAAOxAGVK"
          }
        ],
        "body": "Test email 2",
        "headers": [{
            "name": "Received",
            "value": ""
        }],
        "id": "359",
        "date_received": "2018-07-25T23:06:44.00Z",
        "categories": ["INBOX"],
        "flattened_attached_emails": [],
        "flattened_attached_files": [
          {
            "name": "Test.png",
            "content": "iVBORw0KGgoAAAANSUhEUgAAAgAAAAIACAYAAAD0eNT6AAAACXBIWXMAAA7EAAAOxAGVK"
          }
        ],
        "is_read": false,
        "sender": "joe@test.com",
        "subject": "Check this other email out!!"
      }
    ],
    "attached_files": [],
    "body": "Test email",
    "headers": [{
        "name": "Received",
        "value": ""
    }],
    "id": "358",
    "date_received": "2018-07-25T22:06:44.00Z",
    "categories": ["INBOX"],
    "flattened_attached_emails": [
      {
        "account": "bob@test.com",
        "attached_emails": [],
        "attached_files": [
          {
            "name": "Test.png",
            "content": "iVBORw0KGgoAAAANSUhEUgAAAgAAAAIACAYAAAD0eNT6AAAACXBIWXMAAA7EAAAOxAGVK"
          }
        ],
        "body": "Test email 2",
        "headers": [{
            "name": "Received",
            "value": ""
        }],
        "id": "358",
        "date_received": "2018-07-25T23:06:44.00Z",
        "categories": ["INBOX"],
        "flattened_attached_emails": [],
        "flattened_attached_files": [
          {
            "name": "Test.png",
            "content": "iVBORw0KGgoAAAANSUhEUgAAAgAAAAIACAYAAAD0eNT6AAAACXBIWXMAAA7EAAAOxAGVK"
          }
        ],
        "is_read": false,
        "sender": "joe@test.com",
        "subject": "Check this other email out!!"
      }
    ],
    "flattened_attached_files": [
      {
        "name": "Test.png",
        "content": "iVBORw0KGgoAAAANSUhEUgAAAgAAAAIACAYAAAD0eNT6AAAACXBIWXMAAA7EAAAOxAGVK"
      }
    ],
    "is_read": false,
    "sender": "joe@test.com",
    "subject": "Check this out!"
  },
  "success": true
}

Get Email by ID

This action is used to find an email by ID.

Input
Name Type Default Required Description Enum Example
email string None True The user's email address None user@example.com
email_id string None True ID of email to retrieve None 168e311c98148e0d
flatten_attachments boolean False False Flattens attachments to a single list None True

Example input:

{
  "email": "user@example.com",
  "email_id": "168e311c98148e0d",
  "flatten_attachments": True
}
Output
Name Type Required Description
email email False Email
found boolean False True if found

Example output:

{
  "email": {
    "account": "bob@test.com",
    "attached_emails": [
      {
        "account": "bob@test.com",
        "attached_emails": [],
        "attached_files": [
          {
            "name": "Test.png",
            "content": "iVBORw0KGgoAAAANSUhEUgAAAgAAAAIACAYAAAD0eNT6AAAACXBIWXMAAA7EAAAOxAGVK"
          }
        ],
        "body": "Test email 2",
        "headers": [{
            "name": "Received",
            "value": ""
        }],
        "id": "359",
        "date_received": "2018-07-25T23:06:44.00Z",
        "categories": ["INBOX"],
        "flattened_attached_emails": [],
        "flattened_attached_files": [
          {
            "name": "Test.png",
            "content": "iVBORw0KGgoAAAANSUhEUgAAAgAAAAIACAYAAAD0eNT6AAAACXBIWXMAAA7EAAAOxAGVK"
          }
        ],
        "is_read": false,
        "sender": "joe@test.com",
        "subject": "Check this other email out!!"
      }
    ],
    "attached_files": [],
    "body": "Test email",
    "headers": [{
        "name": "Received",
        "value": ""
    }],
    "id": "358",
    "date_received": "2018-07-25T22:06:44.00Z",
    "categories": ["INBOX"],
    "flattened_attached_emails": [
      {
        "account": "bob@test.com",
        "attached_emails": [],
        "attached_files": [
          {
            "name": "Test.png",
            "content": "iVBORw0KGgoAAAANSUhEUgAAAgAAAAIACAYAAAD0eNT6AAAACXBIWXMAAA7EAAAOxAGVK"
          }
        ],
        "body": "Test email 2",
        "headers": [{
            "name": "Received",
            "value": ""
        }],
        "id": "358",
        "date_received": "2018-07-25T23:06:44.00Z",
        "categories": ["INBOX"],
        "flattened_attached_emails": [],
        "flattened_attached_files": [
          {
            "name": "Test.png",
            "content": "iVBORw0KGgoAAAANSUhEUgAAAgAAAAIACAYAAAD0eNT6AAAACXBIWXMAAA7EAAAOxAGVK"
          }
        ],
        "is_read": false,
        "sender": "joe@test.com",
        "subject": "Check this other email out!!"
      }
    ],
    "flattened_attached_files": [
      {
        "name": "Test.png",
        "content": "iVBORw0KGgoAAAANSUhEUgAAAgAAAAIACAYAAAD0eNT6AAAACXBIWXMAAA7EAAAOxAGVK"
      }
    ],
    "is_read": false,
    "sender": "joe@test.com",
    "subject": "Check this out!"
  },
  "found": true
}

Find Emails

This action is used to find emails in a user's mailbox.

Input
Name Type Default Required Description Enum Example
email string None True The user's email address None user@example.com
flatten_attachments boolean False False Flattens attachments to a single list None False
include_spam_trash boolean False True Include spam & trash results None False
query string None True Supports the same query format as the Gmail search box. For example, 'from:someuser@example.com rfc822msgid: is:unread' None is:inbox is:unread

Example input:

{
  "email": "user@example.com",
  "include_spam_trash": False,
  "query": "in: inbox"
}
Output
Name Type Required Description
count integer False Estimated total count
emails []email False Emails

Example output:

{
  "emails": [{
     "account": "bob@test.com",
     "attached_emails": [
       {
         "account": "bob@test.com",
         "attached_emails": [],
         "attached_files": [
           {
             "name": "Test.png",
             "content": "iVBORw0KGgoAAAANSUhEUgAAAgAAAAIACAYAAAD0eNT6AAAACXBIWXMAAA7EAAAOxAGVK"
           }
         ],
         "body": "Test email 2",
         "headers": [{
             "name": "Received",
             "value": ""
         }],
         "id": "359",
         "date_received": "2018-07-25T23:06:44.00Z",
         "categories": ["INBOX"],
         "flattened_attached_emails": [],
         "flattened_attached_files": [
           {
             "name": "Test.png",
             "content": "iVBORw0KGgoAAAANSUhEUgAAAgAAAAIACAYAAAD0eNT6AAAACXBIWXMAAA7EAAAOxAGVK"
           }
         ],
         "is_read": false,
         "sender": "joe@test.com",
         "subject": "Check this other email out!!"
       }
     ],
     "attached_files": [],
     "body": "Test email",
     "headers": [{
         "name": "Received",
         "value": ""
     }],
     "id": "358",
     "date_received": "2018-07-25T22:06:44.00Z",
     "categories": ["INBOX"],
     "flattened_attached_emails": [
       {
         "account": "bob@test.com",
         "attached_emails": [],
         "attached_files": [
           {
             "name": "Test.png",
             "content": "iVBORw0KGgoAAAANSUhEUgAAAgAAAAIACAYAAAD0eNT6AAAACXBIWXMAAA7EAAAOxAGVK"
           }
         ],
         "body": "Test email 2",
         "headers": [{
             "name": "Received",
             "value": ""
         }],
         "id": "358",
         "date_received": "2018-07-25T23:06:44.00Z",
         "categories": ["INBOX"],
         "flattened_attached_emails": [],
         "flattened_attached_files": [
           {
             "name": "Test.png",
             "content": "iVBORw0KGgoAAAANSUhEUgAAAgAAAAIACAYAAAD0eNT6AAAACXBIWXMAAA7EAAAOxAGVK"
           }
         ],
         "is_read": false,
         "sender": "joe@test.com",
         "subject": "Check this other email out!!"
       }
     ],
     "flattened_attached_files": [
       {
         "name": "Test.png",
         "content": "iVBORw0KGgoAAAANSUhEUgAAAgAAAAIACAYAAAD0eNT6AAAACXBIWXMAAA7EAAAOxAGVK"
       }
     ],
     "is_read": false,
     "sender": "joe@test.com",
     "subject": "Check this out!"
   }],
  "count": 1
}

Find One Email

This action is used to find the first email matching a query.

Input
Name Type Default Required Description Enum Example
email string None True The user's email address None user@example.com
flatten_attachments boolean False False Flattens attachments to a single list None False
include_spam_trash boolean False True Include spam & trash results None False
query string None True Supports the same query format as the Gmail search box. For example, 'from:someuser@example.com rfc822msgid: is:unread' None is:inbox is:unread

Example input:

{
"email": "user@example.com",
"include_spam_trash": False,
"query": "from:user@rapid7.com"
}
Output
Name Type Required Description
email email False Email
found boolean False True if found

Example output:

{
  "email": {
    "account": "bob@test.com",
    "attached_emails": [
      {
        "account": "bob@test.com",
        "attached_emails": [],
        "attached_files": [
          {
            "name": "Test.png",
            "content": "iVBORw0KGgoAAAANSUhEUgAAAgAAAAIACAYAAAD0eNT6AAAACXBIWXMAAA7EAAAOxAGVK"
          }
        ],
        "body": "Test email 2",
        "headers": [{
            "name": "Received",
            "value": ""
        }],
        "id": "359",
        "date_received": "2018-07-25T23:06:44.00Z",
        "categories": ["INBOX"],
        "flattened_attached_emails": [],
        "flattened_attached_files": [
          {
            "name": "Test.png",
            "content": "iVBORw0KGgoAAAANSUhEUgAAAgAAAAIACAYAAAD0eNT6AAAACXBIWXMAAA7EAAAOxAGVK"
          }
        ],
        "is_read": false,
        "sender": "joe@test.com",
        "subject": "Check this other email out!!"
      }
    ],
    "attached_files": [],
    "body": "Test email",
    "headers": [{
        "name": "Received",
        "value": ""
    }],
    "id": "358",
    "date_received": "2018-07-25T22:06:44.00Z",
    "categories": ["INBOX"],
    "flattened_attached_emails": [
      {
        "account": "bob@test.com",
        "attached_emails": [],
        "attached_files": [
          {
            "name": "Test.png",
            "content": "iVBORw0KGgoAAAANSUhEUgAAAgAAAAIACAYAAAD0eNT6AAAACXBIWXMAAA7EAAAOxAGVK"
          }
        ],
        "body": "Test email 2",
        "headers": [{
            "name": "Received",
            "value": ""
        }],
        "id": "358",
        "date_received": "2018-07-25T23:06:44.00Z",
        "categories": ["INBOX"],
        "flattened_attached_emails": [],
        "flattened_attached_files": [
          {
            "name": "Test.png",
            "content": "iVBORw0KGgoAAAANSUhEUgAAAgAAAAIACAYAAAD0eNT6AAAACXBIWXMAAA7EAAAOxAGVK"
          }
        ],
        "is_read": false,
        "sender": "joe@test.com",
        "subject": "Check this other email out!!"
      }
    ],
    "flattened_attached_files": [
      {
        "name": "Test.png",
        "content": "iVBORw0KGgoAAAANSUhEUgAAAgAAAAIACAYAAAD0eNT6AAAACXBIWXMAAA7EAAAOxAGVK"
      }
    ],
    "is_read": false,
    "sender": "joe@test.com",
    "subject": "Check this out!"
  },
  "found": true
}

Modify Email

This action is used to modify an email's labels - https://developers.google.com/gmail/api/v1/reference/users/messages/modify.

Input
Name Type Default Required Description Enum Example
email string None True The user's email address None user@example.com
email_id string None True Email ID None 168e311c98148e0d
labels_to_add []string None False Array of labels to apply, e.g. ["spam"] None ["spam", "Important"]
labels_to_remove []string None False Array of labels to remove, e.g. ["spam"] None ["spam", "Important"]

Example input:

{
"email": "user@example.com",
"email_id": "168e311c98148e0d",
"labels_to_add": ["spam", "important"],
"labels_to_remove": ["spam", "important"]
}
Output
Name Type Required Description
success boolean False True if modified

Example output:

{
  "success": true
}

Batch Modify Emails

This action is used to batch modify email labels - https://developers.google.com/gmail/api/v1/reference/users/messages/batchModify.

Input
Name Type Default Required Description Enum Example
email string None True The user's email address None user@example.com
email_ids []string None False A list of email IDs. This, or emails, is required None ["168e311c98148e0d", "247d466n99248g8t"]
emails []email None False A list of emails. This, or Email IDs, is required None None
labels_to_add []string None False Array of labels to apply, e.g. ["spam"] None ["spam", "Important"]
labels_to_remove []string None False Array of labels to remove, e.g. ["spam"] None ["spam", "Important"]

Example input:

{
  "email": "user@example.com",
  "email_ids": ["168e311c98148e0d", "168e3065a621999c"],
  "emails": [],
  "labels_to_add": ["spam", "important"],
  "labels_to_remove": ["spam", "important"]
}
Output
Name Type Required Description
count integer False Number of emails modified

Example output:

{
  "count": 2
}

Batch Modify Emails by Query

This action is used to batch modify emails that match a query.

Input
Name Type Default Required Description Enum Example
email string None True The user's email address None user@example.com
labels_to_add []string None False Array of labels to apply, e.g. ["spam"] None ["spam", "Important"]
labels_to_remove []string None False Array of labels to remove, e.g. ["spam"] None ["spam", "Important"]
query string None True Emails to modify. Supports the same query format as the Gmail search box. For example, 'from:someuser@example.com rfc822msgid: is:unread' None is:inbox is:unread

Example input:

{
  "email": "user@example.com",
  "labels_to_add": ["spam", "important"],
  "labels_to_remove": ["spam", "important"],
  "query": "from:user@rapid7.com"
}
Output
Name Type Required Description
count integer False Number of emails modified

Example output:

{
  "count": 2
}

Send Email

This action is used to send an email.

Input
Name Type Default Required Description Enum Example
attachment file None False Attachment None { "filename": "document.pdf", "content": "UmFwaWQ3IEluc2lnaHRDb25uZWN0Cg==" }
bcc []string None False Emails to BCC None ["user@example.com", "user2@example.com"]
cc []string None False Emails to CC None ["user@example.com", "user2@example.com"]
email_from string None True Email to use as from None user@example.com
email_to string None True Email to send TO None user@example.com
message string None True Message to send on the email None The body of the email
subject string None True Subject of the email None Subject goes here

Example input:

{
  "attachment": {
    "filename": "<name>, "content": "UmFwaWQ3IEluc2lnaHRDb25uZWN0Cg=="
  },
  "bcc": "user2@example.com",
  "cc": "user2@rapid7.com",
  "email_from": "user@example.com",
  "email_to": "user@raid7.com",
  "subject": "Subject goes here",
  "message": "The body of the email"
}
Output
Name Type Required Description
message message True Message object

Example output:

{
  "message": {
    "id": "16adbe06db777acc",
    "threadId": "16adbe06db777acc",
    "labelIds": [
      "SENT"
    ]
  }
}

Triggers

Email Received

This trigger is used to trigger on unread emails received.

Input
Name Type Default Required Description Enum Example
email string None True The user's email address None user@example.com
flatten_attachments boolean False False Flattens attachments to a single list None True
only_new_emails boolean True True Whether to only retrieve the emails received since the last run of the trigger or all based on the query. This appends 'after:' to the provided query, where is the time from the previous run of the trigger None True
poll_interval integer 15 True How often to poll the specified mailbox for new emails, in seconds. Default value is 15 seconds None None
query string is:inbox is:unread False Supports the same query format as the Gmail search box. For example, 'from:someuser@example.com rfc822msgid: is:unread' None is:inbox is:unread

Example input:

{
  "email": "user@example.com",
  "flatten_attachments": True,
  "only_new_emails": True,
  "poll_interval": 15,
  "query": "is:inbox is:unread"
}
Output
Name Type Required Description
email email False Email

Example output:

{
  "email": {
    "account": "bob@test.com",
    "attached_emails": [
      {
        "account": "bob@test.com",
        "attached_emails": [],
        "attached_files": [
          {
            "name": "Test.png",
            "content": "iVBORw0KGgoAAAANSUhEUgAAAgAAAAIACAYAAAD0eNT6AAAACXBIWXMAAA7EAAAOxAGVK"
          }
        ],
        "body": "Test email 2",
        "headers": [{
            "name": "Received",
            "value": ""
        }],
        "id": "359",
        "date_received": "2018-07-25T23:06:44.00Z",
        "categories": ["INBOX"],
        "flattened_attached_emails": [],
        "flattened_attached_files": [
          {
            "name": "Test.png",
            "content": "iVBORw0KGgoAAAANSUhEUgAAAgAAAAIACAYAAAD0eNT6AAAACXBIWXMAAA7EAAAOxAGVK"
          }
        ],
        "is_read": false,
        "sender": "joe@test.com",
        "subject": "Check this other email out!!"
      }
    ],
    "attached_files": [],
    "body": "Test email",
    "headers": [{
        "name": "Received",
        "value": ""
    }],
    "id": "358",
    "date_received": "2018-07-25T22:06:44.00Z",
    "categories": ["INBOX"],
    "flattened_attached_emails": [
      {
        "account": "bob@test.com",
        "attached_emails": [],
        "attached_files": [
          {
            "name": "Test.png",
            "content": "iVBORw0KGgoAAAANSUhEUgAAAgAAAAIACAYAAAD0eNT6AAAACXBIWXMAAA7EAAAOxAGVK"
          }
        ],
        "body": "Test email 2",
        "headers": [{
            "name": "Received",
            "value": ""
        }],
        "id": "358",
        "date_received": "2018-07-25T23:06:44.00Z",
        "categories": ["INBOX"],
        "flattened_attached_emails": [],
        "flattened_attached_files": [
          {
            "name": "Test.png",
            "content": "iVBORw0KGgoAAAANSUhEUgAAAgAAAAIACAYAAAD0eNT6AAAACXBIWXMAAA7EAAAOxAGVK"
          }
        ],
        "is_read": false,
        "sender": "joe@test.com",
        "subject": "Check this other email out!!"
      }
    ],
    "flattened_attached_files": [
      {
        "name": "Test.png",
        "content": "iVBORw0KGgoAAAANSUhEUgAAAgAAAAIACAYAAAD0eNT6AAAACXBIWXMAAA7EAAAOxAGVK"
      }
    ],
    "is_read": false,
    "sender": "joe@test.com",
    "subject": "Check this out!"
  }
}

Custom Output Types

This plugin does not contain any custom output types.

Troubleshooting

This plugin does not contain an troubleshooting information.

Version History

  • 6.0.1 - Add docs_url to plugin spec with link to plugin setup guide
  • 6.0.0 - Add example inputs | Update titles for style in inputs for Send Email action
  • 5.1.4 - New spec and help.md format for the Extension Library
  • 5.1.3 - Update to use the komand/python-3-37-plugin:3 Docker image to reduce plugin size and fix a Python 3.5 syntax bug in the Find Messages action
  • 5.1.2 - Add support for CC and BCC in the Send Email action
  • 5.1.1 - Fix bug where an empty attachment could throw a KeyError in the Send Email action
  • 5.1.0 - Add Send Email action
  • 5.0.1 - Fix issue where HTML was mangled by soft linebreaks
  • 5.0.0 - Update connection to support read/write and read-only OAuth scopes | Update "Email Received" trigger to utilize file caches to support getting new emails when a read-only OAuth scope is used
  • 4.0.2 - Fix typo in plugin spec
  • 4.0.1 - Add basic handling for emails with no declared Content-Type header | Handle multipart/mixed emails
  • 4.0.0 - Use standardized email type for output | Fix bug where emails with attached .eml files would crash the plugin
  • 3.0.0 - Fix connection behavior so that Domain-wide Delegation works as expected | Remove Account Name from connection parameters | Add error handling to Delete Message by ID action | Fix message count on Find Messages action | Implement pagination on Batch Modify Messages action | Implement pagination on Batch Modify Messages by Query action | Implement pagination on Find Messages action | Remove max parameter from Find Messages action | Fix Email Received trigger output format to make its specification
  • 2.0.0 - Rename "Email received" action to "Email Received" | Rename "Delete Message By ID" action to "Delete Message by ID" | Rename "Trash Message By ID" action to "Trash Message by ID" | Rename "Get Message By ID" action to "Get Message by ID" | Rename "Batch Modify Messages By Query" action to "Batch Modify Messages by Query"
  • 1.0.0 - Update to v2 Python plugin architecture | Support web server mode | Update to new credential types
  • 0.1.4 - SSL bug fix in SDK
  • 0.1.3 - Fix logging debug return message
  • 0.1.0 - Initial plugin

Links

References

plugin_spec_version: v2
extension: plugin
products: ["insightconnect"]
name: gmail
title: Gmail
description: Gmail is a free cloud-based email service from Google. Using the Gmail plugin for Rapid7 InsightConnect, users can interact with and manage both consumer and G Suite Gmail accounts, including monitoring incoming email, managing email, and more
version: 6.0.1
vendor: rapid7
support: rapid7
status: []
resources:
  vendor_url: https://google.com
  docs_url: https://insightconnect.help.rapid7.com/docs/gmail-api
tags:
- google
- gmail
- email
hub_tags:
  use_cases: [data_utility, threat_detection_and_response]
  keywords: [google, gmail, email]
  features: []
types:
  header:
    name:
      type: string
      required: false
    value:
      type: string
      required: false
  attachment_file:
    name:
      type: string
      required: false
    content:
      type: bytes
      required: false
  attachment_email:
    id:
      type: string
      title: ID
      required: false
    sender:
      type: string
      required: false
    subject:
      type: string
      required: false
    body:
      type: string
      required: false
    categories:
      type: '[]string'
      required: false
    headers:
      type: '[]header'
      required: false
    attached_files:
      type: '[]attachment_file'
      required: false
    attached_emails:
      type: '[]object'
      required: false
  email:
    id:
      type: string
      title: ID
      required: false
    account:
      type: string
      title: Account
      required: false
      description: Account for which the email was found on
    is_read:
      type: boolean
      title: Is Read
      required: false
      description: Whether or not the email has been read
    sender:
      type: string
      required: false
    subject:
      type: string
      required: false
    body:
      type: string
      required: false
    attached_files:
      type: '[]attachment_file'
      required: false
    attached_emails:
      type: '[]attachment_email'
      required: false
    flattened_attached_emails:
      type: '[]attachment_email'
      required: false
    flattened_attached_files:
      type: '[]attachment_file'
      required: false
    categories:
      type: '[]string'
      required: false
    headers:
      type: '[]header'
      required: false
  message:
    id:
      type: string
    threadId: 
      type: string
    labelIds:
      type: '[]string'

connection:
  project_id:
    title: Project ID
    type: string
    example: sincere-hybrid-125985
    description: Project ID from service credentials
    required: true
  private_key_id:
    title: Private Key ID
    type: string
    example: 02699626f388ed830012e5b787640e71c56d42d8
    description: Private Key ID from service credentials
    required: true
  private_key:
    title: Private Key
    type: credential_asymmetric_key
    example: -----BEGIN RSA PRIVATE KEY-----

      MIIEpQIBAAKCAQEAjGnoUtfPHqvX3PIU6N9FKmwQ3Zl+NoaWb4yMLhudkdEBJ3Au...8/dqUH5yjRKs2qxkBWG4HmT3Nx6A8sYIrUYxyqVLBpG8yKngbnaYPV4=

      -----END RSA PRIVATE KEY-----
    description: Private Key from service credentials
    required: true
  client_email:
    title: Client Email
    type: string
    example: example@sincere-hybrid-125985.iam.gserviceaccount.com
    description: Client email from service credentials
    required: true
  client_id:
    title: Client ID
    type: string
    example: 102790495738029996994
    description: Client ID
    required: true
  client_x509_cert_url:
    title: Client X509 Cert URL
    type: string
    example: https://www.googleapis.com/robot/v1/metadata/x509/icon%40ssincere-hybrid-125985.iam.gserviceaccount.com
    description: x509 cert URL from service credentials
    required: true
  auth_uri:
    title: Auth URI
    type: string
    example: https://accounts.google.com/o/oauth2/auth
    description: OAUTH2 Auth URI
    default: https://accounts.google.com/o/oauth2/auth
    required: true
  token_uri:
    title: Token URI
    type: string
    example: https://oauth2.googleapis.com/token
    description: OAUTH2 Token URI
    default: https://oauth2.googleapis.com/token
    required: true
  auth_provider_x509_cert_url:
    title: Auth Provider X509 Cert URL
    type: string
    example: https://www.googleapis.com/oauth2/v1/certs
    description: OAUTH2 Auth Provider x509 Cert URL
    default: https://www.googleapis.com/oauth2/v1/certs
    required: true
  oauth_scope:
    title: OAuth Scope
    type: string
    example: https://mail.google.com/
    description: Gmail OAuth scope to use for the connection, note that read only
      will result in some actions not working.
    default: https://mail.google.com/
    required: true
    enum:
    - https://mail.google.com/
    - https://www.googleapis.com/auth/gmail.readonly
triggers:
  email_received:
    title: Email Received
    description: Trigger on unread emails received
    input:
      email:
        title: Email
        description: The user's email address
        type: string
        example: user@example.com
        required: true
      poll_interval:
        type: integer
        description: How often to poll the specified mailbox for new emails, in seconds.
          Default value is 15 seconds
        default: 15
        required: true
      query:
        title: Query
        type: string
        description: 'Supports the same query format as the Gmail search box. For
          example, ''from:someuser@example.com rfc822msgid: is:unread'''
        default: is:inbox is:unread
        example: is:inbox is:unread
        required: false
      only_new_emails:
        title: Only New Emails
        description: Whether to only retrieve the emails received since the last run
          of the trigger or all based on the query. This appends 'after:<unix time>'
          to the provided query, where <unix time> is the time from the previous run
          of the trigger
        type: boolean
        example: true
        default: true
        required: true
      flatten_attachments:
        title: Flatten Attachments
        type: boolean
        example: true
        description: Flattens attachments to a single list
        default: false
        required: false
    output:
      email:
        title: Email
        type: email
        required: false
        description: Email
actions:
  delete_message_by_id:
    title: Delete Email by ID
    description: Delete an email by ID if it exists
    input:
      email:
        title: Email
        description: The user's email address
        type: string
        example: users@example.com
        required: true
      email_id:
        type: string
        title: Email ID
        description: ID of the email to delete
        example: 168e311c98148e0d
        required: true
      deletion_method:
        title: Deletion Method
        type: string
        description: Deletes an email. Emails can be deleted or moved to trash
        example: Trash
        enum:
        - Delete
        - Trash
        required: true
      flatten_attachments:
        title: Flatten Attachments
        type: boolean
        example: true
        description: Flattens attachments to a single list
        default: false
        required: false
    output:
      email:
        title: Email
        type: email
        required: false
        description: Email
      success:
        title: Success
        type: boolean
        description: True if successful
        required: false
  message_by_id:
    title: Get Email by ID
    description: Find email by ID
    input:
      email:
        title: Email
        description: The user's email address
        type: string
        example: user@example.com
        required: true
      email_id:
        title: Email ID
        description: ID of email to retrieve
        type: string
        example: 168e311c98148e0d
        required: true
      flatten_attachments:
        title: Flatten Attachments
        type: boolean
        example: true
        description: Flattens attachments to a single list
        default: false
        required: false
    output:
      email:
        title: Email
        type: email
        required: false
        description: Email
      found:
        title: Found
        type: boolean
        description: True if found
        required: false
  find_messages:
    title: Find Emails
    description: Find emails in a user's mailbox
    input:
      email:
        title: Email
        description: The user's email address
        type: string
        example: user@example.com
        required: true
      include_spam_trash:
        title: Include Spam Trash
        description: Include spam & trash results
        type: boolean
        example: false
        default: false
        required: true
      query:
        title: Query
        type: string
        example: is:inbox is:unread
        required: true
        description: 'Supports the same query format as the Gmail search box. For
          example, ''from:someuser@example.com rfc822msgid: is:unread'''
      flatten_attachments:
        title: Flatten Attachments
        type: boolean
        example: false
        description: Flattens attachments to a single list
        default: false
        required: false
    output:
      emails:
        title: Emails
        type: '[]email'
        required: false
        description: Emails
      count:
        title: Count
        type: integer
        description: Estimated total count
        required: false
  find_one_message:
    title: Find One Email
    description: Find the first email matching a query
    input:
      email:
        title: Email
        description: The user's email address
        type: string
        example: user@example.com
        required: true
      include_spam_trash:
        title: Include Spam Trash
        description: Include spam & trash results
        type: boolean
        example: false
        default: false
        required: true
      query:
        title: Query
        type: string
        example: is:inbox is:unread
        required: true
        description: 'Supports the same query format as the Gmail search box. For
          example, ''from:someuser@example.com rfc822msgid: is:unread'' '
      flatten_attachments:
        title: Flatten Attachments
        type: boolean
        example: false
        description: Flattens attachments to a single list
        default: false
        required: false
    output:
      email:
        title: Email
        type: email
        required: false
        description: Email
      found:
        title: Found
        type: boolean
        description: True if found
        required: false
  modify_message:
    title: Modify Email
    description: Modify an email's labels
    input:
      email:
        title: Email
        description: The user's email address
        type: string
        example: user@example.com
        required: true
      email_id:
        title: Email ID
        description: Email ID
        type: string
        example: 168e311c98148e0d
        required: true
      labels_to_add:
        title: Labels to Add
        description: Array of labels to apply, e.g. ["spam"]
        example: '["spam", "Important"]'
        type: '[]string'
        required: false
      labels_to_remove:
        title: Labels to Remove
        example: '["spam", "Important"]'
        description: Array of labels to remove, e.g. ["spam"]
        type: '[]string'
        required: false
    output:
      success:
        title: Success
        type: boolean
        description: True if modified
        required: false
  batch_modify_messages:
    title: Batch Modify Emails
    description: Batch modify email labels
    input:
      email:
        title: Email
        description: The user's email address
        example: user@example.com
        type: string
        required: true
      emails:
        title: Emails
        description: A list of emails. This, or Email IDs, is required
        type: '[]email'
        required: false
      email_ids:
        title: Email IDs
        description: A list of email IDs.  This, or emails, is required
        type: '[]string'
        example: '["168e311c98148e0d", "247d466n99248g8t"]'
        required: false
      labels_to_add:
        title: Labels to Add
        description: Array of labels to apply, e.g. ["spam"]
        type: '[]string'
        example: '["spam", "Important"]'
        required: false
      labels_to_remove:
        title: Labels to Remove
        description: Array of labels to remove, e.g. ["spam"]
        type: '[]string'
        example: '["spam", "Important"]'
        required: false
    output:
      count:
        title: Count
        type: integer
        description: Number of emails modified
        required: false
  batch_modify_messages_by_query:
    title: Batch Modify Emails by Query
    description: Batch modify emails that match a query
    input:
      email:
        title: Email
        description: The user's email address
        type: string
        example: user@example.com
        required: true
      query:
        title: Query
        type: string
        example: is:inbox is:unread
        description: 'Emails to modify. Supports the same query format as the Gmail
          search box. For example, ''from:someuser@example.com rfc822msgid: is:unread'''
        required: true
      labels_to_add:
        title: Labels to Add
        description: Array of labels to apply, e.g. ["spam"]
        type: '[]string'
        example: '["spam", "Important"]'
        required: false
      labels_to_remove:
        title: Labels to Remove
        description: Array of labels to remove, e.g. ["spam"]
        type: '[]string'
        example: '["spam", "Important"]'
        required: false
    output:
      count:
        title: Count
        type: integer
        description: Number of emails modified
        required: false
  send_email:
    title: Send Email
    description: Send an email
    input:
      email_from:
        title: Email from Address
        type: string
        example: user@example.com
        description: Email to use as from
        required: true
        order: 1
      email_to:
        title: Email to Address
        type: string
        example: user@example.com
        description: Email to send TO
        required: true
        order: 2
      subject:
        title: Email Subject
        type: string
        example: Subject goes here
        description: Subject of the email
        required: true
        order: 3
      message:
        title: Email Body
        type: string
        example: The body of the email
        description: Message to send on the email
        required: true
        order: 4
      attachment:
        title: File Attachment
        type: file
        example: '{ "filename": "document.pdf", "content": "UmFwaWQ3IEluc2lnaHRDb25uZWN0Cg==" }'
        description: Attachment
        required: false
        order: 5
      cc:
        title: CC
        type: '[]string'
        example: '["user@example.com", "user2@example.com"]'
        description: Emails to CC
        required: false
        order: 6
      bcc:
        title: BCC
        type: '[]string'
        example: '["user@example.com", "user2@example.com"]'
        description: Emails to BCC
        required: false
        order: 7
    output:
      message:
          type: message
          title: Message
          required: true
          description: Message object
Other plugins
McAfee Advanced Threat Defense
Rapid7   |   v1.5.0
Plugin
Get
Ivanti Security Controls
Rapid7   |   v1.3.0
Plugin
Get
Base64
Rapid7   |   v1.1.5
Plugin
Get
Fortinet FortiGate
Rapid7   |   v4.0.2
Plugin
Get
Jira
Rapid7   |   v6.0.0
Plugin
Get