Skip to main content

O365 Outlook Mail Single User (Using Graph API)

This Integration is part of the Microsoft Graph Mail Single User Pack.#

Microsoft Graph allows Cortex XSOAR authorized access to a user's Outlook mail data in a personal or organization account. This integration was tested with version 1.0 of Microsoft Graph Mail Single User.

Use Cases

  • Monitor a specific email account and create incidents from incoming emails to the defined folder.
  • Send and reply to emails.

Fetch Incidents

The integration imports email messages from the destination folder in the target mailbox as incidents. If the message contains any attachments, they are uploaded to the War Room as files. If the attachment is an email (item attachment), Cortex XSOAR fetches information about the attached email and downloads all of its attachments (if there are any) as files. To use Fetch incidents, configure a new instance and select the Fetches incidents option in the instance settings.

Authentication

For more details about the authentication used in this integration, see Microsoft Integrations - Authentication . Note: For this integration, you cannot use a "Shared mailbox" regardless of the authentication method used.

Required Permissions

The following permissions are required for all commands:
  • Mail.ReadWrite - Delegated
  • Mail.Send - Delegated
  • User.Read - Delegated

Configure O365 Outlook Mail Single User (Using Graph API) on Cortex XSOAR

  1. Navigate to Settings > Integrations > Servers & Services .
  2. Search for O365 Outlook Mail Single User (Using Graph API).
  3. Click Add instance to create and configure a new integration instance.
    • Name : a textual name for the integration instance.
    • ID or Client ID - see Detailed Instructions (?)
    • Token or Tenant ID - see Detailed Instructions (?)
    • Key or Client Secret - see Detailed Instructions (?)
    • Authorization code (required for self-deployed Azure app)
    • Application redirect URI (required for self-deployed Azure app)
    • Fetch incidents
    • Email address from which to fetch incidents (e.g. "example@demisto.com")
    • Name of the folder from which to fetch incidents (supports Folder ID and sub-folders e.g. Inbox/Phishing)
    • First fetch timestamp (
    • Maximum number of emails to pull per fetch.
    • Trust any certificate (not secure)
    • Use system proxy settings
  4. Run !msgraph-mail-test command in CLI(instead of test button) to validate the new instance.

Commands

You can execute these commands from the Cortex XSOAR CLI, as part of an automation, or in a playbook. After you successfully execute a command, a DBot message appears in the War Room with the command details.

  1. Creates a draft message in a user's mailbox: msgraph-mail-create-draft
  2. Sends an email using Microsoft Graph: send-mail
  3. The replies to the recipients of a message: msgraph-mail-reply-to
  4. Sends a draft email using Microsoft Graph: msgraph-mail-send-draft
  5. Tests connectivity of the email: msgraph-mail-test

1. msgraph-mail-create-draft

Creates a draft message in a user's mailbox.

Base Command

msgraph-mail-create-draft

Required Permissions

The following permissions are required for this command.

  • Mail.ReadWrite
  • Mail.Send
  • User.Read
Input
Argument Name Description Required
to A comma-separated list of email addresses for the 'to' field. Optional
cc A comma-separated list of email addresses for the 'cc' field. Optional
bcc A comma-separated list of email addresses for the 'bcc' field. Optional
subject The subject for the draft. Required
body The contents (body) of the draft. Optional
body_type The body type of the email. Can be: "text", or "HTML". Optional
flag The flag value that indicates the status for the draft. Can be: "notFlagged", "complete", or "flagged". Optional
importance The importance of the draft. Can be: "Low", "Normal", or "High". Optional
headers A comma-separated list of additional headers in the format, headerName:headerValue. For example, "headerName1:headerValue1,headerName2:headerValue2". Optional
attach_ids A comma-separated list of War Room entry IDs that contain files, which are used to attach files to the draft. For example, attachIDs=15@8,19@8. Optional
attach_names A comma-separated list of names of attachments to be displayed in the draft. Must be the same number of elements as attachIDs. Optional
attach_cids A comma-separated list of CIDs to embed attachments within the email itself. Optional

Context Output
Path Type Description
MicrosoftGraph.Draft.Cc String Cc of the draft email.
MicrosoftGraph.Draft.IsRead String Is read status of the draft email.
MicrosoftGraph.Draft.Bcc String The Bcc of the draft email.
MicrosoftGraph.Draft.Body String The body of the draft email.
MicrosoftGraph.Draft.MessageID String The message id of the draft email.
MicrosoftGraph.Draft.SentTime Date The created time of the draft email.
MicrosoftGraph.Draft.Headers String The headers of the draft email.
MicrosoftGraph.Draft.From String The from of the draft email.
MicrosoftGraph.Draft.Subject String The subject of the draft email.
MicrosoftGraph.Draft.ReceivedTime String The received time of the draft email.
MicrosoftGraph.Draft.Importance String The importance status of the draft email.
MicrosoftGraph.Draft.CreatedTime String The created time of the draft email.
MicrosoftGraph.Draft.Sender String The sender of the draft email.
MicrosoftGraph.Draft.ModifiedTime Date The modified time of the draft email.
MicrosoftGraph.Draft.IsDraft Boolean Indicates whether it is a draft email.
MicrosoftGraph.Draft.ID String The ID of the draft email.
MicrosoftGraph.Draft.To String The to recipients of the draft.
MicrosoftGraph.Draft.BodyType Unknown The body type of the draft email.
MicrosoftGraph.Draft.ConversationID String The conversation ID of the draft email.

Command Example

!msgraph-mail-create-draft subject="Test Subject" flag=flagged importance=Normal to=test@demistodev.onmicrosoft.com

Context Example 
{
    "MicrosoftGraph.Draft": {
        "Bcc": [],
        "Body": "",
        "BodyType": "text",
        "Cc": [],
        "ConversationID": "conversation_id",
        "CreatedTime": "2019-12-01T08:25:34Z",
        "From": "",
        "Headers": [],
        "ID": "unique_id",
        "Importance": "normal",
        "IsDraft": true,
        "IsRead": true,
        "MessageID": "",
        "ModifiedTime": "2019-12-01T08:25:34Z",
        "ReceivedTime": "2019-12-01T08:25:34Z",
        "Sender": "",
        "SentTime": "2019-12-01T08:25:34Z",
        "Subject": "Test Subject",
        "To": [
            "test@demistodev.onmicrosoft.com"
        ]
    }
}
Human Readable Output

Created draft with id: unique_id

Bcc Body BodyType Cc ConversationID CreatedTime From Headers ID Importance IsDraft IsRead MessageID ModifiedTime ReceivedTime Sender SentTime Subject To
text convesation_id 2019-12-01T08:25:34Z unique_id normal true true 2019-12-01T08:25:34Z 2019-12-01T08:25:34Z 2019-12-01T08:25:34Z Test Subject test@demistodev.onmicrosoft.com

2. send-mail

Sends an email using Microsoft Graph.

Base Command

send-mail

Required Permissions

The following permissions are required for this command.

  • Mail.ReadWrite
  • Mail.Send
  • User.Read
Input
Argument Name Description Required
to A comma-separated list of email addresses for the 'to' field. Optional
cc A comma-separated list of email addresses for the 'cc' field. Optional
bcc A comma-separated list of email addresses for the 'bcc' field. Optional
subject The subject of the email. Required
body The contents (body) of the email. Optional
body_type The body type of the email. Can be: "text", or "HTML". Optional
flag The flag value that indicates the status for the email. Can be: "notFlagged", "complete", or "flagged". Optional
importance The importance of the email. Can be: "Low", "Normal", or "High". Optional
headers A comma-separated list of additional headers in the format: headerName:headerValue. For example: "headerName1:headerValue1,headerName2:headerValue2". Optional
attach_ids A comma-separated list of War Room entry IDs that contain files, which are used to attach files for the email to send. For example, attachIDs=15@8,19@8. Optional
attach_names A comma-separated list of names of attachments to be displayed in the email to send. Must be the same number of elements as attachIDs. Optional
attach_cids A comma-separated list of CIDs to embed attachments within the email. Optional
from The email address from which to reply. Optional
replyTo A comma separated list of email addresses that need to be used to reply to the message. Optional

Context Output
Path Type Description
MicrosoftGraph.Email.internetMessageHeaders String The email headers.
MicrosoftGraph.Email.body String The body of the email.
MicrosoftGraph.Email.bodyPreview String The body preview of the email.
MicrosoftGraph.Email.subject String The subject of the email.
MicrosoftGraph.Email.flag String The flag status of the email.
MicrosoftGraph.Email.importance String The importance status of the email.
MicrosoftGraph.Email.toRecipients String The to recipients of the email.
MicrosoftGraph.Email.ccRecipients String The cc recipients of the email.
MicrosoftGraph.Email.bccRecipients String The bcc recipients of the email.
MicrosoftGraph.Email.replyTo String The replyTo recipients of the email.

Command Example

!send-mail subject="Test Subject" flag=flagged importance=Normal to=test@demistodev.onmicrosoft.com body_type=HTML attach_ids=attach_id attach_cids=attach_cid attach_names=a1.rtf body="<h1>Added inline</h1> <img src=\"cid:a2.png\" height=\"50\" width=\"50\"> <h1>End</h1>" headers="x-custom:testheader"

Context Example 
{
    "MicrosoftGraph.Email": {
        "bccRecipients": [],
        "body": {
            "content": "html_body",
            "contentType": "HTML"
        },
        "bodyPreview": "body_preview",
        "ccRecipients": [],
        "flag": {
            "flagStatus": "flagged"
        },
        "importance": "Normal",
        "internetMessageHeaders": [
            {
                "name": "x-custom",
                "value": "testheader"
            }
        ],
        "subject": "Test Subject",
        "toRecipients": [
            {
                "emailAddress": {
                    "address": "test@demistodev.onmicrosoft.com"
                }
            }
        ]
    }
}
Human Readable Output

Email was sent successfully.

bccRecipients body bodyPreview ccRecipients flag importance internetMessageHeaders subject toRecipients
content:

Added inline


contentType: HTML

Added inline

flagStatus: flagged Normal {'name': 'x-custom', 'value': 'testheader'} Test Subject {'emailAddress': {'address': 'test@demistodev.onmicrosoft.com'}}

Sending mails with embedded images
In order to send a mail with embedded image, the image content ID should be passed the attach_cids argument and referenced in the HTML mark-up. Note: You will have to specify this CID reference when you add the attachment to the mail message. For example: !send-mail subject="Mail with an embedded image" attach_cids=1@2 body_type=HTML body="<h1>A mail with an embedded image <img src='cid:1@2' /></h1>"

3. msgraph-mail-reply-to

The replies to the recipients of a message.

Base Command

msgraph-mail-reply-to

Required Permissions

The following permissions are required for this command.

  • Mail.ReadWrite
  • Mail.Send
  • User.Read
Input
Argument Name Description Required
message_id The ID of the message. Required
comment The comment of the replied message. Required
to A comma-separated list of email addresses for the 'to' field. Required
attach_ids A comma-separated list of War Room entry IDs that contain files, which are used to attach files for the email to send. For example, attachIDs=15@8,19@8. Optional
attach_names A comma-separated list of names of attachments to be displayed in the email to send. Must be the same number of elements as attachIDs. Optional
attach_cids A comma-separated list of CIDs to embed attachments within the email. Optional

Context Output
There are no context output for this command.

Command Example

!msgraph-mail-reply-to message_id=message_id comment="Reply message" to=test@demistodev.onmicrosoft.com

Human Readable Output

Replied to: test@demistodev.onmicrosoft.com with comment: Reply message

4. msgraph-mail-send-draft

Sends a draft email using Microsoft Graph.

Base Command

msgraph-mail-send-draft

Required Permissions

The following permissions are required for this command.

  • Mail.ReadWrite
  • Mail.Send
  • User.Read
Input
Argument Name Description Required
draft_id The ID of the draft email. Required

Context Output
There are no context output for this command.

Command Example

!msgraph-mail-send-draft draft_id=message_id

Human Readable Output

Draft with: message_id id was sent successfully.

5. msgraph-mail-test

Tests connectivity of the email.

Base Command

msgraph-mail-test

Required Permissions

The following permissions are required for this command.

  • Mail.ReadWrite
  • Mail.Send
  • User.Read
Input
There are no input arguments for this command.

Context Output
There are no context output for this command.

Command Example

!msgraph-mail-test

Human Readable Output

✅ Success!

### reply-mail *** Replies to an email using Graph Mail Single User. #### Base Command `reply-mail` #### Input | **Argument Name** | **Description** | **Required** | | --- | --- | --- | | to | A CSV list of email addresses for the 'to' field. | Required | | body | The contents (body) of the email to be sent. | Optional | | subject | Subject for the email to be sent. | Required | | inReplyTo | ID of the item to reply to. | Required | | attachIDs | A CSV list of War Room entry IDs that contain files, and are used to attach files to the outgoing email. For example: attachIDs=15@8,19@8. | Optional | | cc | A CSV list of email addresses for the 'cc' field. | Optional | | bcc | A CSV list of email addresses for the 'bcc' field. | Optional | | htmlBody | HTML formatted content (body) of the email to be sent. This argument overrides the "body" argument. | Optional | | attachNames | A CSV list of names of attachments to send. Should be the same number of elements as attachIDs. | Optional | | attachCIDs | A CSV list of CIDs to embed attachments within the email itself. | Optional | | from | Email address of the sender. | Optional | #### Context Output | **Path** | **Type** | **Description** | | --- | --- | --- | | MicrosoftGraph.SentMail.body | String | The body of the email. | | MicrosoftGraph.SentMail.bodyPreview | String | The body preview of the email. | | MicrosoftGraph.SentMail.subject | String | The subject of the email. | | MicrosoftGraph.SentMail.toRecipients | String | The 'To' recipients of the email. | | MicrosoftGraph.SentMail.ccRecipients | String | The CC recipients of the email. | | MicrosoftGraph.SentMail.bccRecipients | String | The BCC recipients of the email. | | MicrosoftGraph.SentMail.ID | String | The immutable ID of the message. | #### Command Example ``` !reply-mail to=dev@demistodev.onmicrosoft.com body="This is the body" subject="This is the subject" inReplyTo=AAMkAGY3OTQyM cc=dev3@demistodev.onmicrosoft.com bcc=dev2@demistodev.onmicrosoft.com attachCIDs=3604@6e069bc4-2a1e-43ea-8ed3-ea558e377751 ``` ##### Context Example ``` { "MicrosoftGraph": { "SentMail": { "ID": "AAMkAGY3OTQyM", "body": { "content": "This is the body", "contentType": "html" }, "bodyPreview" : "This is the body", "subject": "Re: This is the subject", "ccRecipients": [ "dev3@demistodev.onmicrosoft.com" ], "bccRecipients": [ "dev2@demistodev.onmicrosoft.com" ], "toRecipients": [ "dev@demistodev.onmicrosoft.com" ] } } } ``` ##### Human Readable Output ##### Replied message was successfully sent to dev@demistodev.onmicrosoft.com |ID|subject|toRecipients| |---|---|---| |AAMkAGY3OTQyM | Re: This is the subject | dev@demistodev.onmicrosoft.com |
Edit this page
Report an Issue