Skip to main content

O365 Outlook Mail (Using Graph API)

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

Microsoft Graph lets your app get authorized access to a user's Outlook mail data in a personal or organization account. This integration was integrated and tested with version v1 of Microsoft Graph.

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

  1. Navigate to Settings > Integrations > Servers & Services.

  2. Search for O365 Outlook Mail (Using Graph API).

  3. Click Add instance to create and configure a new integration instance.

    ParameterDescriptionRequired
    Server URLTrue
    Application ID or Client IDSee the Help tab.False
    Token or Tenant IDSee the Help tab.False
    Key or Client SecretSee the Help tab.False
    Certificate ThumbprintUsed 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
    Fetch incidentsWhether to fetch incidents.False
    Email address from which to fetch incidentsFor example, "example@demisto.com"False
    Name of the folder or sub-folder from which to fetch incidentsSupports folder ID and sub-folders, for example Inbox/Phishing.False
    First fetch timestamp\<number> /<time unit>, for example 12 hours, 7 days.False
    HTTP TimeoutThe timeout of the HTTP requests sent to Microsoft Graph API (in seconds).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
    ID or Client ID - see Detailed Instructions (?)False
    Token or Tenant ID - see Detailed Instructions (?)False
    Key or Client Secret (Deprecated)False
    ID or Client ID - see Detailed Instructions (?) (Deprecated)False
    Token or Tenant ID - see Detailed Instructions (?) (Deprecated)False
    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.
    Advanced: Time in minutes to look back when fetching emailsUse this parameter to determine how far backward to look in the search for incidents that were created before the last run time and did not match the query when they were created.False
  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-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
user_idUser ID from which to pull mails (can be principal ID (email address)).Required
folder_idA comma-separated list of folder IDs, in the format: (mail_box,child_mail_box,child_mail_box). .Optional
odataAn OData query. See REDAME 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_sizeLimit 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
ran_once_flagflag for rate limit retry.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 email.
MSGraphMail.IsDraftBooleanWhether the email is a draft.
MSGraphMail.BodyStringThe content (body) of the email.
MSGraphMail.Sender.NameStringThe name of 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-email#


Returns the properties of an email.

Base Command#

msgraph-mail-get-email

Input#

Argument NameDescriptionRequired
user_idUser ID or principal ID (usually an email address in the format someuser@example.com).Required
message_idThe unique ID of the mail. You cannot use the the 'MessageID' key in the form '<message-id>'.Required
folder_idThe folder ID.Optional
odataAn OData query. See the README for OData usage examples.Optional
get_bodyWhether to return the message body. Possible values are: true, false.Optional
ran_once_flagFlag for rate limit retry.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 email.
MSGraphMail.IsDraftBooleanWhether the email is a draft.
MSGraphMail.BodyStringThe content (body) of the email.
MSGraphMail.Sender.NameStringThe name of 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 users in the 'cc' field of the email.
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.

msgraph-mail-delete-email#


Deletes an email.

Base Command#

msgraph-mail-delete-email

Input#

Argument NameDescriptionRequired
user_idUser ID or principal ID (usually an email address in the format someuser@example.com).Required
message_idThe unique ID of the mail. This could be extracted from - msgraph-mail-list-emails command results. You cannot use the the 'MessageID' key in the form '<message-id>'.Required
folder_idA comma-separated list of folder IDs. For example, mailFolders,childFolders,childFolders.Optional
ran_once_flagFlag for rate limit retry.Optional

Context Output#

There is no context output for this command.

msgraph-mail-list-attachments#


Lists all of the attachments of given email

Base Command#

msgraph-mail-list-attachments

Input#

Argument NameDescriptionRequired
user_idUser ID or principal ID (usually an email address in the format someuser@example.com).Required
message_idThe unique ID of the mail. You cannot use the the 'MessageID' key in the form '<message-id>'.Required
folder_idA comma-separated list of folder IDs, in the format: (mail_box,child_mail_box,child_mail_box).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-attachment#


Gets an attachment from the email.

Base Command#

msgraph-mail-get-attachment

Input#

Argument NameDescriptionRequired
user_idUser ID or principal ID (usually an email address in the format someuser@example.com).Required
message_idThe unique ID of the mail. You cannot use the the 'MessageID' key in the form '<message-id>'.Required
folder_idA comma-separated list of folder IDs, in the format: (mail_box,child_mail_box,child_mail_box).Optional
attachment_idThe ID of the attachment. In case it is not supplied, the command will return all the attachments.Optional
ran_once_flagflag for rate limit retry.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-folders#


Returns the mail folder list directly under the root folder.

Base Command#

msgraph-mail-list-folders

Input#

Argument NameDescriptionRequired
user_idUser ID or principal ID (usually an email address in the format someuser@example.com).Required
limitThe maximum number of mail folder lists to return. Default is 20.Optional
ran_once_flagflag for rate limit retry.Optional

Context Output#

PathTypeDescription
MSGraphMail.Folders.ChildFolderCountNumberThe number of child folders.
MSGraphMail.Folders.DisplayNameStringThe folder display name.
MSGraphMail.Folders.IDStringThe target folder ID.
MSGraphMail.Folders.ParentFolderIDStringThe parent folder ID.
MSGraphMail.Folders.TotalItemCountNumberThe total number of email messages in the folder.
MSGraphMail.Folders.UnreadItemCountNumberThe number of unread emails in the folder.

msgraph-mail-list-child-folders#


Returns the folder list under the specified folder.

Base Command#

msgraph-mail-list-child-folders

Input#

Argument NameDescriptionRequired
user_idUser ID or principal ID (usually an email address in the format someuser@example.com).Required
parent_folder_idThe ID of the parent folder.Required
limitThe maximum number of mail folder lists to return. Default is 20.Optional
ran_once_flagflag for rate limit retry.Optional

Context Output#

PathTypeDescription
MSGraphMail.Folders.ChildFolderCountNumberThe number of child folders.
MSGraphMail.Folders.DisplayNameStringThe folder display name.
MSGraphMail.Folders.IDStringThe folder ID.
MSGraphMail.Folders.ParentFolderIDStringThe parent folder ID.
MSGraphMail.Folders.TotalItemCountNumberThe total number of email messages in the folder.
MSGraphMail.Folders.UnreadItemCountNumberThe number of unread email messages in the folder.

msgraph-mail-create-folder#


Creates a new folder under the specified folder (parent).

Base Command#

msgraph-mail-create-folder

Input#

Argument NameDescriptionRequired
user_idUser ID or principal ID (usually an email address in the format someuser@example.com).Required
new_folder_nameThe display name of the new folder.Required
parent_folder_idThe ID of the parent folder under which to create a new folder.Optional
ran_once_flagflag for rate limit retry.Optional

Context Output#

PathTypeDescription
MSGraphMail.Folders.ChildFolderCountNumberThe number of child folders.
MSGraphMail.Folders.DisplayNameStringThe folder display name.
MSGraphMail.Folders.IDStringThe folder ID.
MSGraphMail.Folders.ParentFolderIDStringThe parent folder ID.
MSGraphMail.Folders.TotalItemCountNumberThe total number of email messages in the folder.
MSGraphMail.Folders.UnreadItemCountNumberThe number of unread email messages in the folder.

msgraph-mail-update-folder#


Updates the properties of the specified folder.

Base Command#

msgraph-mail-update-folder

Input#

Argument NameDescriptionRequired
user_idUser ID or principal ID (usually an email address in the format someuser@example.com).Required
folder_idThe ID of the folder to update.Required
new_display_nameThe mail folder display name.Required
ran_once_flagFlag for rate limit retry.Optional

Context Output#

PathTypeDescription
MSGraphMail.Folders.ChildFolderCountStringThe number of child folders.
MSGraphMail.Folders.DisplayNameStringThe folder display name.
MSGraphMail.Folders.IDStringThe folder ID.
MSGraphMail.Folders.ParentFolderIDStringThe parent folder ID.
MSGraphMail.Folders.TotalItemCountNumberThe total number of email messages in the folder.
MSGraphMail.Folders.UnreadItemCountNumberThe unread emails count inside the folder.

msgraph-mail-delete-folder#


Deletes the specified mail folder.

Base Command#

msgraph-mail-delete-folder

Input#

Argument NameDescriptionRequired
user_idUser ID or principal ID (usually an email address in the format someuser@example.com).Required
folder_idThe ID of the folder to delete.Required
ran_once_flagFlag for rate limit retry.Optional

Context Output#

There is no context output for this command.

msgraph-mail-move-email#


Moves a message to a different folder.

Base Command#

msgraph-mail-move-email

Input#

Argument NameDescriptionRequired
message_idThe unique ID of the mail. You cannot use the the 'MessageID' key in the form '<message-id>'.Required
destination_folder_idThe ID of the destination folder.Required
user_idUser ID or principal ID (usually an email address in the format someuser@example.com).Required
ran_once_flagFlag for rate limit retry.Optional

Context Output#

PathTypeDescription
MSGraphMail.MovedEmails.DestinationFolderIDStringThe folder where the email message was moved.
MSGraphMail.MovedEmails.IDStringThe new ID of the moved email message.
MSGraphMail.MovedEmails.UserIDStringThe user ID.

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
user_idUser ID or principal ID (usually an email address in the format someuser@example.com).Required
message_idThe unique ID of the mail. You cannot use the the 'MessageID' key in the form '<message-id>'.Required
ran_once_flagFlag for rate limit retry.Optional

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-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
bodyTypeThe 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. Can be: "notFlagged", "complete", or "flagged". Possible values are: notFlagged, complete, flagged. Default is notFlagged.Optional
importanceThe importance of the draft. Can be: "Low", "Normal", or "High". 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
attachIDsA 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
attachNamesA comma-separated list of names of attachments to be displayed in the draft. Must be the same number of elements as attachIDs.Optional
attachCIDsA comma-separated list of CIDs to embed attachments within the actual email.Optional
fromThe email address from which the draft is created.Required
ran_once_flagflag for rate limit retry.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 created 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.

send-mail#


Sends an email using Microsoft Graph.

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
bodyTypeThe body type of the email. 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
attachIDsA 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
attachNamesA comma-separated list of names of attachments to display in the email to send. Must be the same number of elements as attachIDs.Optional
attachCIDsA comma-separated list of CIDs to embed attachments within the actual email.Optional
fromThe email address from which to send the email.Optional
htmlBodyThe content (body) of the email (in HTML format).Optional
replyToEmail addresses that need to be used to reply to the message. Supports comma-separated values.Optional
ran_once_flagFlag for rate limit retry.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
IDThe ID of the message.Required
bodyThe comment of the replied message.Required
toA comma-separated list of email addresses for the 'to' field.Required
fromThe email address from which to reply.Required
attachIDsA 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
attachNamesA comma-separated list of names of attachments to display in the email to send. Must be the same number of elements as attachIDs.Optional
attachCIDsA CSV list of CIDs to embed attachments within the email itself.Optional
ran_once_flagFlag for rate limit retry.Optional

Context Output#

There is no context output for this command.

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
fromThe email address from which to send the draft.Required
ran_once_flagFlag for rate limit retry.Optional

Context Output#

There is no context output for this command.

reply-mail#


Replies to an email using Graph Mail.

Base Command#

reply-mail

Input#

Argument NameDescriptionRequired
toA CSV 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 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
ccA CSV list of email addresses for the 'cc' field.Optional
bccA CSV 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 CSV list of names of attachments to send. Should be the same number of elements as attachIDs.Optional
attachCIDsA CSV list of CIDs to embed attachments within the email itself.Optional
fromEmail address of the sender.Optional
replyToEmail addresses that need to be used to reply to the message. Supports comma-separated values.Optional
ran_once_flagFlag for rate limit retry.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.
MicrosoftGraph.SentMail.replyToStringThe replyTo recipients of the email.

msgraph-mail-update-email-status#


Update the status of an email to read / unread.

Base Command#

msgraph-mail-update-email-status

Input#

Argument NameDescriptionRequired
user_idUser ID or principal ID (usually an email address. E.g., user@example.com).Required
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.