Skip to main content

EWS v2

This Integration is part of the Microsoft Exchange On-Premise Pack.#

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 Office Outlook.

The EWS v2 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.

Note: Starting from pack version 2.0.0 the EWS v2 integration requires the Exchange server to support TLS v1.2 and up in order to connect.

Multi-Factor Authentication (MFA) EWS v2 does not support Multi-Factor Authentication (MFA).

If using MFA, use EWS O365 (see https://xsoar.pan.dev/docs/reference/integrations/ewso365)

or if you have Graph Outlook use O365 Outlook Mail (Using Graph API) (see https://xsoar.pan.dev/docs/reference/integrations/microsoft-graph-mail)

or O365 Outlook Mail Single User (Using Graph API) (see https://xsoar.pan.dev/docs/reference/integrations/microsoft-graph-mail-single-user).

EWS v2 Playbooks#

  • Office 365 Search and Delete
  • Search And Delete Emails - EWS
  • 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:

    • Use the ews-search-mailboxes command to search for all emails in a specific scope of mailboxes. Use the filter argument to narrow the search for emails sent from a specific account and more.
    • 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.

    Both of these commands retrieve the ItemID field for each email item listed in the results. TheItemID can be used in the ews-get-items command in order to get more information about the email item itself. For instance, use the ews-search-mailboxes command to hunt for emails that were marked as malicious in prior investigations, across organization mailboxes. Focus your hunt on emails sent from a specific mail account, emails with a specific subject and more.

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

  • Send notifications to external users.

  • Send an email asking for a response to be returned as part of a playbook. See Receiving an email reply

Configure EWS v2 on Cortex XSOAR#

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

  2. Search for EWS v2.

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

    ParameterRequired
    Email addressTrue
    PasswordTrue
    Email address from which to fetch incidentsTrue
    Name of the folder from which to fetch incidents (supports Exchange Folder ID and sub-folders e.g. Inbox/Phishing)True
    Public FolderFalse
    Has impersonation rightsFalse
    Use system proxy settingsFalse
    Fetch incidentsFalse
    First fetch timestamp (<number> <time unit>, e.g., 12 hours, 7 days)False
    Mark fetched emails as readFalse
    Incident typeFalse
    ┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉
    β€Ž Manual Mode
    Exchange Server Hostname or IP address
    False
    DOMAIN\USERNAME (e.g. DEMISTO.INT\admin)False
    Exchange Server Version (On-Premise only. Supported versions: 2007, 2010, 2010_SP2, 2013, 2016, and 2019)False
    Trust any certificate (not secure)False
    ┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉
    β€Ž Advanced Mode
    Override Authentication Type (NTLM, Basic, or Digest).
    False
    Timeout (in seconds) for HTTP requests to Exchange ServerFalse
    Max incidents per fetchFalse
    Run as a separate process (protects against memory depletion)False
  4. Click Test to validate the URLs, token, and connection.

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

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. Additionally, moving messages manually to the destination folder will not trigger a fetch incident. Define rules on phishing/target mailbox instead of moving messages manually.

You can configure the First fetch timestamp field to determine how much time back you want to fetch incidents.

Notice that it might require you to set the Timeout field to a higher value.

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

  • Email address from which to fetch incidents – 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.

  • Has impersonation rights – mark this option if you set the target mailbox to an account different than your personal account. Otherwise Delegation access will be used instead of Impersonation. Find more information on impersonation or delegation rights in the Additional Information section.

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.

ews-get-attachment#


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

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 retrieve 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.attachmentSHA256stringThe SHA256 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": "&lt;message_id&gt;"
}
}
}
}

ews-delete-attachment#


Deletes the attachments of an item (email message).

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="
}
}
}
}

ews-get-searchable-mailboxes#


Returns a list of searchable mailboxes. This command requires eDiscovery permissions to the Exchange Server. For more information, see the EWSv2 integration 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"
}
]
}
}

ews-search-mailboxes#


Searches over multiple mailboxes or all Exchange mailboxes. Use either the mailbox-search-scope command or the email-addresses command to search specific mailboxes. This command requires eDiscovery permissions to the Exchange Server. For more information, see the EWS v2 integration documentation.

The number of mailboxes to search in may be limited by Microsoft Exchange. See here for more information.

Base Command#

ews-search-mailboxes

Input#

Argument NameDescriptionRequired
filterThe filter query to search.Required
mailbox-search-scopeThe mailbox IDs to search. If empty, all mailboxes are searched.Optional
limitMaximum number of results to return. Default is 250.Optional
email_addressesCSV list or array of email addresses.Optional

Context Output#

PathTypeDescription
EWS.Items.itemIdstringThe item ID.
EWS.Items.mailboxstringThe mailbox address where the item was found.
EWS.Items.subjectstringThe subject of the email.
EWS.Items.toRecipientsUnknownList of recipient email addresses.
EWS.Items.senderstringSender email address.
EWS.Items.hasAttachmentsbooleanWhether the email has attachments?
EWS.Items.datetimeSentdateSent time of the email.
EWS.Items.datetimeReceiveddateReceived time of the email.

Command Example#

!ews-search-mailboxes filter="subject:Test" limit=1

Human Readable Output#

datetimeReceiveddatetimeSenthasAttachmentsitemIdmailboxsendersubjecttoRecipients
2019-08-11T11:00:28Z2019-08-11T11:00:28ZfalseAAMkAGY3OTQyMzMzLWYxNjktNDE0My05NmZhLWQ5MGY1YjIyNzBkNABGACASFAACYCKjWAnXDFrfsdhdnfkanpAAA=test2@demistodev.onmicrosoft.comJohn Smithtest reportdem@demistodev.onmicrosoft.com

Context Example#

{
"EWS": {
"Items": {
"itemId": "AAMkAGY3OTQyMzMzLWYxNjktNDE0My05NmZhLWQ5MGY1YjIyNzBkNABGACASFAACYCKjWAnXDFrfsdhdnfkanpAAA=",
"sender": "John Smith",
"datetimeReceived": "2019-08-11T11:00:28Z",
"hasAttachments": "false",
"toRecipients": [
"dem@demistodev.onmicrosoft.com"
],
"mailbox": "test2@demistodev.onmicrosoft.com",
"datetimeSent": "2019-08-11T11:00:28Z",
"subject": "test report "
}
}
}

ews-move-item#


Move an item to different folder in the mailbox.

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. Possible values are: True, False.Optional

Context Output#

PathTypeDescription
EWS.Items.newItemIDstringThe item ID after move.
EWS.Items.messageIDstringThe item message ID.
EWS.Items.itemIdstringThe original item ID.
EWS.Items.actionstringThe action taken. The value will be "moved".

ews-delete-items#


Delete items from mailbox.

Base Command#

ews-delete-items

Input#

Argument NameDescriptionRequired
item-idsThe item IDs to delete.Required
delete-typeDeletion type. Can be "trash", "soft", or "hard". Default is soft.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=<message_id>

Context Example#

{
"EWS": {
"Items": {
"action": "soft-deleted",
"itemId": "VWAFA3hmZjdmNTZjNTMxNwBGAAAAAAA4kxh+ed3JTJPMPXU3wX3aBwCyyVyFtlsUQZfBJebinpkUAAABjKMGAACyw+kAAA=",
"messageId": "&lt;messaage_id&gt;"
}
}
}

ews-search-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.

Base Command#

ews-search-mailbox

Input#

Argument NameDescriptionRequired
queryThe search query string. For more information about the query syntax, see the Microsoft documentation: https://msdn.microsoft.com/en-us/library/ee693615.aspx.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. Default is 100.Optional
target-mailboxThe mailbox on which to apply the search.Optional
is-publicWhether the folder is a Public Folder?. Possible values are: True, False.Optional
message-idThe message ID of the email. This will be ignored if a query argument is provided.Optional
selected-fieldsA CSV list of fields to retrieve. Possible values are: . Default is all.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": "&lt;html&gt;\r\n&lt;head&gt;\r\n&lt;meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\"&gt;\r\n&lt;style type=\"text/css\" style=\"display:none;\"&gt;&lt;!-- P {margin-top:0;margin-bottom:0;} --&gt;&lt;/style&gt;\r\n&lt;/head&gt;\r\n&lt;body dir=\"ltr\"&gt;\r\n&lt;div id=\"divtagrapper\" style=\"font-size:12pt;color:#000000;font-family:Calibri,Helvetica,sans-serif;\" dir=\"ltr\"&gt;\r\n&lt;p style=\"margin-top:0;margin-bottom:0\"&gt;Some text inside email&lt;/p&gt;\r\n&lt;/div&gt;\r\n&lt;/body&gt;\r\n&lt;/html&gt;\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": "&lt;mesage_id&gt;",
"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"
}
}
}

ews-get-contacts#


Retrieves contacts for a specified mailbox.

Base Command#

ews-get-contacts

Input#

Argument NameDescriptionRequired
target-mailboxThe mailbox for which to retrieve the contacts.Optional
limitMaximum number of results to return. Default is 100.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": "&lt;html&gt;&lt;body&gt;&lt;/body&gt;&lt;/html&gt;",
"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"
}
]
}

ews-resolve-name#


This operation verifies aliases and matches display names to the correct mailbox user. It handles one ambiguous name at a time. If there are multiple potential matches, all will be returned, but limited to a maximum of 100 candidates.

Base Command#

ews-resolve-name

Input#

Argument NameDescriptionRequired
identifierThe text value of this argument is used to resolve names against the following fields: First name, Last name, Display name, Full name, Office, Alias, SMTP address. Eg. John Doe or sip:johndoe@example.com.Required
full-contact-dataDescribes whether the full contact details for public contacts for a resolved name are returned. Possible values are: True, False.Optional

Context Output#

PathTypeDescription
EWS.ResolvedNames.FullContactInfo.contactSourceStringWhether the contact is located in the Exchange store or Active Directory Domain Services (AD DS).
EWS.ResolvedNames.FullContactInfo.cultureStringRepresents the culture for a given item in a mailbox.
EWS.ResolvedNames.FullContactInfo.displayNameStringThe display name of a contact.
EWS.ResolvedNames.FullContactInfo.ItemIdStringContains the unique identifier and change key of an item in the Exchange store.
EWS.ResolvedNames.FullContactInfo.emailAddressesStringRepresents a collection of email addresses for a contact.
EWS.ResolvedNames.FullContactInfo.givenNameStringContains a contact's given name.
EWS.ResolvedNames.FullContactInfo.importanceStringDescribes the importance of an item.
EWS.ResolvedNames.FullContactInfo.initialsStringRepresents the initials of a contact.
EWS.ResolvedNames.FullContactInfo.phoneNumbers.labelStringThe following are the possible values for this attribute: AssistantPhone, BusinessFax, BusinessPhone, BusinessPhone2, Callback, CarPhone, CompanyMainPhone, HomeFax, HomePhone, HomePhone2, Isdn, MobilePhone, OtherFax, OtherTelephone, Pager, PrimaryPhone, RadioPhone, Telex, TtyTddPhone
EWS.ResolvedNames.FullContactInfo.phoneNumbers.phoneNumberStringThe phone number of the contact
EWS.ResolvedNames.FullContactInfo.physicalAddresses.cityStringThe physical addresses city associated with the contact.
EWS.ResolvedNames.FullContactInfo.physicalAddresses.countryStringThe physical addresses country associated with the contact.
EWS.ResolvedNames.FullContactInfo.physicalAddresses.labelStringThe physical addresses label associated with the contact.
EWS.ResolvedNames.FullContactInfo.physicalAddresses.stateStringThe physical addresses state associated with the contact.
EWS.ResolvedNames.FullContactInfo.physicalAddresses.streetStringThe physical addresses street associated with the contact.
EWS.ResolvedNames.FullContactInfo.physicalAddresses.zipcodeStringThe physical addresses zipcode associated with the contact.
EWS.ResolvedNames.FullContactInfo.postalAddressIndexStringRepresents the display types for physical addresses.
EWS.ResolvedNames.FullContactInfo.sensitivityStringIndicates the sensitivity level of an item.
EWS.ResolvedNames.email_addressStringThe primary SMTP address of a mailbox user.
EWS.ResolvedNames.mailbox_typeStringThe type of mailbox that is represented by the email address.
EWS.ResolvedNames.nameStringThe name of a mailbox user.
EWS.ResolvedNames.routing_typeStringThe address type for the mailbox

Command example#

!ews-resolve-name identifier=`example@example.com` full-contact-data=True

Context Example#

{
"EWS": {
"ResolvedNames": {
"FullContactInfo": {
"contactSource": "ActiveDirectory",
"culture": "en-US",
"displayName": "ews-2016-test EW2016.",
"emailAddresses": [
"example-sec@example.com",
"example@example.com"
],
"givenName": "ews-2016-test",
"importance": "Normal",
"initials": "EW2016",
"phoneNumbers": [
{
"label": "AssistantPhone",
"phoneNumber": null
},
{
"label": "BusinessFax",
"phoneNumber": null
},
{
"label": "BusinessPhone",
"phoneNumber": null
},
{
"label": "HomePhone",
"phoneNumber": null
},
{
"label": "MobilePhone",
"phoneNumber": null
},
{
"label": "Pager",
"phoneNumber": null
}
],
"physicalAddresses": [
{
"city": null,
"country": null,
"label": "Business",
"state": null,
"street": null,
"zipcode": null
}
],
"postalAddressIndex": "None",
"sensitivity": "Normal"
},
"email_address": "ews-2016-test@lab-demisto.com",
"mailbox_type": "Mailbox",
"name": "ews-2016-test EW2016.",
"routing_type": "SMTP"
}
}
}

Human Readable Output#

Resolved Names#

primary_email_addressnamemailbox_typerouting_type
ews-2016-test@lab-demisto.comews-2016-test EW2016.MailboxSMTP

ews-get-out-of-office#


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

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. Result can be: Enabled, Scheduled, 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#

endexternalAudiencmailboxstartstate
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"
}
}
}
}

ews-recover-messages#


Recovers messages that were soft-deleted.

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 IDs.Required
target-folder-pathThe folder path to recover the messages to. Default is Inbox.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. Possible values are: True, False.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=&lt;DFVDFmvsCSCS.com&gt; target-folder-path=Moving target-mailbox=test@demistodev.onmicrosoft.com

Human Readable Output#

actionitemIdmessageId
recoveredAAVCSVS1hN2NkLThmZjdmNTZjNTMxNwBGAAAAAAA4kxh+ed33wX3aBwCyyVyFtlsUQZfBJebinpkUAAAa2bUBAACyyVyFtlscfxxd/AAA=DFVDFmvsCSCS.com

Context Example#

{
"EWS": {
"Items": {
"action": "recovered",
"itemId": "AAVCSVS1hN2NkLThmZjdmNTZjNTMxNwBGAAAAAAA4kxh+ed33wX3aBwCyyVyFtlsUQZfBJebinpkUAAAa2bUBAACyyVyFtlscfxxd/AAA=",
"messageId": "&lt;DFVDFmvsCSCS.com&gt;"
}
}
}

ews-create-folder#


Creates a new folder in a specified mailbox.

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. Default is Inbox.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

ews-mark-item-as-junk#


Marks an item as junk. This is commonly used to block an email address. For more information, see the Microsoft documentation: https://msdn.microsoft.com/en-us/library/office/dn481311(v=exchg.150).aspx

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. Possible values are: yes, no. Default is yes.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="
}
}
}

ews-find-folders#


Retrieves information for folders for a 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".

Base Command#

ews-find-folders

Input#

Argument NameDescriptionRequired
target-mailboxThe mailbox on which to apply the command.Optional
is-publicWhether to find Public Folders. Possible values are: True, False.Optional

Context Output#

PathTypeDescription
EWS.Folders.namestringFolder name.
EWS.Folders.idstringFolder ID.
EWS.Folders.totalCountUnknownNumber of items in folder.
EWS.Folders.unreadCountnumberNumber of unread items in 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="
}
]
}
}

ews-get-items-from-folder#


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

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. Default is 100.Optional
target-mailboxThe mailbox to on which to apply the command.Optional
is-publicWhether the folder is a Public Folder. Default is 'False'. Possible values are: True, False.Optional
get-internal-itemIf 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". Possible values are: yes, 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.
EWS.Items.isReadStringThe read status of the email.
EWS.Items.categoriesStringCategories 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": "&lt;html&gt;\r\n&lt;head&gt;\r\n&lt;meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\"&gt;\r\n&lt;style type=\"text/css\" style=\"display:none;\"&gt;&lt;!-- P {margin-top:0;margin-bottom:0;} --&gt;&lt;/style&gt;\r\n&lt;/head&gt;\r\n&lt;body dir=\"ltr\"&gt;\r\n&lt;div id=\"divtagdefaultwrapper\" style=\"font-size:12pt;color:#000000;font-family:Calibri,Helvetica,sans-serif;\" dir=\"ltr\"&gt;\r\n&lt;p style=\"margin-top:0;margin-bottom:0\"&gt;Some text inside email&lt;/p&gt;\r\n&lt;/div&gt;\r\n&lt;/body&gt;\r\n&lt;/html&gt;\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": "&lt;message_id&gt;",
"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"
}
}
}

ews-get-items#


Retrieves items by item ID.

Base Command#

ews-get-items

Input#

Argument NameDescriptionRequired
item-idsA CSV list if 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.
EWS.Items.categoriesStringCategories 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.

ews-move-item-between-mailboxes#


Moves an item from one mailbox to different mailbox.

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". Possible values are: True, False.Optional

Context Output#

PathTypeDescription
EWS.Items.movedToMailboxstringThe mailbox wo 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"
}
}
}

ews-get-folder#


Retrieves a single folder.

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". Default is AllItems.Optional
is-publicWhether the folder is a Public Folder. Default is "False". Possible values are: True, 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="
}
}
}

ews-o365-start-compliance-search#


Starts a compliance search.

Base Command#

ews-o365-start-compliance-search

Input#

Argument NameDescriptionRequired
queryQuery to use to find emails.Required

Context Output#

PathTypeDescription
EWS.ComplianceSearch.NamestringThe name of the compliance search.
EWS.ComplianceSearch.StatusstringThe status of the compliance search.

Command Example#

!ews-o365-start-compliance-search query="subject:"Wanted Email""

Human Readable Output#

Search started: DemistoSearch67e67371d0004c46bebfa3219b5a14bf

Context Example#

{
"EWS": {
"ComplianceSearch": {
"Status": "Starting",
"Name": "DemistoSearch67e67371d0004c46bebfa3219b5a14bf"
}
}
}

ews-o365-get-compliance-search#


Returns the status and results of a compliance search.

Base Command#

ews-o365-get-compliance-search

Input#

Argument NameDescriptionRequired
search-nameThe name of the compliance search.Required
show-only-recipientsWhether to return only mailboxes which contain the email. Default is "False". Possible values are: True, False. Default is False.Optional

Context Output#

PathTypeDescription
EWS.ComplianceSearch.StatusUnknownThe status of the compliance search.
EWS.ComplianceSearch.Results.LocationStringThe mailbox.
EWS.ComplianceSearch.Results.Item CountNumberThe number of emails found in the mailbox.
EWS.ComplianceSearch.Results.Total SizeNumberTotal number of emails in the mailbox.

Command Example#

!ews-o365-get-compliance-search search-name=DemistoSearch67e67371d0004c46bebfa3219b5a14bf

Human Readable Output#

LocationItem CountTotal Size
test@demistodev.onmicrosoft.com00

Context Example#

{
"EWS": {
"ComplianceSearch": {
"Status": "Completed",
"Name": "DemistoSearch67e67371d0004c46bebfa3219b5a14bf"
}
}
}

ews-o365-purge-compliance-search-results#


Purges the results found in the compliance search.

Base Command#

ews-o365-purge-compliance-search-results

Input#

Argument NameDescriptionRequired
search-nameThe name of the compliance search.Required

Context Output#

PathTypeDescription
EWS.ComplianceSearch.StatusstringThe status of the compliance search.

Command Example#

!ews-o365-purge-compliance-search-results search-name=DemistoSearch67e67371d0004c46bebfa3219b5a14bf

Human Readable Output#

Search DemistoSearch67e67371d0004c46bebfa3219b5a14bf status: Purging

Context Example#

{
"EWS": {
"ComplianceSearch": {
"Status": "Purging",
"Name": "DemistoSearch67e67371d0004c46bebfa3219b5a14bf"
}
}
}

ews-o365-remove-compliance-search#


Removes the compliance search.

Base Command#

ews-o365-remove-compliance-search

Input#

Argument NameDescriptionRequired
search-nameThe name of the compliance search.Required

Context Output#

PathTypeDescription
EWS.ComplianceSearch.StatusstringThe status of the compliance search.

Command Example#

!ews-o365-remove-compliance-search search-name=DemistoSearch67e67371d0004c46bebfa3219b5a14bf

Human Readable Output#

Search DemistoSearch67e67371d0004c46bebfa3219b5a14bf status: Removed

Context Example#

{
"EWS": {
"ComplianceSearch": {
"Status": "Removed",
"Name": "DemistoSearch67e67371d0004c46bebfa3219b5a14bf"
}
}
}

ews-o365-get-compliance-search-purge-status#


Checks the status of the purge operation on the compliance search.

Base Command#

ews-o365-get-compliance-search-purge-status

Input#

Argument NameDescriptionRequired
search-nameThe name of the compliance search.Required

Context Output#

PathTypeDescription
EWS.ComplianceSearch.StatusUnknownThe status of the compliance search.

Command Example#

!ews-o365-get-compliance-search-purge-status search-name=DemistoSearch67e67371d0004c46bebfa3219b5a14bf

Human Readable Output#

Search DemistoSearch67e67371d0004c46bebfa3219b5a14bf status: Purged

Context Example#

{
"EWS": {
"ComplianceSearch": {
"Status": "Purged",
"Name": "DemistoSearch67e67371d0004c46bebfa3219b5a14bf"
}
}
}

ews-get-autodiscovery-config#


Returns the auto-discovery information. Can be used to manually configure the Exchange Server.

Base Command#

ews-get-autodiscovery-config

Input#

There are no input arguments for this command.

Context Output#

There is no context output for this command.

Command Example#

!ews-get-autodiscovery-config

Human Readable Output#

api_versionauth_typebuildservice_endpoint
Exchange2016###--https://outlook.office365.com/EWS/Exchange.asmx

ews-expand-group#


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

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". Possible values are: True, False. 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#

displayNammailboxmailboxtype
John Wickjohn@wick.comMailBox

Context Example#

{
"EWS.ExpandGroup": {
"name": "TestPublic",
"members": [
{
"mailboxType": "Mailbox",
"displayName": "John Wick",
"mailbox": "john@wick.com"
}
]
}
}

ews-mark-items-as-read#


Marks items as read or unread.

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". Possible values are: read, 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 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
mark-as-readAAMkADQ0NFSffU3wX3aBwCyyVyFtlsUQZfBJebinpkUAAABjKMnpkUAAAfxw+jAAA=id

Context Example#

{
"EWS": {
"Items": {
"action": "marked-as-read",
"itemId": "AAMkADQ0NFSffU3wX3aBwCyyVyFtlsUQZfBJebinpkUAAABjKMnpkUAAAfxw+jAAA= ",
"messageId": "&lt;message_id&gt;"
}
}
}

ews-get-items-as-eml#


Retrieves items by item ID and uploads it's content as eml file.

Base Command#

ews-get-items-as-eml

Input#

Argument NameDescriptionRequired
item-idThe item ID of item to upload as and EML file.Required
target-mailboxThe mailbox in which this email was found. If empty, the default mailbox is used. Otherwise the user might require impersonation rights to this mailbox.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.EntryIDStringEntryID 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.

send-mail#


Sends an email using EWS.

Base Command#

send-mail

Input#

Argument NameDescriptionRequired
toA CSV list of email addresses for the 'to' field.Required
ccA CSV list of email addresses for the 'cc' field.Optional
bccA CSV list of email addresses for the 'bcc' field.Optional
subjectSubject for the email to be sent.Required
replyToThe email address specified in the 'reply to' field.Optional
bodyThe contents (body) of the email to send.Optional
htmlBodyHTML formatted content (body) of the email to be sent. This argument overrides the "body" argument.Optional
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
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
raw_messageRaw email message from MimeContent type.Optional
fromThe email address from which to reply.Optional

Context Output#

There is no context output for this command.

reply-mail#


Replies to an email using EWS.

Command Example#

!send-mail body="hello this is a test" subject=Hi to=avishai@demistodev.onmicrosoft.com

Human Readable Output#

Sent email#

attachmentsfromsubjectto
avishai@demistodev.onmicrosoft.comHiavishai@demistodev.onmicrosoft.com

Base Command#

reply-mail

Input#

Argument NameDescriptionRequired
inReplyToID of the item to reply to.Required
toA CSV list of email addresses for the 'to' field.Required
ccA CSV list of email addresses for the 'cc' field.Optional
bccA CSV list of email addresses for the 'bcc' field.Optional
subjectSubject for the email to be sent.Optional
bodyThe contents (body) of the email to be sent.Optional
htmlBodyHTML formatted content (body) of the email to be sent. This argument overrides the "body" argument.Optional
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
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

Context Output#

There is no context output for this command.

Command Example#

!reply-mail item_id=AAMkAGY3OTQyMzMzLWYxNjktNDE0My05NmZhLWQ5MGY1YjIyNzBkNABGAAAAAACYCKjWAnXBTrnhgWJCcLX7BwDrxRwRjq/zTrN6vWSzK4OWAAAAAAEMAADrxRwRjq/zTrN6vWSzK4OWAAPYQGFeAAA= body=hello subject=hi to="avishai@demistodev.onmicrosoft.com"

Human Readable Output#

Sent email#

attachmentsfromsubjectto
avishai@demistodev.onmicrosoft.comhiavishai@demistodev.onmicrosoft.com

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
DelegatedOne-to-one relationship between users.Read more here.
ImpersonationA single account needs to access multiple mailboxes.Read more here.
eDiscoveryA single account needs to access multiple mailboxes.Read more here.
Compliance SearchPerform searches across mailboxes and get an estimate of the results.Read more here.

New-Compliance Search#

The EWS v2 integration uses remote ps-session to run commands of compliance search as part of Office 365. To check if your account can connect to Office 365 Security & Compliance Center via powershell, check the following steps. New-Compliance search is a long-running task which has no limitation of searched mailboxes and therefore the suggestion is to use Office 365 Search and Deleteplaybook. New-Compliance search returns statistics of matched content search query and doesn't return preview of found emails in contrast toews-search-mailboxescommand.

Troubleshooting#

For troubleshooting information, see the EWS V2 Troubleshooting.