Microsoft Graph Mail

This document provides guidance on how to integrate Microsoft Graph Mail with Google Security Operations SOAR.

Integration version: 17.0

Use cases

Integrating Microsoft Graph Mail with Google SecOps can help you solve the following use cases:

  • Phishing email investigation and remediation: use the Google SecOps capabilities to identify malicious emails, automatically investigate the email headers, sender reputation, and attachments in phishing emails, and automate the threat remediation actions.

  • Compromised account response: use the Google SecOps capabilities to analyze recent emails sent from the suspicious account, looking for potentially malicious activities like bulk forwarding or unusual login locations. The compromised account response can help you identify compromised accounts and facilitate response actions, such as password resets and email scanning for data exfiltration attempts.

Before you begin

Before configuring the integration in the Google SecOps platform, complete the following steps:

  1. Create the Microsoft Entra app.

  2. Configure the API permissions for your app.

  3. Create a client secret.

Create Microsoft Entra app

To create the Microsoft Entra app, complete the following steps:

  1. Sign in to the Azure portal as a user administrator or a password administrator.

  2. Select Microsoft Entra ID.

  3. Go to App registrations > New registration.

  4. Enter the name of the app.

  5. Click Register.

    This document provides an example using a single-tenant setup. The OAuth flow (client credentials) supported by the integration does not require the redirect URL.

  6. Save the Application (client) ID and Directory (tenant) ID values to use them later when configuring the integration parameters.

Configure API permissions

To configure the API permissions for the integration, complete the following steps:

  1. In Azure portal, go to API Permissions > Add a permission.

  2. Select Microsoft Graph > Application permissions.

  3. In the Select Permissions section, select the following required permissions:

    • Mail.Read
    • Mail.ReadWrite
    • Mail.Send
    • MailboxSettings.Read
    • MailboxSettings.ReadWrite
    • User.Read
    • Directory.Read.All

  4. Click Add permissions.

  5. Click Grant admin consent for YOUR_ORGANIZATION_NAME.

    When the Grant admin consent confirmation dialog appears, click Yes.

Create client secret

To create a client secret, complete the following steps:

  1. Navigate to Certificates and secrets > New client secret.

  2. Provide a description for a client secret and set its expiration deadline.

  3. Click Add.

  4. Save the value of the client secret (not the secret ID) to use it as the Secret ID parameter value when configuring the integration. The client secret value is only displayed once.

Integrate Microsoft Graph Mail with Google SecOps

The integration requires the following parameters:

Parameter Description
Azure AD endpoint Required

The Microsoft Entra endpoint to connect to.

The default value is https://login.microsoftonline.com.
Microsoft Graph Endpoint Required

The Microsoft Graph endpoint to connect to.

The default value is https://graph.microsoft.com.
Client ID
 Required

The client (application) ID of the Microsoft Entra app to use in the integration.
Secret ID Required

The client secret value of the Microsoft Entra app to use in the integration.
Tenant Required

The Microsoft Entra ID (tenant ID) value.
Default Mailbox Required

The default mailbox to use in the integration.
Verify SSL Required

If selected, the integration verifies that the SSL certificate for the connection to the Microsoft Graph server is valid.

Selected by default.

For detailed instructions about configuring an integration in Google SecOps, see Configure integrations.

You can make changes at a later stage if needed. After you configure an integration instance, you can use it in playbooks. For more information about configuring and supporting multiple instances, see Supporting multiple instances.

Actions

Before you configure actions, provide the required permissions for the integration. For more detail, see the Configure API permissions section of this document.

Get Mailbox Account Out Of Facility Settings

Use the Get Mailbox Account Out Of Facility Settings action to retrieve the mailbox account out of facility (OOF) settings for the Google SecOps User entity provided.

The Get Mailbox Account Out Of Facility Settings action uses the beta version of Microsoft Graph API.

This action runs on the Google SecOps User entity.

Action inputs

None.

Action outputs

The Get Mailbox Account Out Of Facility Settings action provides the following outputs:

Action output type Availability
Case wall attachment Not available
Case wall link Not available
Case wall table Not available
Enrichment table Not available
JSON result Available
Output messages Available
Script result Available
JSON result

The following example shows the JSON result output received when using the Get Mailbox Account Out Of Facility Settings action:

{
   "@odata.context": "https://graph.microsoft.com/beta/$metadata#communications/presences/$entity",
   "id": "ID",
   "availability": "Offline",
   "activity": "Offline",
   "statusMessage": null,
   "outOfOfficeSettings": {
       "message": "\n\nOut Of Facility111\n",
       "isOutOfOffice": true
   }
}
Output messages

The Get Mailbox Account Out Of Facility Settings action can return the following output messages:

Output message Message description

Successfully returned OOF settings for ENTITY_ID.

Failed to find the following usernames in Office 365 service: USERNAME_LIST.

 The action succeeded.

Error executing action "Add Identity Protection Detection Comment". Reason: ERROR_REASON

Action wasn't able to find OOF settings for ENTITY_ID.

The action failed.

Check the connection to the server, input parameters, or credentials.
Script result

The following table lists the value for the script result output when using the Get Mailbox Account Out Of Facility Settings action:

Script result name Value
is_success True or False

Delete Email

You can use the Delete Email action to delete one or more emails from a mailbox. This action deletes emails based on your search criteria. With the appropriate permissions, the Delete Email action can move emails into different mailboxes.

This action is asynchronous. Adjust the action timeout in the IDE accordingly.

This action doesn't run on entities.

Action inputs

The Delete Email action requires the following parameters:

Parameter Description
Delete In Mailbox Required

The default mailbox to execute the delete operation in. If permissions allow it, the action executes search in other mailboxes. This parameter accepts multiple values as a comma-separated string.
Folder Name Required

A mailbox folder to search an email in.
Mail IDs Optional

A filter condition to search for emails with specific email IDs.

This parameter accepts a comma-separated list of email IDs to search for.

If this parameter is provided, the search ignores the Subject Filter and sSender Filter parameters.
Subject Filter Optional

A filter condition that specifies the email subject to search for.
Sender Filter Optional

A filter condition that specifies the sender of requested emails.
Time Frame (minutes) Optional

A filter condition that specifies the timeframe in minutes to search for emails.
Only Unread Optional

If selected, the action searches only for unread emails.

Not selected by default.
How many mailboxes to process in a single batch Optional

The number of mailboxes to process in a single batch (single connection to the mail server).

The default value is 25.

Action outputs

The following table describes the output types associated with the Delete Email action:

Action output type Availability
Case wall attachment Not available
Case wall link Not available
Case wall table Not available
Enrichment table Not available
JSON result Not available
Output messages Available
Script result Available
Output messages

The Delete Email action provides the following output messages:

Output message Message description

Successfully deleted emails in the following mailboxes: MAILBOX_NAME: DELETED_EMAILS_NUMBER

Mailbox MAILBOX was not found.

 Action succeeded.

Action was not able to find any emails based on the specified search criteria.

Action failed to delete any emails because the provided mailbox folder name was not found in the mailbox(es): MAILBOX_NAME, MAILBOX_FOLDER

Failed to find any of the provided mailboxes: MAILBOX_LIST

Failed to execute action, the error is: ERROR_REASON

Action failed.

Check connection to the server, input parameters, or credentials.
Script result

The following table describes the values for the script result output when using the Delete Email action:

Script result name Value
is_success True or False

Download Attachments From Email

Use the Download Attachments From Email action to download attachments from emails based on the criteria provided.

This action isn't running on entities.

This action is asynchronous. If necessary, adjust the script timeout value in the Google SecOps IDE.

The action replaces the forward slash (\\) or backslash (/) characters in the names of the downloaded attachments with the underscore (_) character.

Action inputs

The Download Attachments From Email action requires the following parameters:

Parameter Description
Search In Mailbox Required

The default mailbox to execute the search operation in. If permissions allow it, the action can search in other mailboxes. This parameter accepts multiple values as a comma-separated string.
Folder Name Required

A mailbox folder to execute the search in.
Download Destination Required

A destination to save the downloaded attachments to.

By default, the action attempts to save the attachment to the Cloud Storage bucket. Saving an attachment to the local file system is a fallback option.

Possible values are GCP Bucket or Local File System. The default value is GCP Bucket.

Download Path Required

A path to download attachments to.

When saving attachments to the Cloud Storage bucket or a local file system, the action expects you to specify the download path in the Unix-like format, such as /tmp/test.
Mail IDs Optional

A filter condition to search for emails with specific email IDs.

This parameter accepts a comma-separated list of email IDs to search for.

If this parameter is provided, the search ignores the Subject Filter and Sender Filter parameters.
Subject Filter Optional

A filter condition that specifies the email subject to search for.

This filter uses the contains logic.
Sender Filter Optional

A filter condition that specifies the sender of requested emails.

This filter uses the equals logic.
Download Attachments from EML Optional

If selected, the action downloads attachments from EML files.

Not selected by default.
Download Attachments to unique path? Optional

If selected, the action downloads attachments to the unique path provided in the Download Path parameter field to avoid overwriting any previously downloaded attachments.

Not selected by default.
How many mailboxes to process in a single batch Optional

The number of mailboxes to process in a single batch (single connection to the mail server).

The default value is 25.

Action outputs

The Download Attachments From Email action provides the following outputs:

Action output type Availability
Case wall attachment Not available
Case wall link Not available
Case wall table Not available
Enrichment table Not available
JSON result Available
Output messages Available
Script result Available
JSON result

The following example describes the JSON result output received when using the Download Attachments From Email action:

[
    {
        "attachment_name": "name1.png",
        "downloaded_path": "file_path/name1.png"
    },
    {
        "attachment_name": "name2.png",
        "downloaded_path": "file_path/name2.png"
    }
]
Output messages

The Download Attachments From Email action provides the following output messages:

Output message Message description

Downloaded NUMBER_OF_ATTACHMENTS attachments. Files: PATHS.

Failed to find emails in MAILBOX with the following mail ids: EMAIL_IDS.

In the mailboxes listed below, emails were found, but there were no attachments to download. Affected mailboxes: MAILBOXES. Mail IDs without attachments to download: LIST_OF_EMAIL_IDS attachments.

 Action succeeded.

Failed to find any emails using the provided criteria!

Failed to find any of the provided mailboxes: MAILBOXES

Action failed to run because the provided mailbox folder name FOLDER_NAME was not found in the mailbox MAILBOX.

Error executing action. Reason: ERROR_REASON

Action failed.

Check the connection to the server, input parameters, or credentials.
Script result

The following table describes the values for the script result output when using the Download Attachments From Email action:

Script result name Value
is_success True or False

Extract Data From Attached EML

Use the Extract Data From Attached EML action to retrieve data from the email EML attachments and return it in the action results. This action supports the .eml, .msg, and .ics file formats.

This action doesn't run on entities.

Action inputs

The Extract Data From Attached EML action requires the following parameters:

Parameter Description
Search In Mailbox Required

The default mailbox to execute the search operation in. If permissions allow it, the action can search in other mailboxes. This parameter accepts multiple values as a comma-separated string.
Folder Name Optional

A mailbox folder to execute the search in.
Mail IDs Required

A filter condition to search for emails with specific email IDs.

This parameter accepts a comma-separated list of email IDs to search for.
Regex Map JSON Optional

A JSON definition that contains regular expressions to apply to the attached email file and generate additional key values in the action JSON result. The example of this parameter value is as follows: {ips: \\b\\\\d{1,3}\\\\.\\\\d{1,3}\\\\.\\\\d{1,3}\\\\.\\\\d{1,3}\\b}

Action outputs

The Extract Data From Attached EML action provides the following outputs:

Action output type Availability
Case wall attachment Not available
Case wall link Not available
Case wall table Not available
Enrichment table Not available
JSON result Available
Output messages Available
Script result Available
JSON result

The following example describes the JSON result output received when using the Extract Data From Attached EML action:

[
    {
        "type": "EML",
        "subject": "examplesubject",
        "from": "sender@example.com",
        "to": "user1@example.com,user2@example.com",
        "date": "Thu,4Jul202412:11:29+0530",
        "text": "text",
        "html": "<p>example-html</p>",
        "regex": {},
        "regex_from_text_part": {},
        "id": "ID",
        "name": "example.eml"
    },
    {
        "type": "MSG",
        "subject": "examplesubject",
        "from": "user@example.com",
        "to": "user1@example.com,user2@example.com",
        "date": "Thu,4Jul202412:11:29+0530",
        "text": "text",
        "html": "<p>examplehtml</p>",
        "regex": {},
        "regex_from_text_part": {},
        "id": "ID",
        "name": "example.msg"
    },
    {
        "type": "ICS",
        "subject": "examplesubject",
        "from": "sender@example.com",
        "to": "user1@example.com,user2@example.com",
        "date": "Thu,4Jul202412:11:29+0530",
        "text": "text",
        "html": "<p>example-html</p>",
        "regex": {},
        "regex_from_text_part": {},
        "id": "ID",
        "name": "example.ics"
    }
]
Output messages

The Extract Data From Attached EML action provides the following output messages:

Output message Message description

Extracted data from ATTACHMENT_NAMES attached email files. Files: PATHS

Failed to find emails in MAILBOX with the following mail ids: MAIL_ID_LIST

 Action succeeded.

Failed to find any emails using the provided criteria!

Failed to find any of the provided mailboxes: MAILBOX_LIST

Action failed to run because the provided mailbox folder name MAILBOX_FOLDER was not found in the mailbox MAILBOX

Failed to execute action, the error is: ERROR_REASON

Action failed.

Check the connection to the server, input parameters, or credentials.
Script result

The following table describes the values for the script result output when using the Extract Data From Attached EML action:

Script result name Value
is_success True or False

Forward Email

Use the Forward Email action to forward emails that include previous threads. With the appropriate permissions, this action can send emails from a mailbox different than the one specified in the integration configuration.

This action doesn't run on entities.

Action inputs

The Forward Email action requires the following parameters:

Parameter Description
Send From Required

An optional email address from which to send an email if permissions allow it.

By default, the email is sent from the default mailbox that is specified in the integration configuration.
Folder Name Optional

A mailbox folder to search an email in.
Mail ID Required

The ID of the email to forward.
Subject Required

The email subject.
Send to Required

A comma-separated list of email addresses for the email recipients, such as user1@example.com, user2@example.com.
CC Optional

A comma-separated list of email addresses for the email CC field.

The format is the same as for the Send to parameter.
BCC Optional

A comma-separated list of email addresses for the email BCC field.

The format is the same as for the Send to parameter.
Attachments Paths Optional

A comma-separated list of paths for file attachments stored on the server, for example, /FILE_DIRECTORY/file.pdf, /FILE_DIRECTORY/image.jpg.
Mail content Required

The email body.

Action outputs

The following table describes the output types associated with the Forward Email action:

Action output type Availability
Case wall attachment Not available
Case wall link Not available
Case wall table Not available
Enrichment table Not available
JSON result Not available
Output messages Available
Script result Available
Output messages

The Forward Email action provides the following output messages:

Output message Message description
Email with message ID MAIL_ID was forwarded successfully. Action succeeded.

Error executing action "Forward Email" because the provided mail id EMAIL_ID was not found.

Action failed to delete any emails because the provided mailbox folder name was not found in the mailbox(es): MAILBOX: MAILBOX_FOLDER

Action failed to run because specified attachments were not found: ATTACHMENTS_LIST

Failed to execute action, the error is: ERROR_REASON

Action failed.

Check connection to the server, input parameters, or credentials.
Script result

The following table describes the values for the script result output when using the Forward Email action:

Script result name Value
is_success True or False

Mark Email as Junk

Use the Mark Email as Junk action to mark emails as junk in a specified mailbox. This action adds the email sender to the list of blocked senders and moves the message to the Junk Email folder.

The Mark Email as Junk action uses the beta version of Microsoft Graph API.

This action doesn't run on Google SecOps entities.

Action inputs

The Mark Email as Junk action requires the following parameters:

Parameter Description
Search In Mailbox Required

A mailbox to search for an email in.

By default, the action attempts to search for the email in the default mailbox that you specified in the integration configuration. To execute a search in other mailboxes, configure appropriate permissions for the action.

This parameter accepts multiple values as a comma separated string.
Folder Name Required

A mailbox folder to execute search in.

The default value is Inbox.
Mail IDs Required

The IDs or internetMessageId values of the mails to mark as junk.

This parameter accepts multiple values as a comma separated string.

Action outputs

The Mark Email as Junk action provides the following outputs:

Action output type Availability
Case wall attachment Not available
Case wall link Not available
Case wall table Not available
Enrichment table Not available
JSON result Not available
Output messages Available
Script result Available
Output messages

The Mark Email as Junk action can return the following output messages:

Output message Message description

Successfully marked the email as junk.

Failed to find email with ID ID in MAILBOX.

Mailbox MAILBOX was not found.

 The action succeeded.

Error executing action "Mark Email as Junk". Reason: ERROR_REASON

Failed to find any emails based on provided parameters!

Action failed to run because the provided mailbox folder name MAILBOX_FOLDER was not found in the mailbox MAILBOX.

The action failed.

Check the connection to the server, input parameters, or credentials.
Script result

The following table lists the value for the script result output when using the Mark Email as Junk action:

Script result name Value
is_success True or False

Mark Email as Not Junk

Use the Mark Email as Not Junk action to mark emails as not junk in a specific mailbox. This action removes the sender from the list of blocked senders and moves the message to the Inbox folder.

The Mark Email as Not Junk action uses the beta version of Microsoft Graph API.

This action doesn't run on Google SecOps entities.

Action inputs

The Mark Email as Not Junk action requires the following parameters:

Parameter Description
Search In Mailbox Required

A mailbox to search for an email in.

By default, the action attempts to search for the email in the default mailbox that you specified in the integration configuration. To execute a search in other mailboxes, configure appropriate permissions for the action.

This parameter accepts multiple values as a comma separated string.
Folder Name Required

A mailbox folder to execute search in.
Mail IDs Required

The IDs or internetMessageId values of the mails to mark as junk.

This parameter accepts multiple values as a comma separated string.

Action outputs

The Mark Email as Not Junk action provides the following outputs:

Action output type Availability
Case wall attachment Not available
Case wall link Not available
Case wall table Not available
Enrichment table Not available
JSON result Not available
Output messages Available
Script result Available
Output messages

The Mark Email as Not Junk action can return the following output messages:

Output message Message description

Successfully marked the email as not junk.

Failed to find email with ID ID in MAILBOX.

Mailbox MAILBOX was not found.

 The action succeeded.

Error executing action "Mark Email as Not Junk". Reason: ERROR_REASON

Failed to find any emails based on provided parameters!

Action failed to run because the provided mailbox folder name MAILBOX_FOLDER was not found in the mailbox MAILBOX.

The action failed.

Check the connection to the server, input parameters, or credentials.
Script result

The following table lists the value for the script result output when using the Mark Email as Not Junk action:

Script result name Value
is_success True or False

Move Email To Folder

Use the Move Email To Folder action to move one or multiple emails from the source email folder to the other folder in the mailbox. With the appropriate permissions, this action can move emails to other mailboxes different from the one that is provided in the integration configuration.

This action is asynchronous. Adjust the action timeout in the IDE accordingly.

This action doesn't run entities.

Action inputs

To configure the Move Email To Folder action, use the following parameters:

Parameter Description
Move In Mailbox Required

The default mailbox to execute the move operation in. If permissions allow it, the action can search in other mailboxes as well. This parameter accepts multiple values as a comma-separated string.

Source Folder Name Required

A source folder to move the email from.
Destination Folder Name Required

A destination folder to move the email to.

Provide the parameter value in the following format: inbox/folder_name/subfolder_name. This parameter is case insensitive.
Mail IDs Optional

A filter condition to search for emails with specific email IDs.

This parameter accepts a comma-separated list of email IDs to search for.

If this parameter is provided, the search ignores the Subject Filter and Sender Filter parameters.
Subject Filter Optional

A filter condition that specifies the email subject to search for.

This filter uses the contains logic.
Sender Filter Optional

A filter condition that specifies the sender of requested emails.

This filter uses the equals logic.
Time Frame (minutes) Optional

A filter condition that specifies the timeframe in minutes to search for emails.
Only Unread Optional

If selected, the action searches only for unread emails.

Not selected by default.
How many mailboxes to process in a single batch Optional

The number of mailboxes to process in a single batch (single connection to the mail server).

The default value is 25.

Action outputs

The following table describes the output types associated with the Move Email To Folder action:

Action output type Availability
Case wall attachment Not available
Case wall link Not available
Case wall table Not available
Enrichment table Not available
JSON result Not available
Output messages Available
Script result Available
Output messages

The Move Email To Folder action provides the following output messages:

Output message Message description

Successfully moved emails in the following mailboxes: MAILBOX: MOVED_EMAILS_NUMBER

Mailbox MAILBOX was not found.

 Action succeeded.

Action was not able to find any emails based on the specified search criteria.

Action failed to move any emails because the provided source folder was not found in the mailbox(es): MAILBOX_NAME, MAILBOX_FOLDER

Action failed to move any emails because the provided destination folder was not found in the mailbox(es): MAILBOX_NAME, MAILBOX_FOLDER

Failed to find any of the provided mailboxes: MAILBOX_LIST

Failed to execute action, the error is: ERROR_REASON

Action failed.

Check connection to the server, input parameters, or credentials.
Script result

The following table describes the values for the script result output when using the Move Email To Folder action:

Script result name Value
is_success True or False

Ping

Use the Ping action to test connectivity to the Microsoft Graph mail service.

This action doesn't run on entities.

Action inputs

None.

Action outputs

The following table describes the output types associated with the Ping action:

Action output type Availability
Case wall attachment Not available
Case wall link Not available
Case wall table Not available
Enrichment table Not available
JSON result Not available
Output messages Available
Script result Available
Output messages

The Ping action provides the following output messages:

Output message Message description
Successfully connected to the Microsoft Graph mail service with the provided connection parameters! Action succeeded.
Failed to connect to the Microsoft Graph mail service! Error is ERROR_REASON

Action failed.

Check connection to the server, input parameters, or credentials.
Script result

The following table describes the values for the script result output when using the Ping action:

Script result name Value
is_success True or False

Save Email To The Case

Use the Save Email To The Case action to save emails or email attachments to the Google SecOps Case Wall. With the appropriate permissions, this action can save emails from mailboxes other than the one provided in the integration configuration.

This action doesn't run on entities.

Action inputs

The Save Email To The Case action requires the following parameters:

Parameter Description
Search In Mailbox Required

The default mailbox to execute the search operation in. If permissions allow it, the action can search in other mailboxes.
Folder Name Optional

A mailbox folder to execute the search in.
Mail ID Required

The email ID to search for.

This parameter accepts a comma-separated list of email IDs to search for.
Save Only Email Attachments Optional

If selected, the action saves only attachments from the specified email.

Not selected by default.
Attachment To Save Optional

If the Save Only Email Attachments parameter is selected, the action only saves attachments specified by this parameter.

This parameter accepts multiple values as a comma-separated string.

Action outputs

The following table describes the output types associated with the Save Email To The Case action:

Action output type Availability
Case wall attachment Available
Case wall link Not available
Case wall table Not available
Enrichment table Not available
JSON result Available
Output messages Available
Script result Available
Case wall attachment

The following attachments are associated with the Save Email To The Case action:

  • EMAIL_SUBJECT.eml, if the action saves the email.

  • If the action saves the attachment, the attachment name contains a file extension, if any.

JSON result

The following example describes the JSON result output received when using the Save Email To The Case action:

{
    "id": "ID",
    "createdDateTime": "2024-02-16T14:10:34Z",
    "eml_info": "example_info",
    "lastModifiedDateTime": "2024-02-16T14:10:41Z",
    "changeKey": "cxsdjjh",
    "categories": [],
    "receivedDateTime": "2024-02-16T14:10:35Z",
    "sentDateTime": "2024-02-16T14:09:36Z",
    "hasAttachments": true,
    "internetMessageId": "INTERNET_MESSAGE_ID",
    "subject": "all attachments",
    "bodyPreview": "all the attachments",
    "importance": "normal",
    "parentFolderId": "PARENT_FOLDER_ID",
    "conversationId": "CONVERSATION_ID",
    "conversationIndex": "example-index",
    "isDeliveryReceiptRequested": false,
    "isReadReceiptRequested": false,
    "isRead": true,
    "isDraft": false,
    "webLink": "https://example.com/",
    "inferenceClassification": "focused",
    "body": {
        "contentType": "html",
        "content": "<html><head>example-html</head></html>"
    },
    "sender": {
        "emailAddress": {
            "name": "NAME",
            "address": "sender@example.com"
        }
    },
    "from": {
        "emailAddress": {
            "name": "NAME",
            "address": "user@example.com"
        }
    },
    "toRecipients": [
        {
            "emailAddress": {
                "name": "NAME",
                "address": "recipient@example.com"
            }
        }
    ],
    "ccRecipients": [],
    "bccRecipients": [],
    "replyTo": [],
    "flag": {
        "flagStatus": "notFlagged"
    }
}
Output messages

On a Case Wall, the Save Email To The Case action provides the following output messages:

Output message Message description

Email successfully saved!

Successfully saved the following attachments: ATTACHMENTS_LIST

The following attachments were not found in email with mail id: EMAIL_ID: ATTACHMENTS_LIST

 Action succeeded.

Mailbox MAILBOX_NAME was not found.

Action failed to run because the provided mailbox folder name MAILBOX_FOLDER was not found in the mailbox MAILBOX_NAME

Failed to execute action, the error is: ERROR_REASON

Action failed.

Check connection to the server, input parameters, or credentials.
Script result

The following table describes the values for the script result output when using the Save Email To The Case action:

Script result name Value
is_success True or False

Search Emails

Use the Search Emails action to execute email search in the default mailbox based on the provided search criteria. With appropriate permissions, this action can run a search in other mailboxes.

This action is asynchronous. Adjust the action timeout in the IDE accordingly.

This action doesn't run on entities.

Action inputs

The Search Emails action requires the following parameters:

Parameter Description
Search In Mailbox Required

The default mailbox to execute the search operation in. If permissions allow it, the action can search in other mailboxes. This parameter accepts multiple values as a comma-separated string.

For complex searches against a significant number of mailboxes, use the Exchange Extension Pack integration.

Folder Name Required

A mailbox folder to execute the search in.
Subject Filter Optional

A filter condition that specifies the email subject to search for.

This filter uses the contains logic.
Sender Filter Optional

A filter condition that specifies the sender of requested emails.

This filter uses the equals logic.
Time Frame (minutes) Optional

A filter condition that specifies the timeframe in minutes to search for emails.
Max Emails To Return Optional

The number of emails for the action to return.

If you provide no value, the API default value is used.
Only Unread Optional

If selected, the action searches only for unread emails.

Not selected by default.
Select All Fields For Return Optional

If selected, the action returns all available fields for the obtained email.

Not selected by default.
How many mailboxes to process in a single batch Optional

The number of mailboxes to process in a single batch (single connection to the mail server).

The default value is 25.

Action outputs

The following table describes the output types associated with the Search Emails action:

Action output type Availability
Case wall attachment Not available
Case wall link Not available
Case wall table Available
Enrichment table Not available
JSON result Not available
Output messages Available
Script result Available
Case wall table

On a Case Wall, the Search Emails action provides the following table:

Table title: Matching Mails

Columns:

  • Mail ID
  • Subject
  • Sender
  • Receivers
  • Received Date
Output messages

The Search Emails action provides the following output messages:

Action was not able to find any emails based on the specified search criteria.

Output message Message description

Successfully found emails in the following mailboxes: MAILBOX: FOUND_EMAILS_NUMBER

Mailbox MAILBOX was not found.

 Action succeeded.

Failed to find any of the provided mailboxes: MAILBOX_LIST

Failed to execute action, the error is: ERROR_REASON

Action failed.

Check connection to the server, input parameters, or credentials.
Script result

The following table describes the values for the script result output when using the Search Emails action:

Script result name Value
is_success True or False

Send Email

Use the Send Email action to send emails from a specific mailbox to an arbitrary list of recipients.

This action can send either plain text or HTML-formatted emails. With appropriate permissions, the action can send emails from a mailbox different than the one specified in the integration configuration.

This action doesn't run on entities.

Action inputs

The Send Email action requires the following parameters:

Parameter Description
Send From Required

An optional email address from which to send emails if permissions allow it.

By default, the action sends emails from the default mailbox specified in the integration configuration.
Subject Required

The email subject.
Send to Required

A comma-separated list of email addresses for the email recipients, such as user1@example.com, user2@example.com.
CC Optional

A comma-separated list of email addresses for the email CC field.

The format is the same as for the Send to parameter.
BCC Optional

A comma-separated list of email addresses for the email BCC field.

The format is the same as for the Send to parameter.
Attachments Paths Optional

A comma-separated list of paths for file attachments stored on the server, for example, /FILE_DIRECTORY/file.pdf, /FILE_DIRECTORY/image.jpg.
Mail Content Type Optional

The type of the email content.

The default value is Text .

Possible values:

  • Text
  • HTML
Mail Content Required

The email body.
Reply-To Recipients Optional

A comma-separated list of recipients to use in the Reply-To header.

Use the Reply-To header to redirect reply emails to the specific email address instead of the sender address that is stated in the From field.

Action outputs

The following table describes the output types associated with the Send Email action:

Action output type Availability
Case wall attachment Not available
Case wall link Not available
Case wall table Not available
Enrichment table Not available
JSON result Not available
Output messages Available
Script result Available
Output messages

The Send Email action provides the following output messages:

Output message Message description

Email was sent successfully.

 Action succeeded.

Action failed to run because specified attachments were not found: ATTACHMENTS_LIST

Failed to execute action, the error is: ERROR_REASON

Action failed.

Check connection to the server, input parameters, or credentials.
Script result

The following table describes the values for the script result output when using the Send Email action:

Script result name Value
is_success True or False

Send Email HTML

Use the Send Email HTML action to send emails using the Google SecOps HTML template from a specific mailbox to an arbitrary list of recipients. With appropriate permissions, the action can send emails from a mailbox other than the default one.

This action doesn't run on entities.

Action inputs

The Send Email HTML action requires the following parameters:

Parameter Description
Send From Required

An optional email address from which to send emails if permissions allow it.

By default, the action sends emails from the default mailbox specified in the integration configuration.
Subject Required

The email subject.
Send to Required

A comma-separated list of email addresses for the email recipients, such as user1@example.com, user2@example.com.
CC Optional

A comma-separated list of email addresses for the email CC field.

The format is the same as for the Send to parameter.
BCC Optional

A comma-separated list of email addresses for the email BCC field.

The format is the same as for the Send to parameter.
Attachments Paths Optional

A full path for the attachment to provide, for example, /FILE_DIRECTORY/file.pdf, /FILE_DIRECTORY/image.jpg.

You can provide multiple values in a comma-separated string.
Email HTML Template Required

The type of the HTML template to use.

The default value is Email HTML Template.

Possible values:

  • Email HTML Template
  • Dynamically generated list of available templates
Mail Content Required

The email body.
Reply-To Recipients Optional

A comma-separated list of recipients to use in the Reply-To header.

Use the Reply-To header to redirect reply emails to the specific email address instead of the sender address that is stated in the From field.
Attachment Location Required

A location where the attachments are stored.

By default, the action attempts to upload the attachment from the Cloud Storage bucket.

Possible values are GCP Bucket or Local File System. The default value is GCP Bucket.

Action outputs

The Send Email HTML action provides the following outputs:

Action output type Availability
Case wall attachment Not available
Case wall link Not available
Case wall table Not available
Enrichment table Not available
JSON result Available
Output messages Available
Script result Available
JSON result

The following example describes the JSON result output received when using the Send Email HTML action:

{
    "createdDateTime": "2024-01-30T16:50:27Z",
    "lastModifiedDateTime": "2024-01-30T16:50:27Z",
    "changeKey": "example-key",
    "categories": [],
    "receivedDateTime": "2024-01-30T16:50:27Z",
    "sentDateTime": "2024-01-30T16:50:27Z",
    "hasAttachments": false,
    "internetMessageId": "outlook.com",
    "subject": "Testing",
    "bodyPreview": "example",
    "importance": "normal",
    "parentFolderId": "ID",
    "conversationId": "ID",
    "conversationIndex": "INDEX",
    "isDeliveryReceiptRequested": false,
    "isReadReceiptRequested": false,
    "isRead": true,
    "isDraft": false,
    "webLink": "https://example.com",
    "inferenceClassification": "focused",
    "body": {
        "contentType": "html",
        "content": "content"
    },
    "sender": {
        "emailAddress": {
            "name": "NAME",
            "address": "sender@example.com"
        }
    },
    "from": {
        "emailAddress": {
            "name": "NAME",
            "address": "user@example.com"
        }
    },
    "toRecipients": [
        {
            "emailAddress": {
                "name": "NAME",
                "address": "recipient@example.com"
            }
        }
    ],
    "ccRecipients": [],
    "bccRecipients": [],
    "replyTo": [],
    "uniqueBody": {
        "contentType": "html",
        "content": "content"
    },
    "flag": {
        "flagStatus": "notFlagged"
    },
    "id": "ID"
}
Output messages

On a Case Wall, the Send Email HTML action provides the following output messages:

Output message Message description
Email was sent successfully. Action succeeded.

Action failed to run because the HTML template was not specified.

Action failed to run because the following specified attachments were not found: ATTACHMENT_LIST

Failed to execute action, the error is: ERROR_REASON

Action failed.

Check the connection to the server, input parameters, or credentials.
Script result

The following table describes the values for the script result output when using the Send Email HTML action:

Script result name Value
is_success True or False

Send Thread Reply

Use the Send Thread Reply action to send a message as a reply to the email thread. With appropriate permissions, the action can send emails from a mailbox other than the one specified in the integration configuration.

This action doesn't run on entities.

Action inputs

The Send Thread Reply action requires the following parameters:

Parameter Description
Send From Required

An optional email address from which to send emails if permissions allow it.

By default, the action sends emails from the default mailbox that is specified in the integration configuration.
Mail ID Required

The email ID to search for.
Folder Name Optional

A mailbox folder to execute the search in.

The default value is Inbox.
Attachments Paths Optional

A comma-separated list of paths for file attachments stored on the server, for example, /FILE_DIRECTORY/file.pdf, /FILE_DIRECTORY/image.jpg.
Mail Content Required

The email body.
Reply All Optional

If selected, the action sends a reply to all recipients related to the original email.

Not selected by default.

This parameter has priority over the Reply To parameter.
Reply To Optional

A comma-separated list of emails to send the reply to.

If you provide no value and the Reply All checkbox is clear, the action only sends a reply to the original email sender.

If the Reply All checkbox is selected, the action ignores this parameter.

Action outputs

The following table describes the output types associated with the Send Thread Reply action:

Action output type Availability
Case wall attachment Not available
Case wall link Not available
Case wall table Not available
Enrichment table Not available
JSON result Not available
Output messages Available
Script result Available
Output messages

The Send Thread Reply action provides the following output messages:

Output message Message description
Successfully sent reply to the mail with ID: EMAIL_ID Action succeeded.
Error executing action "Send Thread Reply". Reason: if you want to send a reply only to your own email address, you need to work with "Reply To" parameter.

Action failed.

Check the Reply To parameter value.

Error executing action "Send Thread Reply" because the provided mail id EMAIL_ID was not found.

Action failed to run because specified attachments were not found: ATTACHMENTS_LIST

Failed to execute action, the error is: ERROR_REASON

Action failed.

Check connection to the server, input parameters, or credentials.
Script result

The following table describes the values for the script result output when using the Send Thread Reply action:

Script result name Value
is_success True or False

Send Vote Email

Use the Send Vote Email action to send emails with the predefined answering options. This action uses Google SecOps HTML templates to format the email. With appropriate permissions, the Send Vote Email action can send emails from a mailbox other than the default one.

This action doesn't run on entities.

Action inputs

The Send Vote Email action requires the following parameters:

Parameter Description
Send From Required

An optional email address from which to send emails if permissions allow it.

By default, the action sends emails from the default mailbox specified in the integration configuration.
Subject Required

The email subject.
Send to Required

A comma-separated list of email addresses for the email recipients, such as user1@example.com, user2@example.com.
CC Optional

A comma-separated list of email addresses for the email CC field.

The format is the same as for the Send to parameter.
BCC Optional

A comma-separated list of email addresses for the email BCC field.

The format is the same as for the Send to parameter.
Attachments Paths Optional

A full path for the attachment to provide, for example, /FILE_DIRECTORY/file.pdf, /FILE_DIRECTORY/image.jpg.

You can provide multiple values in a comma-separated string.
Email HTML Template Required

The type of the HTML template to use.

The default value is Email HTML Template.

Possible values:

  • Email HTML Template
  • Dynamically generated list of available templates
Mail Content Required

The email body.
Reply-To Recipients Optional

A comma-separated list of recipients to use in the Reply-To header.

Use the Reply-To header to redirect reply emails to the specific email address instead of the sender address that is stated in the From field.
Structure of voting options Required

The structure of the vote to send to recipients.

Possible values are Yes/No or Approve/Reject. The default value is Yes/No.

Attachment Location Required

A location where the attachments are stored.

By default, the action attempts to upload the attachment from the Cloud Storage bucket.

Possible values are GCP Bucket or Local File System. The default value is GCP Bucket.

Action outputs

The Send Vote Email action provides the following outputs:

Action output type Availability
Case wall attachment Not available
Case wall link Not available
Case wall table Not available
Enrichment table Not available
JSON result Available
Output messages Available
Script result Available
JSON result

The following example describes the JSON result output received when using the Send Vote Email action:

{
    "createdDateTime": "2024-01-30T16:50:27Z",
    "lastModifiedDateTime": "2024-01-30T16:50:27Z",
    "changeKey": "KEY",
    "categories": [],
    "receivedDateTime": "2024-01-30T16:50:27Z",
    "sentDateTime": "2024-01-30T16:50:27Z",
    "hasAttachments": false,
    "internetMessageId": "<example-message-ID>",
    "subject": "Testing",
    "bodyPreview": "example",
    "importance": "normal",
    "parentFolderId": "FOLDER_ID",
    "conversationId": "CONVERSATION_ID",
    "conversationIndex": "CONVERSATION_INDEX",
    "isDeliveryReceiptRequested": false,
    "isReadReceiptRequested": false,
    "isRead": true,
    "isDraft": false,
    "webLink": "https://www.example.com/about",
    "inferenceClassification": "focused",
    "body": {
        "contentType": "html",
        "content": "content"
    },
    "sender": {
        "emailAddress": {
            "name": "NAME",
            "address": "sender@example.com"
        }
    },
    "from": {
        "emailAddress": {
            "name": "NAME",
            "address": "user@example.com"
        }
    },
    "toRecipients": [
        {
            "emailAddress": {
                "name": "NAME",
                "address": "recipient@example.com"
            }
        }
    ],
    "ccRecipients": [],
    "bccRecipients": [],
    "replyTo": [],
    "uniqueBody": {
        "contentType": "html",
        "content": "content"
    },
    "flag": {
        "flagStatus": "notFlagged"
    },
    "id": "ID"
}
Output messages

On a Case Wall, the Send Vote Email action provides the following output messages:

Output message Message description
Email was sent successfully. Action succeeded.

Action failed to run because the HTML template was not specified.

Action failed to run because the following specified attachments were not found: ATTACHMENT_LIST

Failed to execute action, the error is: ERROR_REASON

Action failed.

Check the connection to the server, input parameters, or credentials.
Script result

The following table describes the values for the script result output when using the Send Vote Email action:

Script result name Value
is_success True or False

Wait For Email From User

Use the Wait For Email From User action to wait for the user's response based on an email sent using the Send Email action.

This action is asynchronous. Adjust the action timeout in the IDE accordingly.

This action doesn't run on entities.

Action inputs

The Wait For Email From User action requires the following parameters:

Parameter Description
Mail ID Required

The ID of the email.

If the email is sent using the Send Mail action, set the parameter value to the SendEmail.JSONResult|id placeholder.
Wait for All Recipients to Reply? Optional

If selected, the action waits for responses from all recipients until reaching timeout or proceeding with the first reply.

Selected by default.
Wait Stage Exclude pattern Optional

A regular expression to exclude specific replies from the wait stage.

This parameter works with the email body.

Example: the action doesn't consider automatic out-of-office messages as recipient replies, instead waiting for an actual user reply.
Folder to Check for Reply Optional

A mailbox email folder to search for the user reply in. The search is run in the mailbox which the email containing a question was sent from.

This parameter accepts a comma-separated list of folders to check the user response in multiple folders.

This parameter is case-sensitive.

The default value is Inbox.
Fetch Response Attachments Optional

If selected and the recipient reply contains attachments, the action fetches the reply and adds it as an attachment to the Case Wall.

Not selected by default.

Action outputs

The following table describes the output types associated with the Wait For Email From User action:

Action output type Availability
Case wall attachment Available
Case wall link Not available
Case wall table Available
Enrichment table Not available
JSON result Not available
Output messages Available
Script result Available
Case wall attachment

The following Case Wall attachment is associated with the Wait For Mail From User action:

Type: Entity

Attachment content: Title, Filename (extensions included, if any), fileContent.

  • Title: RECIPIENT_EMAIL reply attachment.
  • Filename: ATTACHMENT_FILENAME + FILE_EXTENSION
  • fileContent: CONTENT_OF_THE_ATTACHED_FILE
Case wall table

On a Case Wall, the Wait For Mail From User action generates the following table:

Table title: Matching Mails

Columns:

  • Mail ID
  • Received Date
  • Sender
  • Recipients
  • Subject
Output messages

The Wait For Mail From User action provides the following output messages:

Output message Message description

Found the user EMAIL_RECIPIENT reply: USER_REPLY

Timeout getting reply from user: EMAIL_RECIPIENT.

 Action succeeded.

Action failed to receive any replies until timeout.

Failed to execute action, the error is: ERROR_REASON

Action failed.

Check connection to the server, input parameters, or credentials.
Script result

The following table describes the values for the script result output when using the Wait For Email From User action:

Script result name Value
is_success True or False

Wait For Vote Email Results

Use the Wait For Vote Email Results action to wait for the user response based on the vote email sent using the Send Vote Email action.

This action is asynchronous. Adjust the action timeout in the IDE accordingly.

This action doesn't run on entities.

Action inputs

The Wait For Vote Email Results action requires the following parameters:

Parameter Description
Vote Mail Sent From Required

By default, the actions sends an email from the default mailbox that you specified in the integration configuration.

Optionally, you can set a different value for this parameter if the vote mail is sent from a different mailbox.
Mail ID Required

The ID of the email.

If the email is sent using the Send Vote Email action, set the parameter value to the SendVoteEmail.JSONResult|id placeholder.

To return email IDs, you can use the Search Emails action.
Wait for All Recipients to Reply? Optional

If selected, the action waits for responses from all recipients until reaching timeout or proceeding with the first reply.

Selected by default.
Wait Stage Exclude pattern Optional

A regular expression to exclude specific replies from the wait stage.

This parameter works with the email body.

Example: the action doesn't consider automatic out-of-office messages as recipient replies, instead waiting for an actual user reply.
Folder to Check for Reply Optional

A mailbox email folder to search for the user reply in. The search is run in the mailbox which the email containing a question was sent from.

This parameter accepts a comma-separated list of folders to check the user response in multiple folders.

This parameter is case-sensitive.

The default value is Inbox.
Folder to Check for Sent Mail Optional

A mailbox folder to search for the sent mail in. It is a mailbox that you sent the email with a question from.

This parameter accepts a comma-separated list of folders to check the user response in multiple folders.

This parameter is case sensitive. The default value is Sent Items.
Fetch Response Attachments Optional

If selected and the recipient reply contains attachments, the action fetches the reply and adds it as an attachment to the Case Wall.

Not selected by default.

Action outputs

The Wait For Vote Email Results action provides the following outputs:

Action output type Availability
Case wall attachment Available
Case wall link Not available
Case wall table Available
Enrichment table Not available
JSON result Available
Output messages Available
Script result Available
Case wall attachment

The following Case Wall attachment is associated with the Wait For Vote Email Results action:

Type: Entity

Attachment content: Title, Filename (extensions included, if any), fileContent.

  • Title: RECIPIENT_EMAIL reply attachment.
  • Filename: ATTACHMENT_FILENAME + FILE_EXTENSION
  • fileContent: CONTENT_OF_THE_ATTACHED_FILE
Case wall table

On a Case Wall, the Wait For Email Results action generates the following table:

Table title: Matching Mails

Columns:

  • Mail ID
  • Received Date
  • Sender
  • Recipients
  • Subject
JSON result

The following example describes the JSON result output received when using the Wait For Vote Email Results action:

{
    "Responses": [
        {
            "recipient": "user@example.com",
            "vote": "Approve"
        }
    ]
}
Output messages

The Wait For Vote Email Results action provides the following output messages:

Output message Message description

Found the user EMAIL_RECIPIENT reply: USER_REPLY.

Exceeded timeout to get a reply from user: EMAIL_RECIPIENT.

 Action succeeded.

Action failed to receive any replies until timeout.

Failed to execute action, the error is: ERROR_REASON

Action failed.

Check the connection to the server, input parameters, or credentials.
Script result

The following table describes the values for the script result output when using the Wait For Vote Email Results action:

Script result name Value
is_success True or False

Connectors

For detailed instructions on how to configure a connector in Google SecOps, see Ingest your data (connectors).

Microsoft Graph Mail Connector

Use the Microsoft Graph Mail Connector to fetch emails from the Microsoft Graph mail service.

Use the dynamic list to filter specific values from the email body and subject parts using regular expressions. By default, the connector uses a regular expression to filter out the URLs from the email.

Connector parameters

The connector requires the following parameters:

Parameters
Product Field Name Required

The name of the field where the product name is stored.

The default value is device_product.
Event Field Name Required

The field name used to determine the event name (subtype).

The default value is event_name.
Environment Field Name Optional

The name of the field where the environment name is stored.

If the environment field isn't found, the environment is set to "".

Environment Regex Pattern Optional

A regular expression pattern to run on the value found in the Environment Field Name field. This parameter lets you manipulate the environment field using the regular expression logic.

Use the default value .* to retrieve the required raw Environment Field Name value.

If the regular expression pattern is null or empty, or the environment value is null, the final environment result is "".
Email exclude pattern Optional

A regular expression to exclude specific emails from ingestion, such as spam or news.

This parameter works with both the subject and body of the email.
Script Timeout (Seconds) Required

The timeout limit (in seconds) for the Python process running the current script.

The default value is 300 seconds.

Azure AD endpoint Required

The Microsoft Entra endpoint to connect to.

The default value is https://login.microsoftonline.com.
Microsoft Graph Endpoint Required

The Microsoft Graph endpoint to connect to.

The default value is https://graph.microsoft.com.
Client ID Required

For Microsoft 365 OAuth authentication, an application (client) ID of the Microsoft Entra app that is used in the integration.

Client Secret Required

For Microsoft 365 OAuth authentication, the client secret provided for the auth flow.
Tenant (Directory) ID Required

For Microsoft 365 OAuth authentication, the tenant (directory) ID of the Microsoft Entra app used in the integration.
Mail Address Required

An email address for the connector to use.
Folder to check for emails Required

An email folder to search for the emails. This parameter accepts a comma-separated list of folders to check the user response in multiple folders.

This parameter is case-sensitive.

The default value is Inbox.
Offset Time In Hours Required

The number of hours before now to fetch emails from.

The default value is 24 hours.
Max Emails Per Cycle Required

The number of emails to fetch for every connector iteration.

The default value is 10 emails.
Unread Emails Only Optional

If selected, the connector creates cases only from unread emails.

Not selected by default.
Mark Emails as Read Optional

If selected, the connector marks emails as read after ingesting.

Not selected by default.
Disable Overflow Optional

If selected, the connector ignores the overflow mechanism.

Not selected by default.
Original Received Mail Prefix Optional

A prefix to add to the extracted event keys (for example, to, from, or subject) from the original email received in the monitored mailbox.

The default value is orig.
Attached Mail File Prefix Optional

A prefix to add to the extracted event keys (for example, to, from, or subject) from the attached email file received in the monitored mailbox.

The default value is attach.
Attach Original EML Optional

If selected, the connector attaches the original email to the case info as an EML file.

Not selected by default.
Headers to add to events Optional

A comma-separated string specifying which email headers to add to events.

You can provide an exact match for headers or set this parameter value as a regular expression.
Proxy Server Address Optional

The address of the proxy server to use.
Proxy Username Optional

The proxy username to authenticate with.
Proxy Password Optional

The proxy password to authenticate with.
Create a Separate Siemplify Alert per Attached Mail File Optional

If selected, the connector creates multiple alerts, with one alert for every attached email file.

This behavior is useful when you process emails with multiple email files attached and set the Google SecOps SOAR event mapping to create entities from attached email files.

Not selected by default.
Case Name Template Optional

A custom case name.

When you configure this parameter, the connector adds a new key called custom_case_name to the Google SecOps SOAR event.

You can provide placeholders in the following format: [name of the field].

Example: Phishing - [event_mailbox].

For placeholders, the connector uses the first Google SecOps SOAR event. The connector only handles keys containing the string value.
Alert Name Template Optional

A custom alert name.

You can provide placeholders in the following format: [name of the field].

Example: Phishing - [event_mailbox].

For placeholders, the connector uses the first Google SecOps SOAR event. The connector only handles keys containing the string value. If you provide no value or an invalid template, the connector uses the default alert name.

Connector rules

The connector supports proxies.