EWS O365

Exchange Web Services (EWS) provides the functionality to enable client applications to communicate with the Exchange server. EWS provides access to much of the same data that is made available through Microsoft OfficeOutlook.

The EWS O365 integration implants EWS leading services. The integration allows getting information on emails and activities in a target mailbox, and some active operations on the mailbox such as deleting emails and attachments or moving emails from folder to folder.

EWS O365 Playbook

  • Get Original Email - EWS
  • Process Email - EWS

Use Cases

The EWS integration can be used for the following use cases.

  • Monitor a specific email account and create incidents from incoming emails to the defined folder.
    Follow the instructions in the Fetched Incidents Data section.

  • Search for an email message across mailboxes and folders.
    This can be achieved in the following ways:

    1. Use the ews-search-mailbox command to search for all emails in a specific folder within the target mailbox.
      Use the query argument to narrow the search for emails sent from a specific account and more.
    • This command retrieve the ItemID field for each email item listed in the results. The ItemID can be used in the ews-get-items command in order to get more information about the email item itself.

  • Get email attachment information.
    Use the ews-get-attachment command to retrieve information on one attachment or all attachments of a message at once. It supports both file attachments and item attachments (e.g., email messages).

  • Delete email items from a mailbox.
    First, make sure you obtain the email item ID. The item ID can be obtained with one of the integration’s search commands.
    Use the ews-delete-items command to delete one or more items from the target mailbox in a single action.
    A less common use case is to remove emails that were marked as malicious from a user’s mailbox.
    You can delete the items permanently (hard delete), or delete the items (soft delete), so they can be recovered by running the ews-recover-messages command.

Configure EWS O365 on Demisto

  1. Navigate to Settings > Integrations > Servers & Services.
  2. Search for EWS O365.
  3. Click Add instance to create and configure a new integration instance.
    • Name: a textual name for the integration instance.
    • ID / Application ID: ID recieved from https://oproxy.demisto.ninja/ms-ews-o365 app registration, or a self deployed Application ID.
    • Token / Tenant ID: Token recieved from https://oproxy.demisto.ninja/ms-ews-o365 app registration, or a self deployed Application Tenant ID.
    • Key / Application Secret: Key recieved from https://oproxy.demisto.ninja/ms-ews-o365 app registration, or a self deployed Application Secret.
    • Email Address: Mailbox to run commands on, and to fetch incidents from. This argument can take various user accounts in your organization. Usually is used as phishing mailbox.
      Note: To use this functionality, your account must have impersonation rights or delegation for the account specified. For more information on impersonation rights see ‘Additional Information’ section below.
    • Name of the folder from which to fetch incidents: Supports Exchange Folder ID and sub-folders e.g. Inbox/Phishing. Please note, if Exchange is configured with an international flavor Inbox will be named according to the configured language.
    • Public Folder
    • Use system proxy settings
    • Trust any certificate (not secure)
    • Timeout (in seconds) for HTTP requests to Exchange Server
    • Use a self deployed Azure Application
  4. Click Test to validate the URLs, token, and connection.

Authentication

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

Required Permissions for self deployed Azure Application:

Exchange

  • full_access_as_app - Application

Fetched Incidents Data

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

IMPORTANT: The initial fetch interval is the previous 10 minutes. If no emails were fetched before from the destination folder- all emails from 10 minutes prior to the instance configuration and up to the current time will be fetched.

Pay special attention to the following fields in the instance settings:

Email Address – mailbox to fetch incidents from.
Name of the folder from which to fetch incidents – use this field to configure the destination folder from where emails should be fetched. The default is Inbox folder. Please note, if Exchange is configured with an international flavor Inbox will be named according to the configured language.

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. Get the attachments of an item: ews-get-attachment
  2. Delete the attachments of an item: ews-delete-attachment
  3. Get a list of searchable mailboxes: ews-get-searchable-mailboxes
  4. Move an item to a different folder: ews-move-item
  5. Delete an item from a mailbox: ews-delete-items
  6. Search a single mailbox: ews-search-mailbox
  7. Get the contacts for a mailbox: ews-get-contacts
  8. Get the out-of-office status for a mailbox: ews-get-out-of-office
  9. Recover soft-deleted messages: ews-recover-messages
  10. Create a folder: ews-create-folder
  11. Mark an item as junk: ews-mark-item-as-junk
  12. Search for folders: ews-find-folders
  13. Get items of a folder: ews-get-items-from-folder
  14. Get items: ews-get-items
  15. Move an item to a different mailbox: ews-move-item-between-mailboxes
  16. Get a folder: ews-get-folder
  17. Expand a distribution list: ews-expand-group
  18. Mark items as read: ews-mark-items-as-read
  19. Send an email: send-mail

1. Get the attachments of an item

Retrieves the actual attachments from an item (email message). To get all attachments for a message, only specify the item-id argument.

Required Permissions

Impersonation rights required. In order to perform actions on the target mailbox of other users, the service account must be part of the ApplicationImpersonation role.

Base Command

ews-get-attachment

Input
Argument NameDescriptionRequired
item-idThe ID of the email message for which to get the attachments.Required
target-mailboxThe mailbox in which this attachment was found. If empty, the default mailbox is used. Otherwise, the user might require impersonation rights to this mailbox.Optional
attachment-idsThe attachments ids to get. If none - all attachments will be retrieved from the message. Support multiple attachments with comma-separated value or array.Optional
Context Output
PathTypeDescription
EWS.Items.FileAttachments.attachmentIdstringThe attachment ID. Used for file attachments only.
EWS.Items.FileAttachments.attachmentNamestringThe attachment name. Used for file attachments only.
EWS.Items.FileAttachments.attachmentSHA256stringThe SHA256 hash of the attached file.
EWS.Items.FileAttachments.attachmentLastModifiedTimedateThe attachment last modified time. Used for file attachments only.
EWS.Items.ItemAttachments.datetimeCreateddateThe created time of the attached email.
EWS.Items.ItemAttachments.datetimeReceiveddateThe received time of the attached email.
EWS.Items.ItemAttachments.datetimeSentdateThe sent time of the attached email.
EWS.Items.ItemAttachments.receivedBystringThe received by address of the attached email.
EWS.Items.ItemAttachments.subjectstringThe subject of the attached email.
EWS.Items.ItemAttachments.textBodystringThe body of the attached email (as text).
EWS.Items.ItemAttachments.headersUnknownThe headers of the attached email.
EWS.Items.ItemAttachments.hasAttachmentsbooleanWhether the attached email has attachments.
EWS.Items.ItemAttachments.itemIdstringThe attached email item ID.
EWS.Items.ItemAttachments.toRecipientsUnknownA list of recipient email addresses for the attached email.
EWS.Items.ItemAttachments.bodystringThe body of the attached email (as HTML).
EWS.Items.ItemAttachments.attachmentSHA256stringSHA256 hash of the attached email (as EML file).
EWS.Items.ItemAttachments.FileAttachments.attachmentSHA256stringSHA256 hash of the attached files inside of the attached email.
EWS.Items.ItemAttachments.ItemAttachments.attachmentSHA256stringSHA256 hash of the attached emails inside of the attached email.
EWS.Items.ItemAttachments.isReadStringThe read status of the attachment.
Command Example
!ews-get-attachment item-id=BBFDShfdafFSDF3FADR3434DFASDFADAFDADFADFCJebinpkUAAAfxuiVAAA= target-mailbox=test@demistodev.onmicrosoft.com
Context Example
{
"EWS": {
"Items": {
"ItemAttachments": {
"originalItemId": "BBFDShfdafFSDF3FADR3434DFASDFADAFDADFADFCJebinpkUAAAfxuiVAAA=",
"attachmentSize": 2956,
"receivedBy": "test@demistodev.onmicrosoft.com",
"size": 28852,
"author": "test2@demistodev.onmicrosoft.com",
"attachmentLastModifiedTime": "2019-08-11T15:01:30+00:00",
"subject": "Moving Email between mailboxes",
"body": "Some text inside",
"datetimeCreated": "2019-08-11T15:01:47Z",
"importance": "Normal",
"attachmentType": "ItemAttachment",
"toRecipients": [
"test@demistodev.onmicrosoft.com"
],
"mailbox": "test@demistodev.onmicrosoft.com",
"isRead": false,
"attachmentIsInline": false,
"datetimeSent": "2019-08-07T12:50:19Z",
"lastModifiedTime": "2019-08-11T15:01:30Z",
"sender": "test2@demistodev.onmicrosoft.com",
"attachmentName": "Moving Email between mailboxes",
"datetimeReceived": "2019-08-07T12:50:20Z",
"attachmentSHA256": "119e27b28dc81bdfd4f498d44bd7a6d553a74ee03bdc83e6255a53",
"hasAttachments": false,
"headers": [
{
"name": "Subject",
"value": "Moving Email between mailboxes"
}
...
],
"attachmentId": "BBFDShfdafFSDF3FADR3434DFASDFADAFDADFADFCJebinpkUAAAfxuiVAAABEgAQAOpEfpzDB4dFkZ+/K4XSj44=",
"messageId": "message_id"
}
}
}

2. Delete the attachments of an item

Deletes the attachments of an item (email message).

Required Permissions

Impersonation rights required. In order to perform actions on the target mailbox of other users, the service account must be part of the ApplicationImpersonation role.

Base Command

ews-delete-attachment

Input
Argument NameDescriptionRequired
item-idThe ID of the email message for which to delete attachments.Required
target-mailboxThe mailbox in which this attachment was found. If empty, the default mailbox is used. Otherwise, the user might require impersonation rights to this mailbox.Optional
attachment-idsA CSV list (or array) of attachment IDs to delete. If empty, all attachments will be deleted from the message.Optional
Context Output
PathTypeDescription
EWS.Items.FileAttachments.attachmentIdstringThe ID of the deleted attachment, in case of file attachment.
EWS.Items.ItemAttachments.attachmentIdstringThe ID of the deleted attachment, in case of other attachment (for example, "email").
EWS.Items.FileAttachments.actionstringThe deletion action in case of file attachment. This is a constant value: 'deleted'.
EWS.Items.ItemAttachments.actionstringThe deletion action in case of other attachment (for example, "email"). This is a constant value: 'deleted'.
Command Example
!ews-delete-attachment item-id=AAMkADQ0NmwBGAAAAAAA4kxh+ed3JTJPMPXU3wX3aBwCyyVyFtlsUQZfBJjfaljfAFDVSDinpkUAAAfxxd9AAA= target-mailbox=test@demistodev.onmicrosoft.com
Human Readable Output
actionattachmentId
deletedAAMkADQ0NmwBGAAAAAAA4kxh+ed3JTJPMPXU3wX3aBwCyyVyFtlsUQZfBJjfaljfAFDVSDinpkUAAAfxxd9AAABEgAQAIUht2vrOdErec33=

Context Example

{
"EWS": {
"Items": {
"FileAttachments": {
"action": "deleted",
"attachmentId": "AAMkADQ0NmwBGAAAAAAA4kxh+ed3JTJPMPXU3wX3aBwCyyVyFtlsUQZfBJjfaljfAFDVSDinpkUAAAfxxd9AAABEgAQAIUht2vrOdErec33="
}
}
}
}

3. Get a list of searchable mailboxes

Returns a list of searchable mailboxes.

Required Permissions

Requires eDiscovery permissions to the Exchange Server. For more information see the Microsoft documentation.

Base Command

ews-get-searchable-mailboxes

Input

There are no input arguments for this command.

Context Output
PathTypeDescription
EWS.Mailboxes.mailboxstringAddresses of the searchable mailboxes.
EWS.Mailboxes.mailboxIdstringIDs of the searchable mailboxes.
EWS.Mailboxes.displayNamestringThe email display name.
EWS.Mailboxes.isExternalbooleanWhether the mailbox is external.
EWS.Mailboxes.externalEmailAddressstringThe external email address.
Command Example
!ews-get-searchable-mailboxes
Human Readable Output
displayNameisExternalmailboxmailboxId
testfalsetest@demistodev.onmicrosoft.com/o=Exchange*/ou=Exchange Administrative Group ()/cn=/cn=-
Context Example
{
"EWS": {
"Mailboxes": [
{
"mailbox": "test@demistodev.onmicrosoft.com",
"displayName": "test",
"mailboxId": "/o=Exchange***/ou=Exchange Administrative Group ()/cn=**/cn=**-**",
"isExternal": "false"
}
...
]
}
}

4. Move an item to a different folder

Move an item to a different folder in the mailbox.

Required Permissions

Impersonation rights required. In order to perform actions on the target mailbox of other users, the service account must be part of the ApplicationImpersonation role.

Base Command

ews-move-item

Input
Argument NameDescriptionRequired
item-idThe ID of the item to move.Required
target-folder-pathThe path to the folder to which to move the item. Complex paths are supported, for example, "Inbox\Phishing".Required
target-mailboxThe mailbox on which to run the command.Optional
is-publicWhether the target folder is a public folder.Optional
Context Output
PathTypeDescription
EWS.Items.newItemIDstringThe item ID after the move.
EWS.Items.messageIDstringThe item message ID.
EWS.Items.itemIdstringThe original item ID.
EWS.Items.actionstringThe action taken. The value will be "moved".
Command Example
!ews-move-item item-id=VDAFNTZjNTMxNwBGAAAAAAA4kxh+ed3JTJPMPXU34cSCSSSfBJebinpkUAAAAAAEMAACyyVyFtlsUQZfBJebinpkUAAAfxuiRAAA= target-folder-path=Moving target-mailbox=test@demistodev.onmicrosoft.com
Human Readable Output
actionitemIdmessageIdnewItemId
movedVDAFNTZjNTMxNwBGAAAAAAA4kxh+ed3JTJPMPXU34cSCSSSfBJebinpkUAAAAAAEMAACyyVyFtlsUQZfBJebinpkUAAAfxuiRAAAAAVAAAVN2NkLThmZjdmNTZjNTMxFFFFJTJPMPXU3wX3aBwCyyVyFtlsUQZfBJebinpkUAAAa2bUBAACyyVfafainpkUAAAfxxd+AAA=
Context Example
{
"EWS": {
"Items": {
"action": "moved",
"itemId": "VDAFNTZjNTMxNwBGAAAAAAA4kxh+ed3JTJPMPXU34cSCSSSfBJebinpkUAAAAAAEMAACyyVyFtlsUQZfBJebinpkUAAAfxuiRAAA",
"newItemId": "AAVAAAVN2NkLThmZjdmNTZjNTMxFFFFJTJPMPXU3wX3aBwCyyVyFtlsUQZfBJebinpkUAAAa2bUBAACyyVfafainpkUAAAfxxd+AAA=",
"messageId": "<message_id>"
}
}
}

5. Delete an item from a mailbox

Delete items from mailbox.

Required Permissions

Impersonation rights required. In order to perform actions on the target mailbox of other users, the service account must be part of the ApplicationImpersonation role.

Base Command

ews-delete-items

Input
Argument NameDescriptionRequired
item-idsThe item IDs to delete.Required
delete-typeDeletion type. Can be "trash", "soft", or "hard".Required
target-mailboxThe mailbox on which to run the command.Optional
Context Output
PathTypeDescription
EWS.Items.itemIdstringThe deleted item ID.
EWS.Items.messageIdstringThe deleted message ID.
EWS.Items.actionstringThe deletion action. Can be 'trash-deleted', 'soft-deleted', or 'hard-deleted'.
Command Example
!ews-delete-items item-ids=VWAFA3hmZjdmNTZjNTMxNwBGAAAAAAA4kxh+ed3JTJPMPXU3wX3aBwCyyVyFtlsUQZfBJebinpkUAAABjKMGAACyw+kAAA= delete-type=soft target-mailbox=test@demistodev.onmicrosoft.com
Human Readable Output
actionitemIdmessageId
soft-deletedVWAFA3hmZjdmNTZjNTMxNwBGAAAAAAA4kxh+ed3JTJPMPXU3wX3aBwCyyVyFtlsUQZfBJebinpkUAAABjKMGAACyw+kAAA=
Context Example
{
"EWS": {
"Items": {
"action": "soft-deleted",
"itemId": "VWAFA3hmZjdmNTZjNTMxNwBGAAAAAAA4kxh+ed3JTJPMPXU3wX3aBwCyyVyFtlsUQZfBJebinpkUAAABjKMGAACyw+kAAA=",
"messageId": "messaage_id"
}
}
}

6. Search a single mailbox

Searches for items in the specified mailbox. Specific permissions are needed for this operation to search in a target mailbox other than the default.

Required Permissions

Impersonation rights required. To perform actions on the target mailbox of other users, the service account must be part of the ApplicationImpersonation role.

Base Command

ews-search-mailbox

Input
Argument NameDescriptionRequired
queryThe search query string. For more information about the query syntax, see the Microsoft documentation.Optional
folder-pathThe folder path in which to search. If empty, searches all the folders in the mailbox.Optional
limitMaximum number of results to return.Optional
target-mailboxThe mailbox on which to apply the search.Optional
is-publicWhether the folder is a Public Folder?Optional
message-idThe message ID of the email. This will be ignored if a query argument is provided.Optional
Context Output
PathTypeDescription
EWS.Items.itemIdstringThe email item ID.
EWS.Items.hasAttachmentsbooleanWhether the email has attachments.
EWS.Items.datetimeReceiveddateReceived time of the email.
EWS.Items.datetimeSentdateSent time of the email.
EWS.Items.headersUnknownEmail headers (list).
EWS.Items.senderstringSender email address of the email.
EWS.Items.subjectstringSubject of the email.
EWS.Items.textBodystringBody of the email (as text).
EWS.Items.sizenumberEmail size.
EWS.Items.toRecipientsUnknownList of email recipients addresses.
EWS.Items.receivedByUnknownEmail received by address.
EWS.Items.messageIdstringEmail message ID.
EWS.Items.bodystringBody of the email (as HTML).
EWS.Items.FileAttachments.attachmentIdunknownAttachment ID of the file attachment.
EWS.Items.ItemAttachments.attachmentIdunknownAttachment ID of the item attachment.
EWS.Items.FileAttachments.attachmentNameunknownAttachment name of the file attachment.
EWS.Items.ItemAttachments.attachmentNameunknownAttachment name of the item attachment.
EWS.Items.isReadStringThe read status of the email.
Command Example
!ews-search-mailbox query="subject:"Get Attachment Email" target-mailbox=test@demistodev.onmicrosoft.com limit=1
Human Readable Output
sendersubjecthasAttachmentsdatetimeReceivedreceivedByauthortoRecipients
test2@demistodev.onmicrosoft.comGet Attachment Emailtrue2019-08-11T10:57:37Ztest@demistodev.onmicrosoft.comtest2@demistodev.onmicrosoft.comtest@demistodev.onmicrosoft.com
Context Example
{
"EWS": {
"Items": {
"body": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r\n<style type=\"text/css\" style=\"display:none;\"></style>\r\n</head>\r\n<body dir=\"ltr\">\r\n<div id=\"divtagrapper\" style=\"font-size:12pt;color:#000000;font-family:Calibri,Helvetica,sans-serif;\" dir=\"ltr\">\r\n<p style=\"margin-top:0;margin-bottom:0\">Some text inside email</p>\r\n</div>\r\n</body>\r\n</html>\r\n",
"itemId": "AAMkADQ0NmFFijer3FFmNTZjNTMxNwBGAAAAAAFSAAfxw+jAAA=",
"toRecipients": [
"test@demistodev.onmicrosoft.com"
],
"datetimeCreated": "2019-08-11T10:57:37Z",
"datetimeReceived": "2019-08-11T10:57:37Z",
"author": "test2@demistodev.onmicrosoft.com",
"hasAttachments": true,
"size": 30455,
"subject": "Get Attachment Email",
"FileAttachments": [
{
"attachmentName": "atta1.rtf",
"attachmentSHA256": "csfd81097bc049fbcff6e637ade0407a00308bfdfa339e31a44a1c4e98f28ce36e4f",
"attachmentType": "FileAttachment",
"attachmentSize": 555,
"attachmentId": "AAMkADQ0NmFkODFkLWQ4MDEtNDE4Mi1hN2NkLThmZjdmNTZjNTMxNwBGAAAAAAA4kxh+ed3JTJPMPXU3wX3aBwCyyVyFtlsUQZfBJebinpkUAAABjKMGAACyyVyFtlsUQZfBJebinpkUAAAfxw+jAAABEgAQAEyq1TB2nKBLpKUiFUJ5Geg=",
"attachmentIsInline": false,
"attachmentLastModifiedTime": "2019-08-11T11:06:02+00:00",
"attachmentContentLocation": null,
"attachmentContentType": "text/rtf",
"originalItemId": "AAMkADQ0NmFFijer3FFmNTZjNTMxNwBGAAAAAAFSAAfxw+jAAA=",
"attachmentContentId": null
}
],
"headers": [
{
"name": "Subject",
"value": "Get Attachment Email"
},
...
],
"isRead": true,
"messageId": "<mesage_id>",
"receivedBy": "test@demistodev.onmicrosoft.com",
"datetimeSent": "2019-08-11T10:57:36Z",
"lastModifiedTime": "2019-08-11T11:13:59Z",
"mailbox": "test@demistodev.onmicrosoft.com",
"importance": "Normal",
"textBody": "Some text inside email\r\n",
"sender": "test2@demistodev.onmicrosoft.com"
}
}
}

7. Get the contacts for a mailbox

Retrieves contacts for a specified mailbox.

Required Permissions

Impersonation rights required. In order to perform actions on the target mailbox of other users, the service account must be part of the ApplicationImpersonation role.

Base Command

ews-get-contacts

Input
Argument NameDescriptionRequired
target-mailboxThe mailbox for which to retrieve the contacts.Optional
limitMaximum number of results to return.Optional
Context Output
PathTypeDescription
Account.Email.EwsContacts.displayNameUnknownThe contact name.
Account.Email.EwsContacts.lastModifiedTimeUnknownThe time that the contact was last modified.
Account.Email.EwsContacts.emailAddressesUnknownPhone numbers of the contact.
Account.Email.EwsContacts.physicalAddressesUnknownPhysical addresses of the contact.
Account.Email.EwsContacts.phoneNumbers.phoneNumberUnknownEmail addresses of the contact.
Command Example
!ews-get-contacts limit="1"
Human Readable Output
changekeyculturedatetimeCreateddatetimeReceiveddatetimeSentdisplayNameemailAddressesfileAsfileAsMappinggivenNameidimportanceitemClasslastModifiedNamelastModifiedTimepostalAddressIndexsensitivitysubjectuniqueBodywebClientReadFormQueryString
EABYACAADcsxRwRjq/zTrN6vWSzKAK1Dl3Nen-US2019-08-05T12:35:36Z2019-08-05T12:35:36Z2019-08-05T12:35:36ZContact Namesome@dev.microsoft.comContact NameLastCommaFirstContact NameAHSNNK3NQNcasnc3SAS/zTrN6vWSzK4OWAAAAAAEOAADrxRwRjq/zTrNFSsfsfVWAAK1KsF3AAA=NormalIPM.ContactJohn Smith2019-08-05T12:35:36ZNoneNormalContact Namehttps://outlook.office365.com/owa/?ItemID=***
Context Example
{
"Account.Email": [
{
"itemClass": "IPM.Contact",
"lastModifiedName": "John Smith",
"displayName": "Contact Name",
"datetimeCreated": "2019-08-05T12:35:36Z",
"datetimeReceived": "2019-08-05T12:35:36Z",
"fileAsMapping": "LastCommaFirst",
"importance": "Normal",
"sensitivity": "Normal",
"postalAddressIndex": "None",
"webClientReadFormQueryString": "https://outlook.office365.com/owa/?ItemID=***",
"uniqueBody": "<html><body></body></html>",
"fileAs": "Contact Name",
"culture": "en-US",
"changekey": "EABYACAADcsxRwRjq/zTrN6vWSzKAK1Dl3N",
"lastModifiedTime": "2019-08-05T12:35:36Z",
"datetimeSent": "2019-08-05T12:35:36Z",
"emailAddresses": [
"some@dev.microsoft.com"
],
"givenName": "Contact Name",
"id": "AHSNNK3NQNcasnc3SAS/zTrN6vWSzK4OWAAAAAAEOAADrxRwRjq/zTrNFSsfsfVWAAK1KsF3AAA=",
"subject": "Contact Name"
}
]
}

8. Get the out-of-office status for a mailbox

Retrieves the out-of-office status for a specified mailbox.

Required Permissions

Impersonation rights are required. To perform actions on the target mailbox of other users, the service account must be part the ApplicationImpersonation role.

Base Command

ews-get-out-of-office

Input
Argument NameDescriptionRequired
target-mailboxThe mailbox for which to get the out-of-office status.Required
Context Output
PathTypeDescription
Account.Email.OutOfOffice.stateUnknownOut-of-office state. The result can be: "Enabled", "Scheduled", or "Disabled".
Account.Email.OutOfOffice.externalAudienceUnknownOut-of-office external audience. Can be "None", "Known", or "All".
Account.Email.OutOfOffice.startUnknownOut-of-office start date.
Account.Email.OutOfOffice.endUnknownOut-of-office end date.
Account.Email.OutOfOffice.internalReplyUnknownOut-of-office internal reply.
Account.Email.OutOfOffice.externalReplyUnknownOut-of-office external reply.
Account.Email.OutOfOffice.mailboxUnknownOut-of-office mailbox.
Command Example
!ews-get-out-of-office target-mailbox=test@demistodev.onmicrosoft.com
Human Readable Output
endexternalAudiencemailboxstartstate
2019-08-12T13:00:00ZAlltest@demistodev.onmicrosoft.com2019-08-11T13:00:00ZDisabled
Context Example
{
"Account": {
"Email": {
"OutOfOffice": {
"start": "2019-08-11T13:00:00Z",
"state": "Disabled",
"mailbox": "test@demistodev.onmicrosoft.com",
"end": "2019-08-12T13:00:00Z",
"externalAudience": "All"
}
}
}
}

9. Recover soft-deleted messages

Recovers messages that were soft-deleted.

Required Permissions

Impersonation rights are required. To perform actions on the target mailbox of other users, the service account must be part of the ApplicationImpersonation role.

Base Command

ews-recover-messages

Input
Argument NameDescriptionRequired
message-idsA CSV list of message IDs. Run the py-ews-delete-items command to retrieve the message IDsRequired
target-folder-pathThe folder path to recover the messages to.Required
target-mailboxThe mailbox in which the messages found. If empty, will use the default mailbox. If you specify a different mailbox, you might need impersonation rights to the mailbox.Optional
is-publicWhether the target folder is a Public Folder.Optional
Context Output
PathTypeDescription
EWS.Items.itemIdUnknownThe item ID of the recovered item.
EWS.Items.messageIdUnknownThe message ID of the recovered item.
EWS.Items.actionUnknownThe action taken on the item. The value will be 'recovered'.
Command Example
!ews-recover-messages message-ids=<DFVDFmvsCSCS.com> target-folder-path=Moving target-mailbox=test@demistodev.onmicrosoft.com
Human Readable Output
actionitemIdmessageId
recoveredAAVCSVS1hN2NkLThmZjdmNTZjNTMxNwBGAAAAAAA4kxh+ed33wX3aBwCyyVyFtlsUQZfBJebinpkUAAAa2bUBAACyyVyFtlscfxxd/AAA=
Context Example
{
"EWS": {
"Items": {
"action": "recovered",
"itemId": "AAVCSVS1hN2NkLThmZjdmNTZjNTMxNwBGAAAAAAA4kxh+ed33wX3aBwCyyVyFtlsUQZfBJebinpkUAAAa2bUBAACyyVyFtlscfxxd/AAA=",
"messageId": "<DFVDFmvsCSCS.com>"
}
}
}

10. Create a folder

Creates a new folder in a specified mailbox.

Required Permissions

Impersonation rights are required. To perform actions on the target mailbox of other users, the service account must be part of the ApplicationImpersonation role.

Base Command

ews-create-folder

Input
Argument NameDescriptionRequired
new-folder-nameThe name of the new folder.Required
folder-pathPath to locate the new folder. Exchange folder ID is also supported.Required
target-mailboxThe mailbox in which to create the folder.Optional
Context Output

There is no context output for this command.

Command Example
!ews-create-folder folder-path=Inbox new-folder-name="Created Folder" target-mailbox=test@demistodev.onmicrosoft.com
Human Readable Output

Folder Inbox\Created Folder created successfully

11. Mark an item as junk

Marks an item as junk. This is commonly used to block an email address. For more information, see the Microsoft documentation.

Required Permissions

Impersonation rights are required. To perform actions on the target mailbox of other users, the service account must be part of the ApplicationImpersonation role.

Base Command

ews-mark-item-as-junk

Input
Argument NameDescriptionRequired
item-idThe item ID to mark as junk.Required
move-itemsWhether to move the item from the original folder to the junk folder.Optional
target-mailboxIf empty, will use the default mailbox. If you specify a different mailbox, you might need impersonation rights to the mailbox.Optional
Context Output

There is no context output for this command.

Command Example
!ews-mark-item-as-junk item-id=AAMkcSQ0NmFkOhmZjdmNTZjNTMxNwBGAAAAAAA4kxh+ed3JTJPMPXU3wX3aBwCyyVyFtlsUcsBJebinpkUAAAAAAEMASFDkUAAAfxuiSAAA= move-items=yes target-mailbox=test@demistodev.onmicrosoft.com
Human Readable Output
actionitemId
marked-as-junkAAMkcSQ0NmFkOhmZjdmNTZjNTMxNwBGAAAAAAA4kxh+ed3JTJPMPXU3wX3aBwCyyVyFtlsUcsBJebinpkUAAAAAAEMASFDkUAAAfxuiSAAA=
Context Example
{
"EWS": {
"Items": {
"action": "marked-as-junk",
"itemId": "AAMkcSQ0NmFkOhmZjdmNTZjNTMxNwBGAAAAAAA4kxh+ed3JTJPMPXU3wX3aBwCyyVyFtlsUcsBJebinpkUAAAAAAEMASFDkUAAAfxuiSAAA="
}
}
}

12. Search for folders

Retrieves information for the folders of the specified mailbox. Only folders with read permissions will be returned. Your visual folders on the mailbox, such as "Inbox", are under the folder "Top of Information Store".

Required Permissions

Impersonation rights are required. To perform actions on the target mailbox of other users, the service account must be part of the ApplicationImpersonation role.

Base Command

ews-find-folders

Input
Argument NameDescriptionRequired
target-mailboxThe mailbox on which to apply the command.Optional
is-publicWhether to find Public Folders.Optional
Context Output
PathTypeDescription
EWS.Folders.namestringFolder name.
EWS.Folders.idstringFolder ID.
EWS.Folders.totalCountUnknownNumber of items in the folder.
EWS.Folders.unreadCountnumberNumber of unread items in the folder.
EWS.Folders.changeKeynumberFolder change key.
EWS.Folders.childrenFolderCountnumberNumber of sub-folders.
Command Example
!ews-find-folders target-mailbox=test@demistodev.onmicrosoft.com
Human Readable Output
root
├── AllContacts
├── AllItems
├── Common Views
├── Deferred Action
├── ExchangeSyncData
├── Favorites
├── Freebusy Data
├── Location
├── MailboxAssociations
├── My Contacts
├── MyContactsExtended
├── People I Know
├── PeopleConnect
├── Recoverable Items
│ ├── Calendar Logging
│ ├── Deletions
│ ── Purges
│ └── Versions
├── Reminders
├── Schedule
├── Sharing
├── Shortcuts
├── Spooler Queue
├── System
├── To-Do Search
├── Top of Information Store
│ ├── Calendar
│ ├── Contacts
│ │ ├── GAL Contacts
│ │ ├── Recipient Cache
│ ├── Conversation Action Settings
│ ├── Deleted Items
│ │ └── Create1
│ ├── Drafts
│ ├── Inbox
...
Context Example
{
"EWS": {
"Folders": [
{
"unreadCount": 1,
"name": "Inbox",
"childrenFolderCount": 1,
"totalCount": 44,
"changeKey": "**********fefsduQi0",
"id": "*******VyFtlFDSAFDSFDAAA="
}
...
]
}
}

13. Get items of a folder

Retrieves items from a specified folder in a mailbox. The items are ordered by the item created time, most recent is first.

Required Permissions

Impersonation rights are required. To perform actions on the target mailbox of other users, the service account must be part of the ApplicationImpersonation role.

Base Command

ews-get-items-from-folder

Input
Argument NameDescriptionRequired
folder-pathThe folder path from which to get the items.Required
limitMaximum number of items to return.Optional
target-mailboxThe mailbox on which to apply the command.Optional
is-publicWhether the folder is a Public Folder. Default is 'False'.Optional
get-internal-itemsIf the email item contains another email as an attachment (EML or MSG file), whether to retrieve the EML/MSG file attachment. Can be "yes" or "no". Default is "no".Optional
Context Output
PathTypeDescription
EWS.Items.itemIdstringThe item ID of the email.
EWS.Items.hasAttachmentsbooleanWhether the email has attachments.
EWS.Items.datetimeReceiveddateReceived time of the email.
EWS.Items.datetimeSentdateSent time of the email.
EWS.Items.headersUnknownEmail headers (list).
EWS.Items.senderstringSender mail address of the email.
EWS.Items.subjectstringSubject of the email.
EWS.Items.textBodystringBody of the email (as text).
EWS.Items.sizenumberEmail size.
EWS.Items.toRecipientsUnknownEmail recipients addresses (list).
EWS.Items.receivedByUnknownReceived by address of the email.
EWS.Items.messageIdstringEmail message ID.
EWS.Items.bodystringBody of the email (as HTML).
EWS.Items.FileAttachments.attachmentIdunknownAttachment ID of file attachment.
EWS.Items.ItemAttachments.attachmentIdunknownAttachment ID of the item attachment.
EWS.Items.FileAttachments.attachmentNameunknownAttachment name of the file attachment.
EWS.Items.ItemAttachments.attachmentNameunknownAttachment name of the item attachment.
Email.Items.ItemAttachments.attachmentNameunknownAttachment name of the item attachment.
EWS.Items.isReadStringThe read status of the email.
Command Example
!ews-get-items-from-folder folder-path=Test target-mailbox=test@demistodev.onmicrosoft.com limit=1
Human Readable Output
sendersubjecthasAttachmentsdatetimeReceivedreceivedByauthortoRecipientsitemId
test2@demistodev.onmicrosoft.comGet Attachment Emailtrue2019-08-11T10:57:37Ztest@demistodev.onmicrosoft.comtest2@demistodev.onmicrosoft.comtest@demistodev.onmicrosoft.comAAFSFSFFtlsUQZfBJebinpkUAAABjKMGAACyyVyFtlsUQZfBJebinpkUAAAsfw+jAAA=
Context Example
{
"EWS": {
"Items": {
"body": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r\n<style type=\"text/css\" style=\"display:none;\"></style>\r\n</head>\r\n<body dir=\"ltr\">\r\n<div id=\"divtagdefaultwrapper\" style=\"font-size:12pt;color:#000000;font-family:Calibri,Helvetica,sans-serif;\" dir=\"ltr\">\r\n<p style=\"margin-top:0;margin-bottom:0\">Some text inside email</p>\r\n</div>\r\n</body>\r\n</html>\r\n",
"itemId": "AAFSFSFFtlsUQZfBJebinpkUAAABjKMGAACyyVyFtlsUQZfBJebinpkUAAAsfw+jAAA=",
"toRecipients": [
"test@demistodev.onmicrosoft.com"
],
"datetimeCreated": "2019-08-11T10:57:37Z",
"datetimeReceived": "2019-08-11T10:57:37Z",
"author": "test2@demistodev.onmicrosoft.com",
"hasAttachments": true,
"size": 21435,
"subject": "Get Attachment Email",
"FileAttachments": [
{
"attachmentName": "atta1.rtf",
"attachmentSHA256": "cd81097bcvdiojf3407a00308b48039e31a44a1c4fdnfkdknce36e4f",
"attachmentType": "FileAttachment",
"attachmentSize": 535,
"attachmentId": "AAFSFSFFtlsUQZfBJebinpkUAAABjKMGAACyyVyFtlsUQZfBJebinpkUAAAsfw+jAAABEgAQAEyq1TB2nKBLpKUiFUJ5Geg=",
"attachmentIsInline": false,
"attachmentLastModifiedTime": "2019-08-11T11:06:02+00:00",
"attachmentContentLocation": null,
"attachmentContentType": "text/rtf",
"originalItemId": "AAFSFSFFtlsUQZfBJebinpkUAAABjKMGAACyyVyFtlsUQZfBJebinpkUAAAsfw+jAAA=",
"attachmentContentId": null
}
],
"headers": [
{
"name": "Subject",
"value": "Get Attachment Email"
},
...
],
"isRead": true,
"messageId": "<message_id>",
"receivedBy": "test@demistodev.onmicrosoft.com",
"datetimeSent": "2019-08-11T10:57:36Z",
"lastModifiedTime": "2019-08-11T11:13:59Z",
"mailbox": "test@demistodev.onmicrosoft.com",
"importance": "Normal",
"textBody": "Some text inside email\r\n",
"sender": "test2@demistodev.onmicrosoft.com"
}
}
}

14. Get items

Retrieves items by item ID.

Required Permissions

Impersonation rights are required. To perform actions on the target mailbox of other users, the service account must be part of the ApplicationImpersonation role.

Base Command

ews-get-items

Input
Argument NameDescriptionRequired
item-idsA CSV list of item IDs.Required
target-mailboxThe mailbox on which to run the command on.Optional
Context Output
PathTypeDescription
EWS.Items.itemIdstringThe email item ID.
EWS.Items.hasAttachmentsbooleanWhether the email has attachments.
EWS.Items.datetimeReceiveddateReceived time of the email.
EWS.Items.datetimeSentdateSent time of the email.
EWS.Items.headersUnknownEmail headers (list).
EWS.Items.senderstringSender mail address of the email.
EWS.Items.subjectstringSubject of the email.
EWS.Items.textBodystringBody of the email (as text).
EWS.Items.sizenumberEmail size.
EWS.Items.toRecipientsUnknownEmail recipients addresses (list).
EWS.Items.receivedByUnknownReceived by address of the email.
EWS.Items.messageIdstringEmail message ID.
EWS.Items.bodystringBody of the email (as HTML).
EWS.Items.FileAttachments.attachmentIdunknownAttachment ID of the file attachment.
EWS.Items.ItemAttachments.attachmentIdunknownAttachment ID of the item attachment.
EWS.Items.FileAttachments.attachmentNameunknownAttachment name of the file attachment.
EWS.Items.ItemAttachments.attachmentNameunknownAttachment name of the item attachment.
EWS.Items.isReadStringThe read status of the email.
Email.CCStringEmail addresses CC'ed to the email.
Email.BCCStringEmail addresses BCC'ed to the email.
Email.ToStringThe recipient of the email.
Email.FromStringThe sender of the email.
Email.SubjectStringThe subject of the email.
Email.TextStringThe plain-text version of the email.
Email.HTMLStringThe HTML version of the email.
Email.HeadersMapStringThe headers of the email.
Command Example
!ews-get-items item-ids=AAMkADQ0NmFkODFkLWQ4MDEtNDFDFZjNTMxNwBGAAAAAAA4kxhFFAfxw+jAAA= target-mailbox=test@demistodev.onmicrosoft.com
Human Readable Output

Identical outputs to ews-get-items-from-folder command.

15. Move an item to a different mailbox

Moves an item from one mailbox to a different mailbox.

Required Permissions

Impersonation rights are required. To perform actions on the target mailbox of other users, the service account must be part of the ApplicationImpersonation role.

Base Command

ews-move-item-between-mailboxes

Input
Argument NameDescriptionRequired
item-idThe item ID to move.Required
destination-folder-pathThe folder in the destination mailbox to which to move the item. You can specify a complex path, for example, "Inbox\Phishing".Required
destination-mailboxThe mailbox to which to move the item.Required
source-mailboxThe mailbox from which to move the item (conventionally called the "target-mailbox", the target mailbox on which to run the command).Optional
is-publicWhether the destination folder is a Public Folder. Default is "False".Optional
Context Output
PathTypeDescription
EWS.Items.movedToMailboxstringThe mailbox to which the item was moved.
EWS.Items.movedToFolderstringThe folder to which the item was moved.
EWS.Items.actionstringThe action taken on the item. The value will be "moved".
Command Example
!ews-move-item-between-mailboxes item-id=AAMkAGY3OTQyMzMzLWYxNjktNDE0My05NFSFSyNzBkNABGAAAAAACYCKjWAjq/zTrN6vWSzK4OWAAK2ISFSA= destination-folder-path=Moving destination-mailbox=test@demistodev.onmicrosoft.com source-mailbox=test2@demistodev.onmicrosoft.com
Human Readable Output

Item was moved successfully.

Context Example
{
"EWS": {
"Items": {
"movedToMailbox": "test@demistodev.onmicrosoft.com",
"movedToFolder": "Moving"
}
}
}

16. Get a folder

Retrieves a single folder.

Required Permissions

Impersonation rights are required. To perform actions on the target mailbox of other users, the service account must be part of the ApplicationImpersonation role.

Base Command

ews-get-folder

Input
Argument NameDescriptionRequired
target-mailboxThe mailbox on which to apply the search.Optional
folder-pathThe path of the folder to retrieve. If empty, will retrieve the folder "AllItems".Optional
is-publicWhether the folder is a Public Folder. Default is "False".Optional
Context Output
PathTypeDescription
EWS.Folders.idstringFolder ID.
EWS.Folders.namestringFolder name.
EWS.Folders.changeKeystringFolder change key.
EWS.Folders.totalCountnumberTotal number of emails in the folder.
EWS.Folders.childrenFolderCountnumberNumber of sub-folders.
EWS.Folders.unreadCountnumberNumber of unread emails in the folder.
Command Example
!ews-get-folder folder-path=demistoEmail target-mailbox=test@demistodev.onmicrosoft.com
Human Readable Output
changeKeychildrenFolderCountidnametotalCountunreadCount
***yFtCdJSH0AAMkADQ0NmFkODFkLWQ4MDEtNDE4Mi1hN2NlsjflsjfSF=demistoEmail10
Context Example
{
"EWS": {
"Folders": {
"unreadCount": 0,
"name": "demistoEmail",
"childrenFolderCount": 0,
"totalCount": 1,
"changeKey": "***yFtCdJSH",
"id": "AAMkADQ0NmFkODFkLWQ4MDEtNDE4Mi1hN2NlsjflsjfSF="
}
}
}

17. Expand a distribution list

Expands a distribution list to display all members. By default, expands only the first layer of the distribution list. If recursive-expansion is "True", the command expands nested distribution lists and returns all members.

Required Permissions

Impersonation rights required. In order to perform actions on the target mailbox of other users, the service account must be part of the ApplicationImpersonation role.

Base Command

ews-expand-group

Input
Argument NameDescriptionRequired
email-addressEmail address of the group to expand.Required
recursive-expansionWhether to enable recursive expansion. Default is "False".Optional
Context Output

There is no context output for this command.

Command Example
!ews-expand-group email-address="TestPublic" recursive-expansion="False"
Human Readable Output
displayNamemailboxmailboxType
John Wickjohn@wick.comMailbox
Context Example
{
"EWS.ExpandGroup": {
"name": "TestPublic",
"members": [
{
"mailboxType": "Mailbox",
"displayName": "John Wick",
"mailbox": "john@wick.com"
}
]
}
}

18. Mark items as read

Marks items as read or unread.

Required Permissions

Impersonation rights are required. To perform actions on the target mailbox of other users, the service account must be part of the ApplicationImpersonation role.

Base Command

ews-mark-items-as-read

Input
Argument NameDescriptionRequired
item-idsA CSV list of item IDs.Required
operationHow to mark the item. Can be "read" or "unread". Default is "read".Optional
target-mailboxThe mailbox on which to run the command. If empty, the command will be applied on the default mailbox.Optional
Context Output
PathTypeDescription
EWS.Items.actionStringThe action that was performed on the item.
EWS.Items.itemIdStringThe ID of the item.
EWS.Items.messageIdStringThe message ID of the item.
Command Example
!ews-mark-items-as-read item-ids=AAMkADQ0NFSffU3wX3aBwCyyVyFtlsUQZfBJebinpkUAAABjKMnpkUAAAfxw+jAAA= operation=read target-mailbox=test@demistodev.onmicrosoft.com
Human Readable Output
actionitemIdmessageId
marked-as-readAAMkADQ0NFSffU3wX3aBwCyyVyFtlsUQZfBJebinpkUAAABjKMnpkUAAAfxw+jAAA=
Context Example
{
"EWS": {
"Items": {
"action": "marked-as-read",
"itemId": "AAMkADQ0NFSffU3wX3aBwCyyVyFtlsUQZfBJebinpkUAAABjKMnpkUAAAfxw+jAAA= ",
"messageId": "message_id"
}
}
}

19. Send an email

Required Permissions

Impersonation rights are required. To perform actions on the target mailbox of other users, the service account must be part of the ApplicationImpersonation role.

Base Command

send-mail

Input
Argument NameDescriptionRequired
toEmail addresses for the 'To' field. Supports comma-separated valuesOptional
ccEmail addresses for the 'Cc' field. Supports comma-separated valuesOptional
bccEmail addresses for the 'Bcc' field. Supports comma-separated valuesOptional
subjectSubject for the email to be sentOptional
bodyThe contents (body) of the email to be sent in plain textOptional
htmlBodyThe contents (body) of the email to be sent in HTML formatOptional
attachIDsA comma-separated list of IDs of war room entries that contains the files that should be attached to the emailOptional
attachNamesA comma-separated list to rename file-names of corresponding attachments IDs. (e.g. rename first two files - attachNames=file_name1,file_name2. rename first and third file - attachNames=file_name1,,file_name3)Optional
attachCIDsA comma-separated list of CIDs to embed attachments inside the email itselfOptional
transientFileDesired name for attached file. Multiple files are supported as comma-separated list. (e.g. transientFile="t1.txt,temp.txt,t3.txt" transientFileContent="test 2,temporary file content,third file content" transientFileCID="t1.txt@xxx.yyy,t2.txt@xxx.zzz")Optional
transientFileContentContent for attached file. Multiple files are supported as comma-separated list. (e.g. transientFile="t1.txt,temp.txt,t3.txt" transientFileContent="test 2,temporary file content,third file content" transientFileCID="t1.txt@xxx.yyy,t2.txt@xxx.zzz")Optional
transientFileCIDCID for attached file if we want it inline. Multiple files are supported as comma-separated list. (e.g. transientFile="t1.txt,temp.txt,t3.txt" transientFileContent="test 2,temporary file content,third file content" transientFileCID="t1.txt@xxx.yyy,t2.txt@xxx.zzz")Optional
templateParamsReplace {varname} variables with values from this argument. Expected values are in the form of a JSON document like {"varname": {"value": "some value", "key": "context key"}}. Each var name can either be provided with the value or a context key to retrieve the value fromOptional
additionalHeaderA comma-separated list list of additional headers in the format: headerName=headerValue. For example: "headerName1=headerValue1,headerName2=headerValue2".Optional
raw_messageRaw email message to send. If provided, all other arguments, but to, cc and bcc, will be ignored.Optional

Context Output

There is no context output for this command.

Command Example
!send-mail to=demisto@demisto.onmicrosoft.com subject=some_subject body=some_text attachIDs=110@457,116@457 htmlBody="<html><body>Hello <b>World</b></body></html>" additionalHeader="some_header_name=some_header_value" transientFile=some_file.txt transientFileContent="Some file content"
Human Readable Output

Mail sent successfully

Additional Information

EWS Permissions

To perform actions on mailboxes of other users, and to execute searches on the Exchange server, you need specific permissions. For a comparison between Delegate and Impersonation permissions, see the Microsoft documentation.

PermissionUse CaseHow to Configure
DelegateOne-to-one relationship between users.Read more here.
ImpersonationA single account needs to access multiple mailboxes.Read more here.
eDiscoverySearch the Exchange server.Read more here.
Compliance SearchPerform searches across mailboxes and get an estimate of the results.Read more here.
Edit this page
Report an Issue