O365 Outlook Mail Single User (Using Graph API)
Microsoft Graph Mail Single User Pack.#
This Integration is part of theMicrosoft 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
- Navigate to Settings > Integrations > Servers & Services .
- Search for O365 Outlook Mail Single User (Using Graph API).
-
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
- 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.
- Creates a draft message in a user's mailbox: msgraph-mail-create-draft
- Sends an email using Microsoft Graph: send-mail
- The replies to the recipients of a message: msgraph-mail-reply-to
- Sends a draft email using Microsoft Graph: msgraph-mail-send-draft
- 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 inlinecontentType: 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 |