The Exchange connector provides a robust, platform-independent, and simple interface for communicating with Microsoft Exchange 2007-2016 Server or Office 365 using Exchange Web Services (EWS).
This document provides information about the Exchange connector, which facilitates automated interactions, with an Exchange server using FortiSOAR™ playbooks. Add the Exchange connector as a step in FortiSOAR™ playbooks and perform automated operations, such as retrieving unread emails, moving or deleting emails from the Exchange server, sending an email from the Exchange server, or running a query on the Exchange server based on the parameter (s) that you have specified.
Connector Version: 3.1.0
FortiSOAR™ Version Tested on: 4.12.1-253
Exchange Version Tested on: Microsoft Exchange 2007-2016 Server or Office 365
Authored By: Fortinet
Certified: Yes
Following enhancements have been made to the Exchange Connector in version 3.1.0:
Note: The configuration parameters for the Exchange Connector in version 3.0.0 and later is different from the earlier versions, therefore, in this case, the previous version, prior to version 3.0.0, of the connector does not get replaced, thereby storing the previous configuration of the Exchange connector. You will, therefore, have both the previous version and the current version of the connector in your FortiSOAR™ system.
All connectors provided by FortiSOAR™ are delivered using a FortiSOAR™ repository. Therefore, you must set up your FortiSOAR™ repository and use the yum
command to install connectors:
yum install cyops-connector-exchange
For the detailed procedure to install a connector, click here.
For the procedure to configure a connector, click here.
In FortiSOAR™, on the Connectors page, click the Exchange connector row, and in the Configuration tab enter the required configuration details.
Parameter | Description |
---|---|
Host | Hostname of the Exchange server to which you will connect and perform the automated operations. Note: For Office365, add the host as outlook.office365.com . |
Username | Username to access the Exchange server/Office 365 server. For Exchange, add the username in the format: Domain\Username . |
Password | Password to access the Exchange server. |
Email Address | Email address of the Exchange server that you are using. |
Access Type | (Optional) Access type for the user. You can choose between Delegate or Impersonation By default, this is set as Delegate. |
Protocol | Protocol that will be used to communicate with the Exchange server/Office 365 server. Choose either http and https. By default, this is set to https. |
Use Autodiscover | An alias account will work for the given account details. Defaults to False . |
Verify SSL | Specifies whether the SSL certificate for the server is to be verified or not. Defaults to True . |
Enable Email Notification Service | Select this option, i.e., set it to True (default) to set up a listener that would instantly notify FortiSOAR™ whenever a new email arrives in the mailbox. Once you select this options, the following parameters get populate:
|
The following automated operations can be included in playbooks, and you can also use the annotations to access operations from FortiSOAR™ release 4.10.0 onwards:
Function | Description | Annotation and Category |
---|---|---|
Create Calendar Event | Creates an event in a calendar on the Exchange Server, based on input parameters, such as subject, from date and to date, you have specified. | create_event Investigation |
Get Calendar Events | Gets events from the calendar on the Exchange server, based on the filter criteria, such as subject, from time, and to time, you have specified. | get_events Investigation |
Get Contacts | Gets the contact list from the mailbox on the Exchange server. | get_contacts Investigation |
Delete Email | Deletes an email from a specified folder on the Exchange server, based on the input parameters, such as message ID and delete type, you have specified. | delete_email Investigation |
Get Unread Emails | Gets all unread emails from the Exchange server. You can also mark the retrieved Unread emails as Read. | get_email Investigation |
Mark Email as Read | Marks an unread email as read on the Exchange Server, based on the message ID you have specified. | mark_as_read Investigation |
Move Email | Moves an email from a specified folder to a specified folder, based on the message ID and the source and destination folder you have specified. | move_email Miscellaneous |
Search Email | Runs a query on the Exchange server and searches emails, based on input parameters, such as folder name, email address, body, and subject, that you have specified. | search_query Investigation |
Send Email | Sends an email from the Exchange server. | send_email Investigation |
Parameter | Description |
---|---|
Subject | Subject line of the event that you want to create on the Exchange server. |
Start Date | Start date and time of the event that you want to create on the Exchange server. |
End Date | End date and time of the event that you want to create on the Exchange server. |
Required Attendees | Email IDs of the members who are required to attend the event. You must add the email IDs in the CSV or list format. For example, @xyz.com, def@lmn.com |
Optional Attendees | (Optional) Email IDs of the optional members who can attend the event. You must add the email IDs in the CSV or list format. |
Body | (Optional) Details of the event that you want to create on the Exchange server. |
Location | (Optional) Location of the event that you want to create on the Exchange server. |
Categories | (Optional) Category of the event that you want to create on the Exchange server. You must add the categories in the CSV or list format. For example, Blue category, Green Category, etc. |
Show As | (Optional) Status of the attendees when they are attending this event. You can choose one of the following options: Free, Working elsewhere, Tentative, Busy, or OOF. |
Reminder | (Optional) Time before the event starts when you want to set a reminder for the attendees. You can choose one of the following options: 0 minutes, 5 minutes, 10 minutes, 15 minutes, 30 minutes, 1 hour, 2 hour, 3 hour, 4 hour, 8 hour, 12 hour, 1 day, 2 day, 3 day, 1 week, or 2 week. |
Is All Day | If you select this option, i.e., set it to True , then this sets the event as a full-day event.By default, this is set to False . |
Is Private | If you select this option, i.e., set it to True , then this sets the event as a private event, and it can be viewed only by its attendees.By default, this is set to True . |
The JSON output contains the status of the create calendar event operation. The JSON output returns a Success
message if the calendar event is successfully added on the Exchange server or an Error
message containing the reason for failure.
The output contains the following populated JSON schema:
{
"message": ""
}
Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criteria is applied, and an unfiltered list is returned.
Parameter | Description |
---|---|
Subject | Subject text based on which you want to filter events on the Exchange server. |
From Time | Start date and time from when you want to retrieve events from the Exchange server. |
To Time | End date and time till when you want to retrieve events from the Exchange server. |
The JSON output contains the retrieved events from the calendar on the Exchange server, based on the input parameters you have specified.
The output contains the following populated JSON schema:
{
"Organizer": "",
"Importance": "",
"Required attendees": [],
"End": "",
"Attachments": [
{
"size": "",
"Name": "",
"content_type": ""
}
],
"Legacy status": "",
"Location": "",
"Reminder minutes before start": "",
"Subject": "",
"Reminder is set": "",
"sensitivity": "",
"Is all day": "",
"Start": "",
"Categories": [],
"Body": "",
"Optional attendees": []
}
None.
The JSON output contains the retrieved contact list from the mailbox on the Exchange server.
The output contains the following populated JSON schema:
{
"CLASS": "",
"TEL": "",
"PRODID": "",
"FN": "",
"N": "",
"EMAIL": "",
"MAILER": "",
"REV": "",
"LABEL": "",
"VERSION": "",
"ADR": "",
"ORG": ""
}
Parameter | Description |
---|---|
Message ID | ID of the email that you want to delete. |
Delete Type | Type of Delete that you want to use to delete the email. You can choose from the following options: Soft Delete, Hard Delete, or Move To Trash. |
Folder Name | (Optional) Folder on the Exchange server from which you want to delete the email. By default, this is set as Inbox. |
The JSON output contains the status of the delete operation. The JSON output returns a Success
message if the email is successfully deleted from the Exchange server or an Error
message containing the reason for failure.
The output contains the following populated JSON schema:
{
"message": ""
}
Parameter | Description |
---|---|
Source | Select the source folder from which you want to retrieve unread emails from the Exchange server. You can choose from Inbox, Sent, Drafts, Trash, Custom Folder. By default, this is set as Inbox. If you select Custom Folder, then you must specify the folder on the Exchange server from which you want to retrieve unread emails. |
Mark as Read | Select this option, i.e., set it to True (default) , to retrieve the unread emails from the Exchange server and also marks these emails as Read.By default, this is set to True . |
Parse Inline Images | Select this option, i.e., set it to True , to retrieve the body of the unread emails including inline images, from the Exchange server. By default, this is set to False (option is unchecked). |
Save Email | Select this option, i.e., set it to True (default) to save the email as a file in the FortiSOAR™ Attachment module. |
Extract Attachment Data | Select this option, i.e., set it to True (default), to extracts the attachment data if the type of the attachment is eml or msg . |
The JSON contains details of all the unread emails retrieved from the Exchange server.
The output contains the following populated JSON schema:
{
"email_as_attachment": "",
"parsed_attachment_data": [],
"attachments": [
{
"file": "",
"json": "",
"text": "",
"metadata": {
"content_length": "",
"filename": "",
"sha256": "",
"content_type": "",
"sha1": "",
"md5": ""
}
}
],
"epilogue": "",
"item_id": "",
"attachment_files": [],
"preamble": "",
"headers": {
"X-MS-Exchange-Transport-CrossTenantHeadersStamped": "",
"X-MS-TrafficTypeDiagnostic": "",
"Auto-Submitted": "",
"X-MS-Exchange-CrossTenant-Network-Message-Id": "",
"X-Exchange-Antispam-Report-Test": "",
"X-Forefront-Antispam-Report": "",
"From": "",
"X-MS-Exchange-Organization-MessageDirectionality": "",
"X-Microsoft-Antispam-Message-Info": [],
"Subject": "",
"X-Microsoft-Antispam": "",
"MIME-Version": "",
"Reply-To": "",
"X-MS-Exchange-Organization-Network-Message-Id": "",
"X-MS-Exchange-CrossTenant-OriginalArrivalTime": "",
"Authentication-Results": "",
"SpamDiagnosticOutput": "",
"X-Google-Smtp-Source": "",
"X-Received": "",
"X-MS-Exchange-Transport-EndToEndLatency": "",
"X-EOPAttributedMessage": "",
"X-MS-Exchange-Organization-AuthAs": "",
"Return-Path": "",
"X-MS-PublicTrafficType": "",
"SpamDiagnosticMetadata": "",
"X-MS-Exchange-Organization-AuthSource": "",
"Received": [],
"X-MS-Exchange-Organization-SCL": "",
"X-EOPTenantAttributedMessage": "",
"X-Exchange-Antispam-Report-CFA-Test": "",
"X-Google-DKIM-Signature": "",
"X-MS-Office365-Filtering-Correlation-Id": "",
"Content-Type": "",
"DKIM-Signature": [],
"X-MS-Exchange-Processed-By-BccFoldering": "",
"Sender": "",
"Received-SPF": "",
"X-Gm-Message-State": "",
"X-MS-Exchange-CrossTenant-FromEntityHeader": "",
"Message-ID": "",
"X-Microsoft-Exchange-Diagnostics": [],
"To": "",
"X-MS-Exchange-CrossTenant-Id": ""
},
"body": {
"html": "",
"json": "",
"text": ""
}
}
Parameter | Description |
---|---|
Message ID | ID of the email that you want to mark as read. |
Folder Name | (Optional) Name of the folder name that contains the email message that you want to mark as read. |
The JSON output contains the status of the "mark email as read" operation. The JSON output returns a Success
message if the specified email is successfully marked as read on the Exchange server or an Error
message containing the reason for failure.
The output contains the following populated JSON schema:
{
"message": ""
}
Parameter | Description |
---|---|
Message ID | ID of the email that you want to move. |
Source Folder | Source folder on the Exchange server from where you want to move the email. |
Destination Folder | Destination folder on the Exchange server to which you want to move the email. |
The JSON output contains the status of the move operation. The JSON output returns a Success
message if the email is successfully moved as per your specifications on the Exchange server or an Error
message containing the reason for failure.
The output contains the following populated JSON schema:
{
"message": ""
}
Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criteria is applied, and an unfiltered list is returned.
Parameter | Description |
---|---|
Subject | Subject of the email message based on which you want to search emails on the Exchange server. |
Body | Content within the body of the email based on which you want to search emails on the Exchange server. |
Sender | Email address of the sender based on which you want to search emails on the Exchange server. |
Email Range | Maximum number of emails that you want to display in the output based on your search criteria. If you do not specify the range, then all the emails based on your search criteria are displayed. |
Folder Name | Folder on the Exchange server based on which you want to search emails on the Exchange server. |
Parse Inline Images
|
Select this option, i.e., set it to True , to retrieve the body of the emails including inline images, from the Exchange server. By default, this is set to False (option is unchecked). |
Query | Search parameters based on which you want to search emails on the Exchange server in the form of a query. Accepts input in the dictionary format. For example, {'subject__icontains' : '365', 'datetime_received__gt' : '2018-01-20T18:30:00.000Z'} You can also provide options such as: subject__exact='foo' // Returns items where subject is 'foo'. Same as filter(subject='foo' ),subject__iexact='foo' // Returns items where subject is 'foo', 'FOO' or 'Foo',subject_contains='foo' //Returns items where subject contains 'foo',subject_icontains , subject_startswith , and subject_istartswith . |
The JSON output contains the details of all emails that match with the search criteria that you have specified.
The output contains the following populated JSON schema:
{
"search_fields": "",
"emails": [
{
"file": "",
"attachments": [
{
"file": "",
"json": "",
"text": "",
"metadata": {
"content_length": "",
"filename": "",
"sha256": "",
"content_type": "",
"sha1": "",
"md5": ""
}
}
],
"raw": "",
"item_id": "",
"attachment_files": [],
"epilogue": "",
"preamble": "",
"headers": {
"X-MS-Exchange-Transport-CrossTenantHeadersStamped": "",
"X-MS-TrafficTypeDiagnostic": "",
"Auto-Submitted": "",
"X-MS-Exchange-CrossTenant-Network-Message-Id": "",
"X-Exchange-Antispam-Report-Test": "",
"X-Forefront-Antispam-Report": "",
"From": "",
"X-MS-Exchange-Organization-MessageDirectionality": "",
"X-Microsoft-Antispam-Message-Info": [],
"Subject": "",
"X-Microsoft-Antispam": "",
"MIME-Version": "",
"Reply-To": "",
"X-MS-Exchange-Organization-Network-Message-Id": "",
"X-MS-Exchange-CrossTenant-OriginalArrivalTime": "",
"Authentication-Results": "",
"SpamDiagnosticOutput": "",
"X-Google-Smtp-Source": "",
"X-Received": "",
"X-MS-Exchange-Transport-EndToEndLatency": "",
"X-EOPAttributedMessage": "",
"X-MS-Exchange-Organization-AuthAs": "",
"Return-Path": "",
"X-MS-PublicTrafficType": "",
"SpamDiagnosticMetadata": "",
"X-MS-Exchange-Organization-AuthSource": "",
"Received": [],
"X-MS-Exchange-Organization-SCL": "",
"X-EOPTenantAttributedMessage": "",
"X-Exchange-Antispam-Report-CFA-Test": "",
"X-Google-DKIM-Signature": "",
"X-MS-Office365-Filtering-Correlation-Id": "",
"Content-Type": "",
"DKIM-Signature": [],
"X-MS-Exchange-Processed-By-BccFoldering": "",
"Sender": "",
"Received-SPF": "",
"X-Gm-Message-State": "",
"X-MS-Exchange-CrossTenant-FromEntityHeader": "",
"Message-ID": "",
"X-Microsoft-Exchange-Diagnostics": [],
"To": "",
"X-MS-Exchange-CrossTenant-Id": ""
},
"body": {
"html": "",
"json": "",
"text": ""
}
}
]
}
Important: For this operation to work, you must have the FortiSOAR™ Built-in connector "cyops_utilities" (minimum version required is 2.0.1) installed on your system. For more information on FortiSOAR™ Built-in connectors, see FortiSOAR™ product documentation.
Parameter | Description |
---|---|
Subject | (Optional) Subject of the email message that you want to send from the Exchange server. |
TO Recipients | Email IDs of the members to whom you want to send the email message from the Exchange server. You must add the email IDs in the CSV or list format. For example, abc@xyz.com, def@lmn.com Important: You must specify email ID(s) in at least one of the following fields: TO Recipients, CC Recipients, or BCC Recipients. |
CC Recipients | Email IDs of the members to be added to the CC list of the email message that you want to send from the Exchange server. You must add the email IDs in the CSV or list format. |
BCC Recipients | Email IDs of the members to be added to the BCC list of the email message that you want to send from the Exchange server. You must add the email IDs in the CSV or list format. |
Body | (Optional) Message or content of the email that you want to send from the Exchange server. |
Attachment IRIs | (Optional) List of IRI ID(s) of the file (s) that you want to attach to the email that you want to send from the Exchange server. IRI IDs are used to access files from the FortiSOAR™Attachments module. You must add the Attachment IRIs in the CSV or list format. |
Inline Attachment IRIs | (Optional) List of IRI ID(s) of the file (s) that you want to add inline to the email that you want to send from the Exchange server. You can add the image content inline in the email body using its UUIDs. For example, <img src="cid%3Adfe26867-01a1-4969-8168-8c8882586538"> |
The JSON output contains the status of the send email operation. The JSON output returns a Success
message if the email is successfully sent from the Exchange server or an Error
message containing the reason for failure.
The output contains the following populated JSON schema:
{
"message": ""
}
The Sample - Exchange - 3.1.0
playbook collection comes bundled with the Exchange connector. This playbook contains steps using which you can perform all supported actions. You can see the bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the Exchange connector.
Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during connector upgrade and delete.
The Exchange connector provides a robust, platform-independent, and simple interface for communicating with Microsoft Exchange 2007-2016 Server or Office 365 using Exchange Web Services (EWS).
This document provides information about the Exchange connector, which facilitates automated interactions, with an Exchange server using FortiSOAR™ playbooks. Add the Exchange connector as a step in FortiSOAR™ playbooks and perform automated operations, such as retrieving unread emails, moving or deleting emails from the Exchange server, sending an email from the Exchange server, or running a query on the Exchange server based on the parameter (s) that you have specified.
Connector Version: 3.1.0
FortiSOAR™ Version Tested on: 4.12.1-253
Exchange Version Tested on: Microsoft Exchange 2007-2016 Server or Office 365
Authored By: Fortinet
Certified: Yes
Following enhancements have been made to the Exchange Connector in version 3.1.0:
Note: The configuration parameters for the Exchange Connector in version 3.0.0 and later is different from the earlier versions, therefore, in this case, the previous version, prior to version 3.0.0, of the connector does not get replaced, thereby storing the previous configuration of the Exchange connector. You will, therefore, have both the previous version and the current version of the connector in your FortiSOAR™ system.
All connectors provided by FortiSOAR™ are delivered using a FortiSOAR™ repository. Therefore, you must set up your FortiSOAR™ repository and use the yum
command to install connectors:
yum install cyops-connector-exchange
For the detailed procedure to install a connector, click here.
For the procedure to configure a connector, click here.
In FortiSOAR™, on the Connectors page, click the Exchange connector row, and in the Configuration tab enter the required configuration details.
Parameter | Description |
---|---|
Host | Hostname of the Exchange server to which you will connect and perform the automated operations. Note: For Office365, add the host as outlook.office365.com . |
Username | Username to access the Exchange server/Office 365 server. For Exchange, add the username in the format: Domain\Username . |
Password | Password to access the Exchange server. |
Email Address | Email address of the Exchange server that you are using. |
Access Type | (Optional) Access type for the user. You can choose between Delegate or Impersonation By default, this is set as Delegate. |
Protocol | Protocol that will be used to communicate with the Exchange server/Office 365 server. Choose either http and https. By default, this is set to https. |
Use Autodiscover | An alias account will work for the given account details. Defaults to False . |
Verify SSL | Specifies whether the SSL certificate for the server is to be verified or not. Defaults to True . |
Enable Email Notification Service | Select this option, i.e., set it to True (default) to set up a listener that would instantly notify FortiSOAR™ whenever a new email arrives in the mailbox. Once you select this options, the following parameters get populate:
|
The following automated operations can be included in playbooks, and you can also use the annotations to access operations from FortiSOAR™ release 4.10.0 onwards:
Function | Description | Annotation and Category |
---|---|---|
Create Calendar Event | Creates an event in a calendar on the Exchange Server, based on input parameters, such as subject, from date and to date, you have specified. | create_event Investigation |
Get Calendar Events | Gets events from the calendar on the Exchange server, based on the filter criteria, such as subject, from time, and to time, you have specified. | get_events Investigation |
Get Contacts | Gets the contact list from the mailbox on the Exchange server. | get_contacts Investigation |
Delete Email | Deletes an email from a specified folder on the Exchange server, based on the input parameters, such as message ID and delete type, you have specified. | delete_email Investigation |
Get Unread Emails | Gets all unread emails from the Exchange server. You can also mark the retrieved Unread emails as Read. | get_email Investigation |
Mark Email as Read | Marks an unread email as read on the Exchange Server, based on the message ID you have specified. | mark_as_read Investigation |
Move Email | Moves an email from a specified folder to a specified folder, based on the message ID and the source and destination folder you have specified. | move_email Miscellaneous |
Search Email | Runs a query on the Exchange server and searches emails, based on input parameters, such as folder name, email address, body, and subject, that you have specified. | search_query Investigation |
Send Email | Sends an email from the Exchange server. | send_email Investigation |
Parameter | Description |
---|---|
Subject | Subject line of the event that you want to create on the Exchange server. |
Start Date | Start date and time of the event that you want to create on the Exchange server. |
End Date | End date and time of the event that you want to create on the Exchange server. |
Required Attendees | Email IDs of the members who are required to attend the event. You must add the email IDs in the CSV or list format. For example, @xyz.com, def@lmn.com |
Optional Attendees | (Optional) Email IDs of the optional members who can attend the event. You must add the email IDs in the CSV or list format. |
Body | (Optional) Details of the event that you want to create on the Exchange server. |
Location | (Optional) Location of the event that you want to create on the Exchange server. |
Categories | (Optional) Category of the event that you want to create on the Exchange server. You must add the categories in the CSV or list format. For example, Blue category, Green Category, etc. |
Show As | (Optional) Status of the attendees when they are attending this event. You can choose one of the following options: Free, Working elsewhere, Tentative, Busy, or OOF. |
Reminder | (Optional) Time before the event starts when you want to set a reminder for the attendees. You can choose one of the following options: 0 minutes, 5 minutes, 10 minutes, 15 minutes, 30 minutes, 1 hour, 2 hour, 3 hour, 4 hour, 8 hour, 12 hour, 1 day, 2 day, 3 day, 1 week, or 2 week. |
Is All Day | If you select this option, i.e., set it to True , then this sets the event as a full-day event.By default, this is set to False . |
Is Private | If you select this option, i.e., set it to True , then this sets the event as a private event, and it can be viewed only by its attendees.By default, this is set to True . |
The JSON output contains the status of the create calendar event operation. The JSON output returns a Success
message if the calendar event is successfully added on the Exchange server or an Error
message containing the reason for failure.
The output contains the following populated JSON schema:
{
"message": ""
}
Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criteria is applied, and an unfiltered list is returned.
Parameter | Description |
---|---|
Subject | Subject text based on which you want to filter events on the Exchange server. |
From Time | Start date and time from when you want to retrieve events from the Exchange server. |
To Time | End date and time till when you want to retrieve events from the Exchange server. |
The JSON output contains the retrieved events from the calendar on the Exchange server, based on the input parameters you have specified.
The output contains the following populated JSON schema:
{
"Organizer": "",
"Importance": "",
"Required attendees": [],
"End": "",
"Attachments": [
{
"size": "",
"Name": "",
"content_type": ""
}
],
"Legacy status": "",
"Location": "",
"Reminder minutes before start": "",
"Subject": "",
"Reminder is set": "",
"sensitivity": "",
"Is all day": "",
"Start": "",
"Categories": [],
"Body": "",
"Optional attendees": []
}
None.
The JSON output contains the retrieved contact list from the mailbox on the Exchange server.
The output contains the following populated JSON schema:
{
"CLASS": "",
"TEL": "",
"PRODID": "",
"FN": "",
"N": "",
"EMAIL": "",
"MAILER": "",
"REV": "",
"LABEL": "",
"VERSION": "",
"ADR": "",
"ORG": ""
}
Parameter | Description |
---|---|
Message ID | ID of the email that you want to delete. |
Delete Type | Type of Delete that you want to use to delete the email. You can choose from the following options: Soft Delete, Hard Delete, or Move To Trash. |
Folder Name | (Optional) Folder on the Exchange server from which you want to delete the email. By default, this is set as Inbox. |
The JSON output contains the status of the delete operation. The JSON output returns a Success
message if the email is successfully deleted from the Exchange server or an Error
message containing the reason for failure.
The output contains the following populated JSON schema:
{
"message": ""
}
Parameter | Description |
---|---|
Source | Select the source folder from which you want to retrieve unread emails from the Exchange server. You can choose from Inbox, Sent, Drafts, Trash, Custom Folder. By default, this is set as Inbox. If you select Custom Folder, then you must specify the folder on the Exchange server from which you want to retrieve unread emails. |
Mark as Read | Select this option, i.e., set it to True (default) , to retrieve the unread emails from the Exchange server and also marks these emails as Read.By default, this is set to True . |
Parse Inline Images | Select this option, i.e., set it to True , to retrieve the body of the unread emails including inline images, from the Exchange server. By default, this is set to False (option is unchecked). |
Save Email | Select this option, i.e., set it to True (default) to save the email as a file in the FortiSOAR™ Attachment module. |
Extract Attachment Data | Select this option, i.e., set it to True (default), to extracts the attachment data if the type of the attachment is eml or msg . |
The JSON contains details of all the unread emails retrieved from the Exchange server.
The output contains the following populated JSON schema:
{
"email_as_attachment": "",
"parsed_attachment_data": [],
"attachments": [
{
"file": "",
"json": "",
"text": "",
"metadata": {
"content_length": "",
"filename": "",
"sha256": "",
"content_type": "",
"sha1": "",
"md5": ""
}
}
],
"epilogue": "",
"item_id": "",
"attachment_files": [],
"preamble": "",
"headers": {
"X-MS-Exchange-Transport-CrossTenantHeadersStamped": "",
"X-MS-TrafficTypeDiagnostic": "",
"Auto-Submitted": "",
"X-MS-Exchange-CrossTenant-Network-Message-Id": "",
"X-Exchange-Antispam-Report-Test": "",
"X-Forefront-Antispam-Report": "",
"From": "",
"X-MS-Exchange-Organization-MessageDirectionality": "",
"X-Microsoft-Antispam-Message-Info": [],
"Subject": "",
"X-Microsoft-Antispam": "",
"MIME-Version": "",
"Reply-To": "",
"X-MS-Exchange-Organization-Network-Message-Id": "",
"X-MS-Exchange-CrossTenant-OriginalArrivalTime": "",
"Authentication-Results": "",
"SpamDiagnosticOutput": "",
"X-Google-Smtp-Source": "",
"X-Received": "",
"X-MS-Exchange-Transport-EndToEndLatency": "",
"X-EOPAttributedMessage": "",
"X-MS-Exchange-Organization-AuthAs": "",
"Return-Path": "",
"X-MS-PublicTrafficType": "",
"SpamDiagnosticMetadata": "",
"X-MS-Exchange-Organization-AuthSource": "",
"Received": [],
"X-MS-Exchange-Organization-SCL": "",
"X-EOPTenantAttributedMessage": "",
"X-Exchange-Antispam-Report-CFA-Test": "",
"X-Google-DKIM-Signature": "",
"X-MS-Office365-Filtering-Correlation-Id": "",
"Content-Type": "",
"DKIM-Signature": [],
"X-MS-Exchange-Processed-By-BccFoldering": "",
"Sender": "",
"Received-SPF": "",
"X-Gm-Message-State": "",
"X-MS-Exchange-CrossTenant-FromEntityHeader": "",
"Message-ID": "",
"X-Microsoft-Exchange-Diagnostics": [],
"To": "",
"X-MS-Exchange-CrossTenant-Id": ""
},
"body": {
"html": "",
"json": "",
"text": ""
}
}
Parameter | Description |
---|---|
Message ID | ID of the email that you want to mark as read. |
Folder Name | (Optional) Name of the folder name that contains the email message that you want to mark as read. |
The JSON output contains the status of the "mark email as read" operation. The JSON output returns a Success
message if the specified email is successfully marked as read on the Exchange server or an Error
message containing the reason for failure.
The output contains the following populated JSON schema:
{
"message": ""
}
Parameter | Description |
---|---|
Message ID | ID of the email that you want to move. |
Source Folder | Source folder on the Exchange server from where you want to move the email. |
Destination Folder | Destination folder on the Exchange server to which you want to move the email. |
The JSON output contains the status of the move operation. The JSON output returns a Success
message if the email is successfully moved as per your specifications on the Exchange server or an Error
message containing the reason for failure.
The output contains the following populated JSON schema:
{
"message": ""
}
Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criteria is applied, and an unfiltered list is returned.
Parameter | Description |
---|---|
Subject | Subject of the email message based on which you want to search emails on the Exchange server. |
Body | Content within the body of the email based on which you want to search emails on the Exchange server. |
Sender | Email address of the sender based on which you want to search emails on the Exchange server. |
Email Range | Maximum number of emails that you want to display in the output based on your search criteria. If you do not specify the range, then all the emails based on your search criteria are displayed. |
Folder Name | Folder on the Exchange server based on which you want to search emails on the Exchange server. |
Parse Inline Images
|
Select this option, i.e., set it to True , to retrieve the body of the emails including inline images, from the Exchange server. By default, this is set to False (option is unchecked). |
Query | Search parameters based on which you want to search emails on the Exchange server in the form of a query. Accepts input in the dictionary format. For example, {'subject__icontains' : '365', 'datetime_received__gt' : '2018-01-20T18:30:00.000Z'} You can also provide options such as: subject__exact='foo' // Returns items where subject is 'foo'. Same as filter(subject='foo' ),subject__iexact='foo' // Returns items where subject is 'foo', 'FOO' or 'Foo',subject_contains='foo' //Returns items where subject contains 'foo',subject_icontains , subject_startswith , and subject_istartswith . |
The JSON output contains the details of all emails that match with the search criteria that you have specified.
The output contains the following populated JSON schema:
{
"search_fields": "",
"emails": [
{
"file": "",
"attachments": [
{
"file": "",
"json": "",
"text": "",
"metadata": {
"content_length": "",
"filename": "",
"sha256": "",
"content_type": "",
"sha1": "",
"md5": ""
}
}
],
"raw": "",
"item_id": "",
"attachment_files": [],
"epilogue": "",
"preamble": "",
"headers": {
"X-MS-Exchange-Transport-CrossTenantHeadersStamped": "",
"X-MS-TrafficTypeDiagnostic": "",
"Auto-Submitted": "",
"X-MS-Exchange-CrossTenant-Network-Message-Id": "",
"X-Exchange-Antispam-Report-Test": "",
"X-Forefront-Antispam-Report": "",
"From": "",
"X-MS-Exchange-Organization-MessageDirectionality": "",
"X-Microsoft-Antispam-Message-Info": [],
"Subject": "",
"X-Microsoft-Antispam": "",
"MIME-Version": "",
"Reply-To": "",
"X-MS-Exchange-Organization-Network-Message-Id": "",
"X-MS-Exchange-CrossTenant-OriginalArrivalTime": "",
"Authentication-Results": "",
"SpamDiagnosticOutput": "",
"X-Google-Smtp-Source": "",
"X-Received": "",
"X-MS-Exchange-Transport-EndToEndLatency": "",
"X-EOPAttributedMessage": "",
"X-MS-Exchange-Organization-AuthAs": "",
"Return-Path": "",
"X-MS-PublicTrafficType": "",
"SpamDiagnosticMetadata": "",
"X-MS-Exchange-Organization-AuthSource": "",
"Received": [],
"X-MS-Exchange-Organization-SCL": "",
"X-EOPTenantAttributedMessage": "",
"X-Exchange-Antispam-Report-CFA-Test": "",
"X-Google-DKIM-Signature": "",
"X-MS-Office365-Filtering-Correlation-Id": "",
"Content-Type": "",
"DKIM-Signature": [],
"X-MS-Exchange-Processed-By-BccFoldering": "",
"Sender": "",
"Received-SPF": "",
"X-Gm-Message-State": "",
"X-MS-Exchange-CrossTenant-FromEntityHeader": "",
"Message-ID": "",
"X-Microsoft-Exchange-Diagnostics": [],
"To": "",
"X-MS-Exchange-CrossTenant-Id": ""
},
"body": {
"html": "",
"json": "",
"text": ""
}
}
]
}
Important: For this operation to work, you must have the FortiSOAR™ Built-in connector "cyops_utilities" (minimum version required is 2.0.1) installed on your system. For more information on FortiSOAR™ Built-in connectors, see FortiSOAR™ product documentation.
Parameter | Description |
---|---|
Subject | (Optional) Subject of the email message that you want to send from the Exchange server. |
TO Recipients | Email IDs of the members to whom you want to send the email message from the Exchange server. You must add the email IDs in the CSV or list format. For example, abc@xyz.com, def@lmn.com Important: You must specify email ID(s) in at least one of the following fields: TO Recipients, CC Recipients, or BCC Recipients. |
CC Recipients | Email IDs of the members to be added to the CC list of the email message that you want to send from the Exchange server. You must add the email IDs in the CSV or list format. |
BCC Recipients | Email IDs of the members to be added to the BCC list of the email message that you want to send from the Exchange server. You must add the email IDs in the CSV or list format. |
Body | (Optional) Message or content of the email that you want to send from the Exchange server. |
Attachment IRIs | (Optional) List of IRI ID(s) of the file (s) that you want to attach to the email that you want to send from the Exchange server. IRI IDs are used to access files from the FortiSOAR™Attachments module. You must add the Attachment IRIs in the CSV or list format. |
Inline Attachment IRIs | (Optional) List of IRI ID(s) of the file (s) that you want to add inline to the email that you want to send from the Exchange server. You can add the image content inline in the email body using its UUIDs. For example, <img src="cid%3Adfe26867-01a1-4969-8168-8c8882586538"> |
The JSON output contains the status of the send email operation. The JSON output returns a Success
message if the email is successfully sent from the Exchange server or an Error
message containing the reason for failure.
The output contains the following populated JSON schema:
{
"message": ""
}
The Sample - Exchange - 3.1.0
playbook collection comes bundled with the Exchange connector. This playbook contains steps using which you can perform all supported actions. You can see the bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the Exchange connector.
Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during connector upgrade and delete.