Skip to main content

Microsoft Graph Mail Single User

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

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

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.

OData Usage#

The OData parameter can be used to create different queries for the msgraph-mail-list-emails and msgraph-mail-get-email commands. Please see OData Docs for detailed information. Examples: !msgraph-mail-list-emails odata="$select=from" !msgraph-mail-list-emails odata="$filter=from/emailAddress/address eq 'azure-noreply@microsoft.com'" !msgraph-mail-list-emails odata="$filter=sentDateTime gt 2020-03-25T09:35:23Z and sentDateTime lt 2020-03-25T12:04:47Z"

Note: The query parameter $filter is not supported when using the search parameter.

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.

Email Attachments Limitations#

  • The maximum attachment size to be sent in an email can be 150-MB. large-attachments
  • The larger the attachment, the longer it would take for a command that supports adding attachments to run.
  • Requires the permission of Mail.ReadWrite (Application) - to send attachments > 3mb
  • When sending mails with large attachments, it could take up to 5 minutes for the mail to actually be sent.

Required Permissions#

The following permissions are required for all commands:

  • Mail.ReadWrite - Delegated
  • Mail.Send - Delegated
  • User.Read - Delegated

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.

    ParameterDescriptionRequired
    ID or Client ID - see Detailed Instructions (?)True
    Token or Tenant ID - see Detailed Instructions (?)True
    Key or Client Secret - see Detailed Instructions (?)False
    Certificate Thumbprint (optional for self-deployed Azure app)Used for certificate authentication. As appears in the "Certificates & secrets" page of the app.False
    Private KeyUsed for certificate authentication. The private key of the registered certificate.False
    Authorization code (required for self-deployed Azure app)False
    Application redirect URI (required for self-deployed Azure app)False
    Use Azure Managed IdentitiesRelevant only if the integration is running on Azure VM. If selected, authenticates based on the value provided for the Azure Managed Identities Client ID field. If no value is provided for the Azure Managed Identities Client ID field, authenticates based on the System Assigned Managed Identity. For additional information, see the Help tab.False
    Azure Managed Identities Client IDThe Managed Identities client ID for authentication - relevant only if the integration is running on Azure VM.False
    Fetch incidentsFalse
    Email address from which to fetch incidents (e.g., "example@demisto.com")True
    Name of the folder from which to fetch incidents (supports Folder ID and sub-folders e.g., Inbox/Phishing)True
    First fetch timestamp (<number> <time unit>, e.g., 12 hours, 7 days)False
    Maximum number of emails to pull per fetchFalse
    Trust any certificate (not secure)False
    Use system proxy settingsFalse
    Use a self-deployed Azure applicationFalse
    Incident typeFalse
    Display full email bodyIf not active, only a preview of the email will be fetched.
    Mark fetched emails as readRelevant only if fetch incidents is active.
    Incidents Fetch IntervalFalse
  4. Click Test to validate the URLs, token, and connection.

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.

msgraph-mail-create-draft#


Creates a draft message in the specified user's mailbox.

Base Command#

msgraph-mail-create-draft

Input#

Argument NameDescriptionRequired
toA comma-separated list of email addresses for the 'to' field.Optional
ccA comma-separated list of email addresses for the 'cc' field.Optional
bccA comma-separated list of email addresses for the 'bcc' field.Optional
subjectThe subject for the draft.Required
bodyThe contents (body) of the draft.Optional
body_typeThe body type of the email. Can be: "text", or "HTML". Possible values are: text, HTML. Default is text.Optional
flagThe flag value that indicates the status of the draft. Possible values are: notFlagged, complete, flagged. Default is notFlagged.Optional
importanceThe importance of the draft. Possible values are: Low, Normal, High. Default is Low.Optional
headersA comma-separated list of additional headers in the format, headerName:headerValue. For example, "headerName1:headerValue1,headerName2:headerValue2".Optional
attach_idsA 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_namesA comma-separated list of names of attachments to be displayed in the draft. Must be the same number of elements as attachIDs.Optional
attach_cidsA comma-separated list of CIDs to embed attachments within the actual email.Optional

Context Output#

PathTypeDescription
MicrosoftGraph.Draft.CcStringThe CC recipients of the draft email.
MicrosoftGraph.Draft.IsReadStringThe "Is read" status of the draft email.
MicrosoftGraph.Draft.BccStringThe BCC recipients of the draft email.
MicrosoftGraph.Draft.BodyStringThe body of the draft email.
MicrosoftGraph.Draft.MessageIDStringThe message ID of the draft email.
MicrosoftGraph.Draft.SentTimeDateThe sent time of the draft email.
MicrosoftGraph.Draft.HeadersStringThe headers of the draft email.
MicrosoftGraph.Draft.FromStringThe user that sent the draft email.
MicrosoftGraph.Draft.SubjectStringThe subject of the draft email.
MicrosoftGraph.Draft.ReceivedTimeStringThe received time of the draft email.
MicrosoftGraph.Draft.ImportanceStringThe importance status of the draft email.
MicrosoftGraph.Draft.CreatedTimeStringThe created time of the draft email.
MicrosoftGraph.Draft.SenderStringThe sender of the draft email.
MicrosoftGraph.Draft.ModifiedTimeDateThe modified time of the draft email.
MicrosoftGraph.Draft.IsDraftBooleanWhether it is a draft email.
MicrosoftGraph.Draft.IDStringThe ID of the draft email.
MicrosoftGraph.Draft.ToStringThe 'to' recipients of the draft email.
MicrosoftGraph.Draft.BodyTypeUnknownThe body type of the draft email.
MicrosoftGraph.Draft.ConversationIDStringThe conversation ID of the draft email.
Command Example#

!msgraph-mail-create-draft subject=EmailSubject

reply-mail#


Replies to an email using Graph Mail Single User.

Required Permissions#

The following permissions are required for this command:

  • Mail.Send (Application)
  • Mail.ReadWrite (Application) - to send attachments > 3mb

Base Command#

reply-mail

Input#

Argument NameDescriptionRequired
toA comma-separated list of email addresses for the 'to' field.Required
bodyThe contents (body) of the email to be sent.Optional
subjectSubject for the email to be sent.Required
inReplyToID of the item to reply to.Required
attachIDsA comma-separated 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
ccA comma-separated list of email addresses for the 'cc' field.Optional
bccA comma-separated list of email addresses for the 'bcc' field.Optional
htmlBodyHTML formatted content (body) of the email to be sent. This argument overrides the "body" argument.Optional
attachNamesA comma-separated list of names of attachments to send. Should be the same number of elements as attachIDs.Optional
attachCIDsA comma-separated list of CIDs to embed attachments within the email itself.Optional

Context Output#

PathTypeDescription
MicrosoftGraph.SentMail.bodyStringThe body of the email.
MicrosoftGraph.SentMail.bodyPreviewStringThe body preview of the email.
MicrosoftGraph.SentMail.subjectStringThe subject of the email.
MicrosoftGraph.SentMail.toRecipientsStringThe 'To' recipients of the email.
MicrosoftGraph.SentMail.ccRecipientsStringThe CC recipients of the email.
MicrosoftGraph.SentMail.bccRecipientsStringThe BCC recipients of the email.
MicrosoftGraph.SentMail.IDStringThe immutable ID of the message.

Command Example#

!reply-mail to=email1 subject=subject inReplyTo=123

send-mail#


Sends an email using Microsoft Graph.

Required Permissions#

The following permissions are required for this command:

  • Mail.Send (Application)
  • Mail.ReadWrite (Application) - to send attachments > 3mb

Base Command#

send-mail

Input#

Argument NameDescriptionRequired
toA comma-separated list of email addresses for the 'to' field.Optional
ccA comma-separated list of email addresses for the 'cc' field.Optional
bccA comma-separated list of email addresses for the 'bcc' field.Optional
subjectThe subject of the email.Required
bodyThe contents (body) of the email.Optional
body_typeThe body type of the email. Can be: "text", or "HTML". Possible values are: text, HTML.Optional
flagThe flag value that indicates the status for the email. Possible values are: notFlagged, complete, flagged. Default is notFlagged.Optional
importanceThe importance of the email. Possible values are: Low, Normal, High. Default is Low.Optional
headersA comma-separated list of additional headers in the format: headerName:headerValue. For example: "headerName1:headerValue1,headerName2:headerValue2".Optional
attach_idsA 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_namesA comma-separated list of names of attachments to display in the email to send. Must be the same number of elements as attachIDs.Optional
attach_cidsA comma-separated list of CIDs to embed attachments within the actual email.Optional
replyToEmail addresses that need to be used to reply to the message. Supports comma-separated values.Optional

Context Output#

PathTypeDescription
MicrosoftGraph.Email.internetMessageHeadersStringThe email headers.
MicrosoftGraph.Email.bodyStringThe body of the email.
MicrosoftGraph.Email.bodyPreviewStringThe body preview of the email.
MicrosoftGraph.Email.subjectStringThe subject of the email.
MicrosoftGraph.Email.flagStringThe flag status of the email.
MicrosoftGraph.Email.importanceStringThe importance status of the email.
MicrosoftGraph.Email.toRecipientsStringThe 'to' recipients of the email.
MicrosoftGraph.Email.ccRecipientsStringThe CC recipients of the email.
MicrosoftGraph.Email.bccRecipientsStringThe BCC recipients of the email.
MicrosoftGraph.Email.replyToStringThe replyTo recipients of the email.

msgraph-mail-reply-to#


The replies to the recipients of a message.

Base Command#

msgraph-mail-reply-to

Input#

Argument NameDescriptionRequired
message_idThe ID of the message.Required
commentThe comment of the replied message.Required
toA comma-separated list of email addresses for the 'to' field.Required
attach_idsA 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_namesA comma-separated list of names of attachments to display in the email to send. Must be the same number of elements as attach_ids.Optional
attach_cidsA comma-separated list of CIDs to embed attachments within the actual email.Optional

Context Output#

There is no context output for this command.

Command Example#

msgraph-mail-send-draft#


Sends a draft email using Microsoft Graph.

Base Command#

msgraph-mail-send-draft

Input#

Argument NameDescriptionRequired
draft_idThe ID of the draft email.Required

Context Output#

There is no context output for this command.

msgraph-mail-test#


Tests connectivity of the email.

Base Command#

msgraph-mail-test

Input#

Argument NameDescriptionRequired

Context Output#

There is no context output for this command.

msgraph-mail-auth-reset#


Run this command to rerun the authentication process.

Base Command#

msgraph-mail-auth-reset

Input#

Argument NameDescriptionRequired

Context Output#

There is no context output for this command.

msgraph-mail-list-emails#


Gets the properties of returned emails. Typically shows partial results. Use the "page_size" and "pages_to_pull" arguments to get all results.

Base Command#

msgraph-mail-list-emails

Input#

Argument NameDescriptionRequired
odataAn OData query. See OData Usage for OData usage examples.Optional
searchThe term for which to search. This argument cannot contain reserved characters such as !, $, #, @, etc. For further information, see https://tools.ietf.org/html/rfc3986#section-2.2.Optional
page_sizeThe maximum number of emails to fetch in one request. Default is 20.Optional
pages_to_pullThe number of pages of emails to return (maximum is 10 emails per page). Default is 1.Optional

Context Output#

PathTypeDescription
MSGraphMail.IDStringThe ID of the email.
MSGraphMail.CreatedDateThe time the email was created.
MSGraphMail.LastModifiedTimeDateThe time the email was last modified.
MSGraphMail.ReceivedTimeDateThe time the email was received.
MSGraphMail.SendTimeDateThe time the email was sent.
MSGraphMail.CategoriesStringCategories of the email.
MSGraphMail.HasAttachmentsBooleanWhether the email has attachments.
MSGraphMail.SubjectStringThe subject of the email.
MSGraphMail.IsDraftBooleanWhether the email is a draft.
MSGraphMail.BodyStringThe content (body) of the email.
MSGraphMail.Sender.NameStringThe name of the sender.
MSGraphMail.Sender.AddressStringThe email address of the sender.
MSGraphMail.From.NameStringThe name of the user in the 'from' field of the email.
MSGraphMail.From.AddressStringThe email address of the user in the 'from' field of the email.
MSGraphMail.CCRecipients.NameStringThe names of the CC recipients.
MSGraphMail.CCRecipients.AddressStringThe email address of the user in the 'cc' field of the email.
MSGraphMail.BCCRecipients.NameStringThe names of the users in the 'bcc' field of the email.
MSGraphMail.BCCRecipients.AddressStringThe email address of the user in the 'bcc' field of the email.
MSGraphMail.ReplyTo.NameStringThe name in the 'replyTo' field of the email.
MSGraphMail.ReplyTo.AddressStringThe email address in the 'replyTo' field of the email.
MSGraphMail.UserIDStringThe ID of the user.
MSGraphMail.ConversationIDStringThe ID of the conversation.
MSGraphMail.InternetMessageIDStringInternet Message ID of the message
MSGraphMail.Recipients.NameStringThe name of the user in the 'toRecipients' field of the email.
MSGraphMail.Recipients.AddressStringThe email address of the user in the 'toRecipients' field of the email.
MSGraphMail.NextPageStringA token to pass to the next list command to retrieve additional results.

msgraph-mail-get-attachment#


Get email attachment

Base Command#

msgraph-mail-get-attachment

Input#

Argument NameDescriptionRequired
message_idThe email message ID.Required
attachment_idThe ID of the attachment.Required
folder_idThe ID of the folder.Optional

Context Output#

PathTypeDescription
File.SizeNumberThe size of the file.
File.SHA1StringThe SHA1 hash of the file.
File.SHA256StringThe SHA256 hash of the file.
File.NameStringThe name of the file.
File.SSDeepStringThe SSDeep hash of the file.
File.EntryIDStringThe entry ID of the file.
File.InfoStringFile information.
File.TypeStringThe file type.
File.MD5StringThe MD5 hash of the file.
File.ExtensionStringThe file extension.

msgraph-mail-list-attachments#


Lists all of the attachments of given email

Base Command#

msgraph-mail-list-attachments

Input#

Argument NameDescriptionRequired
message_idThe email message ID.Required
folder_idThe ID of the folder.Optional
ran_once_flagFlag for rate limit retry.Optional

Context Output#

PathTypeDescription
MSGraphMailAttachment.IDStringThe email ID.
MSGraphMailAttachment.Attachment.IDStringThe ID of the attachment.
MSGraphMailAttachment.Attachment.NameStringThe name of the attachment.
MSGraphMailAttachment.Attachment.TypeStringThe attachment type.
MSGraphMailAttachment.UserIDStringThe ID of the user.

msgraph-mail-get-email-as-eml#


Retrieves an email message by message ID and uploads the content as an EML file.

Base Command#

msgraph-mail-get-email-as-eml

Input#

Argument NameDescriptionRequired
message_idThe unique ID of the email. You cannot use the 'MessageID' key in the form '<message-id>'.Required

Context Output#

PathTypeDescription
File.SizeStringThe size of the file.
File.SHA1StringThe SHA1 hash of the file.
File.SHA256StringThe SHA256 hash of the file.
File.SHA512StringThe SHA512 hash of the file.
File.NameStringThe name of the file.
File.SSDeepStringThe SSDeep hash of the file.
File.EntryIDStringThe EntryID of the file.
File.InfoStringInformation about the file.
File.TypeStringThe file type.
File.MD5StringThe MD5 hash of the file.
File.ExtensionStringThe extension of the file.

msgraph-update-email-status#


Update the status of an email to read / unread.

Base Command#

msgraph-update-email-status

Input#

Argument NameDescriptionRequired
message_idsUnique ID of the emails to update. You cannot use the 'MessageID' key in the form '<message-id>'. Can be a list of comma-separated values.Required
folder_idThe folder ID.Optional
statusStatus to set the email to. Possible values are: Read, Unread.Required

Context Output#

There is no context output for this command.

msgraph-mail-generate-login-url#


Generate the login url used for Authorization code flow.

Base Command#

msgraph-mail-generate-login-url

Input#

There are no input arguments for this command.

Context Output#

There is no context output for this command.

Command Example#

msgraph-mail-generate-login-url

Human Readable Output#

Authorization instructions#

  1. Click on the login URL to sign in and grant Cortex XSOAR permissions for your Azure Service Management. You will be automatically redirected to a link with the following structure: REDIRECT_URI?code=AUTH_CODE&session_state=SESSION_STATE
  2. Copy the AUTH_CODE (without the code= prefix, and the session_state parameter) and paste it in your instance configuration under the Authorization code parameter.