Cortex XSOAR for Developers (Formerly Demisto)

Microsoft Graph Mail Single User

Microsoft Graph allows Demisto 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.

Detailed Description

To allow us access to Microsoft Graph Mail, you need to approve our app, by clicking on the following link . After authorizing the Demisto app, you will receive an ID, Refresh Token, and Key, which needs to be added to the integration instance configuration's corresponding fields.

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), Demisto 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.

Generate Authentication Parameters

  1. Navigate to Settings > Integrations > Servers & Services .
  2. Search for Microsoft Graph Mail Single User.
  3. Click Add instance to create and configure a new integration instance.
  4. Click the question mark button in the upper-right corner and read the information, and click the link.
  5. Click the Start Authorization Process button.
  6. Log in with Microsoft user credentials.
  7. Authorize Demisto application to access data.
  8. When you are redirected, copy the parameter values, which you will need when configuring the integration instance in Demisto.
    • ID
    • Key
    • Token

Configure Microsoft Graph Mail Single User on Demisto

  1. Navigate to Settings > Integrations > Servers & Services .
  2. Search for Microsoft Graph Mail Single User.
  3. Click Add instance to create and configure a new integration instance.
    • Name : a textual name for the integration instance.
    • ID (received from the authorization step - see Detailed Instructions (?) section)
    • Token (received from the authorization step - see Detailed Instructions (?) section)
    • Key (received from the authorization step - see Detailed Instructions (?) section)
    • 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.

Required Permissions

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

Commands

You can execute these commands from the Demisto 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

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.

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'}}

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

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!```

Additional Information

Known Limitations

Troubleshooting

Edit this page
Report an Issue