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.
  • 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.

    Authentication

    For more details about the authentication used in this integration, see Microsoft Integrations - Authentication .

    Required Permissions

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

    Configure Microsoft Graph Mail Single User on Cortex XSOAR

    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.

    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