EWS O365
Microsoft Exchange Online Pack.#
This Integration is part of theExchange 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.
The integration will use the UPN parameter (if given) as the target mailbox if it's different from the Email Address, otherwise, the Email Address is used.
#
EWS O365 Playbook- Get Original Email - EWS
- Process Email - EWS
#
Use CasesThe 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-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 theews-get-items
command in order to get more information about the email item itself.
- Use the
Get email attachment information.
Use theews-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 theews-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 theews-recover-messages
Ā command.
#
Configure EWS O365 on Cortex XSOAR- Navigate to Settings > Integrations > Servers & Services.
- Search for EWS O365.
- 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
- Access Type: Run the commands using
Delegate
orImpersonation
access types. - Mark fetched emails as read: Mark emails as read after fetching them.
- Use system proxy settings
- Trust any certificate (not secure)
- Timeout (in seconds) for HTTP requests to Exchange Server
- Use a self deployed Azure Application
- Click Test to validate the URLs, token, and connection.
#
AuthenticationFor more details about the authentication used in this integration, see Microsoft Integrations - Authentication.
#
Required Permissions for self deployed Azure Applications#
Office 365 Exchange Onlinefull_access_as_app - To set this permission follow the Microsoft documentation. You can't manage the Office 365 Exchange Online app permissions via the Azure portal.
To limit the application's permissions to only specific mailboxes, follow the Microsoft documentation. Note that it may take about an hour for permissions changes to take effect.
#
Fetched Incidents DataThe 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.
You can configure the First fetch timestamp
field to determine how much time back you want to fetch incidents.
Notice that it might be required to set the Timeout
field to a higher value.
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.
#
CommandsYou 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.
- Get the attachments of an item: ews-get-attachment
- Delete the attachments of an item: ews-delete-attachment
- Get a list of searchable mailboxes: ews-get-searchable-mailboxes
- Move an item to a different folder: ews-move-item
- Delete an item from a mailbox: ews-delete-items
- Search a single mailbox: ews-search-mailbox
- Get the contacts for a mailbox: ews-get-contacts
- Get the out-of-office status for a mailbox: ews-get-out-of-office
- Recover soft-deleted messages: ews-recover-messages
- Create a folder: ews-create-folder
- Mark an item as junk: ews-mark-item-as-junk
- Search for folders: ews-find-folders
- Get items of a folder: ews-get-items-from-folder
- Get items: ews-get-items
- Move an item to a different mailbox: ews-move-item-between-mailboxes
- Get a folder: ews-get-folder
- Expand a distribution list: ews-expand-group
- Mark items as read: ews-mark-items-as-read
- Send an email: send-mail
- Retrieve item as eml: ews-get-items-as-eml
- Reply to an email: reply-mail
#
1. Get the attachments of an itemRetrieves the actual attachments from an item (email message). To get all attachments for a message, only specify the item-id argument.
#
Required PermissionsImpersonation 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 Commandews-get-attachment
#
InputArgument Name | Description | Required |
---|---|---|
item-id | The ID of the email message for which to get the attachments. | Required |
target-mailbox | The 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-ids | The 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 OutputPath | Type | Description |
---|---|---|
EWS.Items.FileAttachments.attachmentId | string | The attachment ID. Used for file attachments only. |
EWS.Items.FileAttachments.attachmentName | string | The attachment name. Used for file attachments only. |
EWS.Items.FileAttachments.attachmentSHA256 | string | The SHA256 hash of the attached file. |
EWS.Items.FileAttachments.attachmentLastModifiedTime | date | The attachment last modified time. Used for file attachments only. |
EWS.Items.ItemAttachments.datetimeCreated | date | The created time of the attached email. |
EWS.Items.ItemAttachments.datetimeReceived | date | The received time of the attached email. |
EWS.Items.ItemAttachments.datetimeSent | date | The sent time of the attached email. |
EWS.Items.ItemAttachments.receivedBy | string | The received by address of the attached email. |
EWS.Items.ItemAttachments.subject | string | The subject of the attached email. |
EWS.Items.ItemAttachments.textBody | string | The body of the attached email (as text). |
EWS.Items.ItemAttachments.headers | Unknown | The headers of the attached email. |
EWS.Items.ItemAttachments.hasAttachments | boolean | Whether the attached email has attachments. |
EWS.Items.ItemAttachments.itemId | string | The attached email item ID. |
EWS.Items.ItemAttachments.toRecipients | Unknown | A list of recipient email addresses for the attached email. |
EWS.Items.ItemAttachments.body | string | The body of the attached email (as HTML). |
EWS.Items.ItemAttachments.attachmentSHA256 | string | SHA256 hash of the attached email (as EML file). |
EWS.Items.ItemAttachments.FileAttachments.attachmentSHA256 | string | SHA256 hash of the attached files inside of the attached email. |
EWS.Items.ItemAttachments.ItemAttachments.attachmentSHA256 | string | SHA256 hash of the attached emails inside of the attached email. |
EWS.Items.ItemAttachments.isRead | String | The read status of the attachment. |
#
Command Example#
Context Example#
2. Delete the attachments of an itemDeletes the attachments of an item (email message).
#
Required PermissionsImpersonation 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 Commandews-delete-attachment
#
InputArgument Name | Description | Required |
---|---|---|
item-id | The ID of the email message for which to delete attachments. | Required |
target-mailbox | The 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-ids | A CSV list (or array) of attachment IDs to delete. If empty, all attachments will be deleted from the message. | Optional |
#
Context OutputPath | Type | Description |
---|---|---|
EWS.Items.FileAttachments.attachmentId | string | The ID of the deleted attachment, in case of file attachment. |
EWS.Items.ItemAttachments.attachmentId | string | The ID of the deleted attachment, in case of other attachment (for example, "email"). |
EWS.Items.FileAttachments.action | string | The deletion action in case of file attachment. This is a constant value: 'deleted'. |
EWS.Items.ItemAttachments.action | string | The deletion action in case of other attachment (for example, "email"). This is a constant value: 'deleted'. |
#
Command Example#
Human Readable Outputaction | attachmentId |
---|---|
deleted | AAMkADQ0NmwBGAAAAAAA4kxh+ed3JTJPMPXU3wX3aBwCyyVyFtlsUQZfBJjfaljfAFDVSDinpkUAAAfxxd9AAABEgAQAIUht2vrOdErec33= |
#
Context Example#
3. Get a list of searchable mailboxesReturns a list of searchable mailboxes.
When using UPN parameter, the command ews-get-searchable-mailboxes would work after assigning RBAC roles requested in the management role header as explained [https://learn.microsoft.com/en-us/Exchange/policy-and-compliance/ediscovery/assign-permissions?redirectedfrom=MSDN&view=exchserver-2019].
#
Required PermissionsRequires eDiscovery permissions to the Exchange Server. For more information see theĀ Microsoft documentation.
#
Base Commandews-get-searchable-mailboxes
#
InputThere are no input arguments for this command.
#
Context OutputPath | Type | Description |
---|---|---|
EWS.Mailboxes.mailbox | string | Addresses of the searchable mailboxes. |
EWS.Mailboxes.mailboxId | string | IDs of the searchable mailboxes. |
EWS.Mailboxes.displayName | string | The email display name. |
EWS.Mailboxes.isExternal | boolean | Whether the mailbox is external. |
EWS.Mailboxes.externalEmailAddress | string | The external email address. |
#
Command Example#
Human Readable OutputdisplayName | isExternal | mailbox | mailboxId |
---|---|---|---|
test | false | test@demistodev.onmicrosoft.com | /o=Exchange*/ou=Exchange Administrative Group ()/cn=/cn=- |
#
Context Example#
4. Move an item to a different folderMove an item to a different folder in the mailbox.
#
Required PermissionsImpersonation 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 Commandews-move-item
#
InputArgument Name | Description | Required |
---|---|---|
item-id | The ID of the item to move. | Required |
target-folder-path | The path to the folder to which to move the item. Complex paths are supported, for example, "Inbox\Phishing". | Required |
target-mailbox | The mailbox on which to run the command. | Optional |
is-public | Whether the target folder is a public folder. | Optional |
#
Context OutputPath | Type | Description |
---|---|---|
EWS.Items.newItemID | string | The item ID after the move. |
EWS.Items.messageID | string | The item message ID. |
EWS.Items.itemId | string | The original item ID. |
EWS.Items.action | string | The action taken. The value will be "moved". |
#
Command Example#
Human Readable Outputaction | itemId | messageId | newItemId |
---|---|---|---|
moved | VDAFNTZjNTMxNwBGAAAAAAA4kxh+ed3JTJPMPXU34cSCSSSfBJebinpkUAAAAAAEMAACyyVyFtlsUQZfBJebinpkUAAAfxuiRAAA | AAVAAAVN2NkLThmZjdmNTZjNTMxFFFFJTJPMPXU3wX3aBwCyyVyFtlsUQZfBJebinpkUAAAa2bUBAACyyVfafainpkUAAAfxxd+AAA= |
#
Context Example#
5. Delete an item from a mailboxDelete items from mailbox.
#
Required PermissionsImpersonation 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 Commandews-delete-items
#
InputArgument Name | Description | Required |
---|---|---|
item-ids | The item IDs to delete. | Required |
delete-type | Deletion type. Can be "trash", "soft", or "hard". | Required |
target-mailbox | The mailbox on which to run the command. | Optional |
#
Context OutputPath | Type | Description |
---|---|---|
EWS.Items.itemId | string | The deleted item ID. |
EWS.Items.messageId | string | The deleted message ID. |
EWS.Items.action | string | The deletion action. Can be 'trash-deleted', 'soft-deleted', or 'hard-deleted'. |
#
Command Example#
Human Readable Outputaction | itemId | messageId |
---|---|---|
soft-deleted | VWAFA3hmZjdmNTZjNTMxNwBGAAAAAAA4kxh+ed3JTJPMPXU3wX3aBwCyyVyFtlsUQZfBJebinpkUAAABjKMGAACyw+kAAA= |
#
Context Example#
6. Search a single mailboxSearches for items in the specified mailbox. Specific permissions are needed for this operation to search in a target mailbox other than the default.
#
Required PermissionsImpersonation rights required. To perform actions on the target mailbox of other users, the service account must be part of the ApplicationImpersonation role.
#
Base Commandews-search-mailbox
#
InputArgument Name | Description | Required |
---|---|---|
query | The search query string. For more information about the query syntax, see the Microsoft documentation. | Optional |
folder-path | The folder path in which to search. If empty, searches all the folders in the mailbox. | Optional |
limit | Maximum number of results to return. | Optional |
target-mailbox | The mailbox on which to apply the search. | Optional |
is-public | Whether the folder is a Public Folder? | Optional |
message-id | The message ID of the email. This will be ignored if a query argument is provided. | Optional |
#
Context OutputPath | Type | Description |
---|---|---|
EWS.Items.itemId | string | The email item ID. |
EWS.Items.hasAttachments | boolean | Whether the email has attachments. |
EWS.Items.datetimeReceived | date | Received time of the email. |
EWS.Items.datetimeSent | date | Sent time of the email. |
EWS.Items.headers | Unknown | Email headers (list). |
EWS.Items.sender | string | Sender email address of the email. |
EWS.Items.subject | string | Subject of the email. |
EWS.Items.textBody | string | Body of the email (as text). |
EWS.Items.size | number | Email size. |
EWS.Items.toRecipients | Unknown | List of email recipients addresses. |
EWS.Items.receivedBy | Unknown | Email received by address. |
EWS.Items.messageId | string | Email message ID. |
EWS.Items.body | string | Body of the email (as HTML). |
EWS.Items.FileAttachments.attachmentId | unknown | Attachment ID of the file attachment. |
EWS.Items.ItemAttachments.attachmentId | unknown | Attachment ID of the item attachment. |
EWS.Items.FileAttachments.attachmentName | unknown | Attachment name of the file attachment. |
EWS.Items.ItemAttachments.attachmentName | unknown | Attachment name of the item attachment. |
EWS.Items.isRead | String | The read status of the email. |
#
Command Example#
Human Readable Outputsender | subject | hasAttachments | datetimeReceived | receivedBy | author | toRecipients |
---|---|---|---|---|---|---|
test2@demistodev.onmicrosoft.com | Get Attachment Email | true | 2019-08-11T10:57:37Z | test@demistodev.onmicrosoft.com | test2@demistodev.onmicrosoft.com | test@demistodev.onmicrosoft.com |
#
Context Example#
7. Get the contacts for a mailboxRetrieves contacts for a specified mailbox.
#
Required PermissionsImpersonation 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 Commandews-get-contacts
#
InputArgument Name | Description | Required |
---|---|---|
target-mailbox | The mailbox for which to retrieve the contacts. | Optional |
limit | Maximum number of results to return. | Optional |
#
Context OutputPath | Type | Description |
---|---|---|
Account.Email.EwsContacts.displayName | Unknown | The contact name. |
Account.Email.EwsContacts.lastModifiedTime | Unknown | The time that the contact was last modified. |
Account.Email.EwsContacts.emailAddresses | Unknown | Phone numbers of the contact. |
Account.Email.EwsContacts.physicalAddresses | Unknown | Physical addresses of the contact. |
Account.Email.EwsContacts.phoneNumbers.phoneNumber | Unknown | Email addresses of the contact. |
#
Command Example#
Human Readable Outputchangekey | culture | datetimeCreated | datetimeReceived | datetimeSent | displayName | emailAddresses | fileAs | fileAsMapping | givenName | id | importance | itemClass | lastModifiedName | lastModifiedTime | postalAddressIndex | sensitivity | subject | uniqueBody | webClientReadFormQueryString |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
EABYACAADcsxRwRjq/zTrN6vWSzKAK1Dl3N | en-US | 2019-08-05T12:35:36Z | 2019-08-05T12:35:36Z | 2019-08-05T12:35:36Z | Contact Name | some@dev.microsoft.com | Contact Name | LastCommaFirst | Contact Name | AHSNNK3NQNcasnc3SAS/zTrN6vWSzK4OWAAAAAAEOAADrxRwRjq/zTrNFSsfsfVWAAK1KsF3AAA= | Normal | IPM.Contact | John Smith | 2019-08-05T12:35:36Z | None | Normal | Contact Name | https://outlook.office365.com/owa/?ItemID=*** |
#
Context Example#
8. Get the out-of-office status for a mailboxRetrieves the out-of-office status for a specified mailbox.
#
Required PermissionsImpersonation rights are required. To perform actions on the target mailbox of other users, the service account must be part the ApplicationImpersonation role.
#
Base Commandews-get-out-of-office
#
InputArgument Name | Description | Required |
---|---|---|
target-mailbox | The mailbox for which to get the out-of-office status. | Required |
#
Context OutputPath | Type | Description |
---|---|---|
Account.Email.OutOfOffice.state | Unknown | Out-of-office state. The result can be: "Enabled", "Scheduled", or "Disabled". |
Account.Email.OutOfOffice.externalAudience | Unknown | Out-of-office external audience. Can be "None", "Known", or "All". |
Account.Email.OutOfOffice.start | Unknown | Out-of-office start date. |
Account.Email.OutOfOffice.end | Unknown | Out-of-office end date. |
Account.Email.OutOfOffice.internalReply | Unknown | Out-of-office internal reply. |
Account.Email.OutOfOffice.externalReply | Unknown | Out-of-office external reply. |
Account.Email.OutOfOffice.mailbox | Unknown | Out-of-office mailbox. |
#
Command Example#
Human Readable Outputend | externalAudience | mailbox | start | state |
---|---|---|---|---|
2019-08-12T13:00:00Z | All | test@demistodev.onmicrosoft.com | 2019-08-11T13:00:00Z | Disabled |
#
Context Example#
9. Recover soft-deleted messagesRecovers messages that were soft-deleted.
#
Required PermissionsImpersonation rights are required. To perform actions on the target mailbox of other users, the service account must be part of the ApplicationImpersonation role.
#
Base Commandews-recover-messages
#
InputArgument Name | Description | Required |
---|---|---|
message-ids | A CSV list of message IDs. Run the py-ews-delete-items command to retrieve the message IDs | Required |
target-folder-path | The folder path to recover the messages to. | Required |
target-mailbox | The 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-public | Whether the target folder is a Public Folder. | Optional |
#
Context OutputPath | Type | Description |
---|---|---|
EWS.Items.itemId | Unknown | The item ID of the recovered item. |
EWS.Items.messageId | Unknown | The message ID of the recovered item. |
EWS.Items.action | Unknown | The action taken on the item. The value will be 'recovered'. |
#
Command Example#
Human Readable Outputaction | itemId | messageId |
---|---|---|
recovered | AAVCSVS1hN2NkLThmZjdmNTZjNTMxNwBGAAAAAAA4kxh+ed33wX3aBwCyyVyFtlsUQZfBJebinpkUAAAa2bUBAACyyVyFtlscfxxd/AAA= |
#
Context Example#
10. Create a folderCreates a new folder in a specified mailbox.
#
Required PermissionsImpersonation rights are required. To perform actions on the target mailbox of other users, the service account must be part of the ApplicationImpersonation role.
#
Base Commandews-create-folder
#
InputArgument Name | Description | Required |
---|---|---|
new-folder-name | The name of the new folder. | Required |
folder-path | Path to locate the new folder. Exchange folder ID is also supported. | Required |
target-mailbox | The mailbox in which to create the folder. | Optional |
#
Context OutputThere is no context output for this command.
#
Command Example#
Human Readable OutputFolder Inbox\Created Folder created successfully
#
11. Mark an item as junkMarks an item as junk. This is commonly used to block an email address. For more information, see the Microsoft documentation.
#
Required PermissionsImpersonation rights are required. To perform actions on the target mailbox of other users, the service account must be part of the ApplicationImpersonation role.
#
Base Commandews-mark-item-as-junk
#
InputArgument Name | Description | Required |
---|---|---|
item-id | The item ID to mark as junk. | Required |
move-items | Whether to move the item from the original folder to the junk folder. | Optional |
target-mailbox | If empty, will use the default mailbox. If you specify a different mailbox, you might need impersonation rights to the mailbox. | Optional |
#
Context OutputThere is no context output for this command.
#
Command Example#
Human Readable Outputaction | itemId |
---|---|
marked-as-junk | AAMkcSQ0NmFkOhmZjdmNTZjNTMxNwBGAAAAAAA4kxh+ed3JTJPMPXU3wX3aBwCyyVyFtlsUcsBJebinpkUAAAAAAEMASFDkUAAAfxuiSAAA= |
#
Context Example#
12. Search for foldersRetrieves 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 PermissionsImpersonation rights are required. To perform actions on the target mailbox of other users, the service account must be part of the ApplicationImpersonation role.
#
Base Commandews-find-folders
#
InputArgument Name | Description | Required |
---|---|---|
target-mailbox | The mailbox on which to apply the command. | Optional |
is-public | Whether to find Public Folders. | Optional |
#
Context OutputPath | Type | Description |
---|---|---|
EWS.Folders.name | string | Folder name. |
EWS.Folders.id | string | Folder ID. |
EWS.Folders.totalCount | Unknown | Number of items in the folder. |
EWS.Folders.unreadCount | number | Number of unread items in the folder. |
EWS.Folders.changeKey | number | Folder change key. |
EWS.Folders.childrenFolderCount | number | Number of sub-folders. |
#
Command Example#
Human Readable Output#
Context Example#
13. Get items of a folderRetrieves items from a specified folder in a mailbox. The items are ordered by the item created time, most recent is first.
#
Required PermissionsImpersonation rights are required. To perform actions on the target mailbox of other users, the service account must be part of the ApplicationImpersonation role.
#
Base Commandews-get-items-from-folder
#
InputArgument Name | Description | Required |
---|---|---|
folder-path | The folder path from which to get the items. | Required |
limit | Maximum number of items to return. | Optional |
target-mailbox | The mailbox on which to apply the command. | Optional |
is-public | Whether the folder is a Public Folder. Default is 'False'. | Optional |
get-internal-items | If 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 OutputPath | Type | Description |
---|---|---|
EWS.Items.itemId | string | The item ID of the email. |
EWS.Items.hasAttachments | boolean | Whether the email has attachments. |
EWS.Items.datetimeReceived | date | Received time of the email. |
EWS.Items.datetimeSent | date | Sent time of the email. |
EWS.Items.headers | Unknown | Email headers (list). |
EWS.Items.sender | string | Sender mail address of the email. |
EWS.Items.subject | string | Subject of the email. |
EWS.Items.textBody | string | Body of the email (as text). |
EWS.Items.size | number | Email size. |
EWS.Items.toRecipients | Unknown | Email recipients addresses (list). |
EWS.Items.receivedBy | Unknown | Received by address of the email. |
EWS.Items.messageId | string | Email message ID. |
EWS.Items.body | string | Body of the email (as HTML). |
EWS.Items.FileAttachments.attachmentId | unknown | Attachment ID of file attachment. |
EWS.Items.ItemAttachments.attachmentId | unknown | Attachment ID of the item attachment. |
EWS.Items.FileAttachments.attachmentName | unknown | Attachment name of the file attachment. |
EWS.Items.ItemAttachments.attachmentName | unknown | Attachment name of the item attachment. |
EWS.Items.isRead | String | The read status of the email. |
EWS.Items.categories | String | Categories of the email. |
#
Command Example#
Human Readable Outputsender | subject | hasAttachments | datetimeReceived | receivedBy | author | toRecipients | itemId |
---|---|---|---|---|---|---|---|
test2@demistodev.onmicrosoft.com | Get Attachment Email | true | 2019-08-11T10:57:37Z | test@demistodev.onmicrosoft.com | test2@demistodev.onmicrosoft.com | test@demistodev.onmicrosoft.com | AAFSFSFFtlsUQZfBJebinpkUAAABjKMGAACyyVyFtlsUQZfBJebinpkUAAAsfw+jAAA= |
#
Context Example#
14. Get itemsRetrieves items by item ID.
#
Required PermissionsImpersonation rights are required. To perform actions on the target mailbox of other users, the service account must be part of the ApplicationImpersonation role.
#
Base Commandews-get-items
#
InputArgument Name | Description | Required |
---|---|---|
item-ids | A CSV list of item IDs. | Required |
target-mailbox | The mailbox on which to run the command on. | Optional |
#
Context OutputPath | Type | Description |
---|---|---|
EWS.Items.itemId | string | The email item ID. |
EWS.Items.hasAttachments | boolean | Whether the email has attachments. |
EWS.Items.datetimeReceived | date | Received time of the email. |
EWS.Items.datetimeSent | date | Sent time of the email. |
EWS.Items.headers | Unknown | Email headers (list). |
EWS.Items.sender | string | Sender mail address of the email. |
EWS.Items.subject | string | Subject of the email. |
EWS.Items.textBody | string | Body of the email (as text). |
EWS.Items.size | number | Email size. |
EWS.Items.toRecipients | Unknown | Email recipients addresses (list). |
EWS.Items.receivedBy | Unknown | Received by address of the email. |
EWS.Items.messageId | string | Email message ID. |
EWS.Items.body | string | Body of the email (as HTML). |
EWS.Items.FileAttachments.attachmentId | unknown | Attachment ID of the file attachment. |
EWS.Items.ItemAttachments.attachmentId | unknown | Attachment ID of the item attachment. |
EWS.Items.FileAttachments.attachmentName | unknown | Attachment name of the file attachment. |
EWS.Items.ItemAttachments.attachmentName | unknown | Attachment name of the item attachment. |
EWS.Items.isRead | String | The read status of the email. |
EWS.Items.categories | String | Categories of the email. |
Email.CC | String | Email addresses CC'ed to the email. |
Email.BCC | String | Email addresses BCC'ed to the email. |
Email.To | String | The recipient of the email. |
Email.From | String | The sender of the email. |
Email.Subject | String | The subject of the email. |
Email.Text | String | The plain-text version of the email. |
Email.HTML | String | The HTML version of the email. |
Email.HeadersMap | String | The headers of the email. |
#
Command Example#
Human Readable OutputIdentical outputs to ews-get-items-from-folder
command.
#
15. Move an item to a different mailboxMoves an item from one mailbox to a different mailbox.
#
Required PermissionsImpersonation rights are required. To perform actions on the target mailbox of other users, the service account must be part of the ApplicationImpersonation role.
#
Base Commandews-move-item-between-mailboxes
#
InputArgument Name | Description | Required |
---|---|---|
item-id | The item ID to move. | Required |
destination-folder-path | The folder in the destination mailbox to which to move the item. You can specify a complex path, for example, "Inbox\Phishing". | Required |
destination-mailbox | The mailbox to which to move the item. | Required |
source-mailbox | The mailbox from which to move the item (conventionally called the "target-mailbox", the target mailbox on which to run the command). | Optional |
is-public | Whether the destination folder is a Public Folder. Default is "False". | Optional |
#
Context OutputPath | Type | Description |
---|---|---|
EWS.Items.movedToMailbox | string | The mailbox to which the item was moved. |
EWS.Items.movedToFolder | string | The folder to which the item was moved. |
EWS.Items.action | string | The action taken on the item. The value will be "moved". |
#
Command Example#
Human Readable OutputItem was moved successfully.
#
Context Example#
16. Get a folderRetrieves a single folder.
#
Required PermissionsImpersonation rights are required. To perform actions on the target mailbox of other users, the service account must be part of the ApplicationImpersonation role.
#
Base Commandews-get-folder
#
InputArgument Name | Description | Required |
---|---|---|
target-mailbox | The mailbox on which to apply the search. | Optional |
folder-path | The path of the folder to retrieve. If empty, will retrieve the folder "AllItems". | Optional |
is-public | Whether the folder is a Public Folder. Default is "False". | Optional |
#
Context OutputPath | Type | Description |
---|---|---|
EWS.Folders.id | string | Folder ID. |
EWS.Folders.name | string | Folder name. |
EWS.Folders.changeKey | string | Folder change key. |
EWS.Folders.totalCount | number | Total number of emails in the folder. |
EWS.Folders.childrenFolderCount | number | Number of sub-folders. |
EWS.Folders.unreadCount | number | Number of unread emails in the folder. |
#
Command Example#
Human Readable OutputchangeKey | childrenFolderCount | id | name | totalCount | unreadCount |
---|---|---|---|---|---|
***yFtCdJSH | 0 | AAMkADQ0NmFkODFkLWQ4MDEtNDE4Mi1hN2NlsjflsjfSF= | demistoEmail | 1 | 0 |
#
Context Example#
17. Expand a distribution listExpands 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 PermissionsImpersonation 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 Commandews-expand-group
#
InputArgument Name | Description | Required |
---|---|---|
email-address | Email address of the group to expand. | Required |
recursive-expansion | Whether to enable recursive expansion. Default is "False". | Optional |
#
Context OutputThere is no context output for this command.
#
Command Example#
Human Readable OutputdisplayName | mailbox | mailboxType |
---|---|---|
John Wick | john@wick.com | Mailbox |
#
Context Example#
18. Mark items as readMarks items as read or unread.
#
Required PermissionsImpersonation rights are required. To perform actions on the target mailbox of other users, the service account must be part of the ApplicationImpersonation role.
#
Base Commandews-mark-items-as-read
#
InputArgument Name | Description | Required |
---|---|---|
item-ids | A CSV list of item IDs. | Required |
operation | How to mark the item. Can be "read" or "unread". Default is "read". | Optional |
target-mailbox | The mailbox on which to run the command. If empty, the command will be applied on the default mailbox. | Optional |
#
Context OutputPath | Type | Description |
---|---|---|
EWS.Items.action | String | The action that was performed on the item. |
EWS.Items.itemId | String | The ID of the item. |
EWS.Items.messageId | String | The message ID of the item. |
#
Command Example#
Human Readable Outputaction | itemId | messageId |
---|---|---|
marked-as-read | AAMkADQ0NFSffU3wX3aBwCyyVyFtlsUQZfBJebinpkUAAABjKMnpkUAAAfxw+jAAA= |
#
Context Example#
19. Send an email#
Required PermissionsImpersonation rights are required. To perform actions on the target mailbox of other users, the service account must be part of the ApplicationImpersonation role.
#
Base Commandsend-mail
#
InputArgument Name | Description | Required |
---|---|---|
to | Email addresses for the 'To' field. Supports comma-separated values | Optional |
cc | Email addresses for the 'Cc' field. Supports comma-separated values | Optional |
bcc | Email addresses for the 'Bcc' field. Supports comma-separated values | Optional |
subject | Subject for the email to be sent | Optional |
body | The contents (body) of the email to be sent in plain text | Optional |
htmlBody | The contents (body) of the email to be sent in HTML format | Optional |
attachIDs | A comma-separated list of IDs of war room entries that contains the files that should be attached to the email | Optional |
attachNames | A 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 |
attachCIDs | A comma-separated list of CIDs to embed attachments inside the email itself | Optional |
transientFile | Desired 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 |
transientFileContent | Content 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 |
transientFileCID | CID 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 |
templateParams | Replace {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 from. Note that only context data is accessible for this argument, while incident fields are not. | Optional |
additionalHeader | A comma-separated list list of additional headers in the format: headerName=headerValue. For example: "headerName1=headerValue1,headerName2=headerValue2". | Optional |
raw_message | Raw email message to send. If provided, all other arguments, but to, cc and bcc, will be ignored. | Optional |
from_address | The email address from which to reply. | Optional |
replyTo | Email addresses that need to be used to reply to the message. Supports comma-separated values. | Optional |
importance | Sets the importance/Priority of the email. Default value is Normal. | Optional |
#
Context OutputThere is no context output for this command.
#
Command Example#
Human Readable OutputMail sent successfully
#
20. ews-get-items-as-emlRetrieves items by item ID and uploads its content as an EML file.
#
Base Commandews-get-items-as-eml
#
InputArgument Name | Description | Required |
---|---|---|
item-id | The item ID of item to upload as and EML file. | Required |
target-mailbox | The 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 OutputPath | Type | Description |
---|---|---|
File.Size | String | The size of the file. |
File.SHA1 | String | The SHA1 hash of the file. |
File.SHA256 | String | The SHA256 hash of the file. |
File.SHA512 | String | The SHA512 hash of the file. |
File.Name | String | The name of the file. |
File.SSDeep | String | The SSDeep hash of the file. |
File.EntryID | String | EntryID of the file |
File.Info | String | Information about the file. |
File.Type | String | The file type. |
File.MD5 | String | The MD5 hash of the file. |
File.Extension | String | The extension of the file. |
#
21. reply-mail#
Required PermissionsImpersonation rights are required. To perform actions on the target mailbox of other users, the service account must be part of the ApplicationImpersonation role.
#
Base Commandreply-mail
#
InputArgument Name | Description | Required |
---|---|---|
inReplyTo | ID of the item to reply to. | Required |
to | A comma-separated list of email addresses for the 'to' field. | Required |
cc | A comma-separated list of email addresses for the 'cc' field. | Optional |
bcc | A comma-separated list of email addresses for the 'bcc' field. | Optional |
subject | Subject for the email to be sent. | Optional |
body | The contents (body) of the email to send. | Optional |
htmlBody | HTML formatted content (body) of the email to be sent. This argument overrides the "body" argument. | Optional |
attachIDs | A comma-separated list of War Room entry IDs that contain files, and are used to attach files to the outgoing email. For example: attachIDs=15@8,19@8. | Optional |
attachNames | A comma-separated list of names of attachments to send. Should be the same number of elements as attachIDs. | Optional |
attachCIDs | A comma-separated list of CIDs to embed attachments within the email itself. | Optional |
#
Context OutputThere 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
attachments from subject to avishai@demistodev.onmicrosoft.com hi avishai@demistodev.onmicrosoft.com
#
Additional Information#
EWS PermissionsTo 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.
Permission | Use Case | How to Configure |
---|---|---|
Delegate | One-to-one relationship between users. | Read moreĀ here. |
Impersonation | A single account needs to access multiple mailboxes. | Read moreĀ here. |
eDiscovery | Search the Exchange server. | Read moreĀ here. |
Compliance Search | Perform searches across mailboxes and get an estimate of the results. | Read moreĀ here. |