Enterprise Recon v1 API
Scan and Remediate Emails and Attachments Containing Specific Reference Numbers
This example describes the workflow and sequence of requests to make to (i) scan a specific mailbox on an Exchange Domain Target, and (ii) remediate (Delete permanently) match objects if the contain specific reference numbers in the email subject, email content, and/or email attachment(s).
- Step 1 - Create Data Type Profile
- Step 2 - Scan Exchange Domain Target
- Step 3 - List Objects with Matches
- Step 4 - Remediate Files with Matches
Defaults and Assumptions
This example uses the following default values and makes the following assumptions:
- The Exchange Domain server has been added to the Master Server and 1295310479927725330 is the Target ID.
- The mailbox group has been added as a Target Location (Target Location id = 6481178332265563363).
- mailbox1 is the shared mailbox to be scanned.
- You want to remediate (Delete permanently) emails and/or email attachments
that contain the following reference number in the email subject, email content,
and/or email attachments:
- 1290ABYZ3478
Step 1 - Create Data Type Profile
POST
https://er-master:8339/v1/filters
Create a new Data Type Profile to use when scanning the Exchange Domain Target that enables specific built-in data types to search for, where:
- label is a descriptive name for the data type profile. E.g. exchange-domain-1290ABYZ3478-only.
- custom_expressions.disabled is false.
- custom_expressions.label is ref-number. This label could be any meaningful label for the custom data type.
- custom_expressions.expression is LABEL 'EXAMPLE REF NUMBER'\nWORD NOCASE '1290ABYZ3478'. This defines a custom GLASS expression to search for the reference number (1290ABYZ3478) in the email subject, email content and/or email attachment. The LABEL operator in the custom expression can be used to define a unique identifier for the custom data type (e.g. EXAMPLE REF NUMBER), which can be used to filter the match objects results in Step 4.
- capture: true.
Sample Request
cURL
curl --request POST 'https://er-master:8339/v1/datatypes/profiles' \
--user apiuser:password123 \
--header "Content-Type: application/json" \
--data-raw '{
"label": "exchange-domain-1290ABYZ3478-only",
"custom_expressions": [
{
"disabled": false,
"label": "ref-number",
"expression": "LABEL 'EXAMPLE REF NUMBER'\nWORD NOCASE '1290ABYZ3478'"
}
],
"ocr": false,
"ebcdic": false,
"suppress": false,
"capture": true
}'
Expected Response
201 Created
HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: xxx
{
"id": "685300134190752184",
"version": 1
}
The ID for the data type profile (685300134190752184) created in this request will be required when scanning the Exchange Domain Target.
Step 2 - Scan Exchange Domain Target
POST
https://er-master:8339/v1/schedules
Schedule a scan for the Exchange Domain Target, where:
- label is a descriptive label for the scan.
- targets.id is 1295310479927725330 (see Defaults and Assumptions).
- targets.locations.id is 6481178332265563363 (see Defaults and Assumptions),
- targets.locations.subpath is the mailbox to scan (e.g. mailbox1).
- profiles is the ID of the data type profile created in Step 1 (e.g. 685300134190752184).
- trace = true.
Sample Request
cURL
curl --request POST 'https://er-master:8339/v1/schedules' \
--user apiuser:password123 \
--header "Content-Type: application/json" \
--data-raw '{
"label": "Exchange Domain Email Subject API scan",
"targets": {
"id": "1295310479927725330",
"locations": [
{
"id": "6481178332265563363",
"subpath": "mailbox1"
}
]
},
"profiles": [
"685300134190752184"
],
"cpu": "low",
"throughput": 0,
"memory": 0,
"capture": true,
"trace": true,
"match_detail": "balanced"
}'
Expected Response
201 Created
HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: xxx
{
"id": ""
}
You can check the status and progress of the scan using the scan schedule id (124) created in this request.
You can also view the Scan Trace Log to check that the correct mailbox (mailbox1) is being scanned according to the scan schedule setup.
Step 3 - List Objects with Matches
POST
https://er-master:8339/v1/targets/<target_id>/matchobjects
Get a list of objects with matches using the data_types query parameter to limit the results to match objects with 1290ABYZ3478 in the email subject, email content, and/or email attachment, where:
- target_id is 1295310479927725330 (see Defaults and Assumptions).
- data_types is EXAMPLE+REF+NUMBER
Sample Request
Get a list of objects that contain the reference number 1290ABYZ3478 in the email subject, email content, and/or email attachment.
cURL
curl --request GET 'https://er-master:8339/v1/targets/1295310479927725330/matchobjects?data_types=EXAMPLE+REF+NUMBER' \
--user apiuser:password123 \
--header "Accept: application/json"
Expected Response
List of objects that contain the reference number 1290ABYZ3478 in the email subject.
200 OK
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: xxx
[
{
"id": "103",
"path": "Group/mailbox1/Inbox/Example Email 1 With Ref Num 1290ABYZ3478/2023-02-20 08:07:49 GMT$AAMkADBlM2JlMTY0LThiMWItNDRkYS04ZmU3LWU4YWYyZDZjNTc1OQBGAAAAAAAdYjK+eyzOTrGJyOB1tmgPBwDYBFAwTUBSSb6KarWN6tdnAAAAG6EfAADYBFAwTUBSSb6KarWN6tdnAAG9iYM7AAA=",
"owner": ""
},
{
"id": "102",
"path": "Group/mailbox1/Inbox/Example Email 2 With Ref Num 1290ABYZ3478/2023-02-20 08:08:44 GMT$AAMkADBlM2JlMTY0LThiMWItNDRkYS04ZmU3LWU4YWYyZDZjNTc1OQBGAAAAAAAdYjK+eyzOTrGJyOB1tmgPBwDYBFAwTUBSSb6KarWN6tdnAAAAG6EfAADYBFAwTUBSSb6KarWN6tdnAAG9iYM8AAA=",
"owner": ""
},
{
"id": "95",
"path": "Group/mailbox1/Inbox/Example Email 2 With Ref Num 1290ABYZ3478/2023-02-20 08:08:44 GMT/example.txt$AQMkADBlM2JlMTY0LThiMWItNDQAZGEtOGZlNy1lOGFmMmQ2YzU3NTkARgAAAx1iMr57LM5OsYnI4HW2aA8HANgEUDBNQFJJvopqtY3q12cAAAEboR8AAADYBFAwTUBSSb6KarWN6tdnAAG9iYM8AAAAAQYABAAAAw==",
"owner": ""
},
{
"id": "101",
"path": "Group/mailbox1/Inbox/Example Email 3 With Ref Num 1290ABYZ3478/2023-02-20 08:09:18 GMT$AAMkADBlM2JlMTY0LThiMWItNDRkYS04ZmU3LWU4YWYyZDZjNTc1OQBGAAAAAAAdYjK+eyzOTrGJyOB1tmgPBwDYBFAwTUBSSb6KarWN6tdnAAAAG6EfAADYBFAwTUBSSb6KarWN6tdnAAG9iYM9AAA=",
"owner": ""
},
{
"id": "94",
"path": "Group/mailbox1/Inbox/Example Email 3 With Ref Num 1290ABYZ3478/2023-02-20 08:09:18 GMT/example.txt$AQMkADBlM2JlMTY0LThiMWItNDQAZGEtOGZlNy1lOGFmMmQ2YzU3NTkARgAAAx1iMr57LM5OsYnI4HW2aA8HANgEUDBNQFJJvopqtY3q12cAAAEboR8AAADYBFAwTUBSSb6KarWN6tdnAAG9iYM9AAAAAQYABAAAAw==",
"owner": ""
},
{
"id": "100",
"path": "Group/mailbox1/Inbox/Example Email 4 With Ref Num 1290ABYZ3478/2023-02-20 08:10:00 GMT$AAMkADBlM2JlMTY0LThiMWItNDRkYS04ZmU3LWU4YWYyZDZjNTc1OQBGAAAAAAAdYjK+eyzOTrGJyOB1tmgPBwDYBFAwTUBSSb6KarWN6tdnAAAAG6EfAADYBFAwTUBSSb6KarWN6tdnAAG9iYM+AAA=",
"owner": ""
},
{
"id": "99",
"path": "Group/mailbox1/Inbox/Example Email 4 With Ref Num 1290ABYZ3478/2023-02-20 08:10:26 GMT$AAMkADBlM2JlMTY0LThiMWItNDRkYS04ZmU3LWU4YWYyZDZjNTc1OQBGAAAAAAAdYjK+eyzOTrGJyOB1tmgPBwDYBFAwTUBSSb6KarWN6tdnAAAAG6EfAADYBFAwTUBSSb6KarWN6tdnAAG9iYM/AAA=",
"owner": ""
},
{
"id": "98",
"path": "Group/mailbox1/Inbox/Example Email 4 With Ref Num 1290ABYZ3478/2023-02-20 08:12:27 GMT$AAMkADBlM2JlMTY0LThiMWItNDRkYS04ZmU3LWU4YWYyZDZjNTc1OQBGAAAAAAAdYjK+eyzOTrGJyOB1tmgPBwDYBFAwTUBSSb6KarWN6tdnAAAAG6EfAADYBFAwTUBSSb6KarWN6tdnAAG9iYNAAAA=",
"owner": ""
},
{
"id": "105",
"path": "Group/mailbox1/Inbox/Example Email Without Reference Number 1/2023-02-20 08:04:06 GMT$AAMkADBlM2JlMTY0LThiMWItNDRkYS04ZmU3LWU4YWYyZDZjNTc1OQBGAAAAAAAdYjK+eyzOTrGJyOB1tmgPBwDYBFAwTUBSSb6KarWN6tdnAAAAG6EfAADYBFAwTUBSSb6KarWN6tdnAAG9iYM3AAA=",
"owner": ""
},
{
"id": "97",
"path": "Group/mailbox1/Inbox/Example Email Without Reference Number 2/2023-02-20 08:05:12 GMT/example.txt$AQMkADBlM2JlMTY0LThiMWItNDQAZGEtOGZlNy1lOGFmMmQ2YzU3NTkARgAAAx1iMr57LM5OsYnI4HW2aA8HANgEUDBNQFJJvopqtY3q12cAAAEboR8AAADYBFAwTUBSSb6KarWN6tdnAAG9iYM4AAAAAQYABAAAAw==",
"owner": ""
},
{
"id": "104",
"path": "Group/mailbox1/Inbox/Example Email Without Reference Number 3/2023-02-20 08:06:03 GMT$AAMkADBlM2JlMTY0LThiMWItNDRkYS04ZmU3LWU4YWYyZDZjNTc1OQBGAAAAAAAdYjK+eyzOTrGJyOB1tmgPBwDYBFAwTUBSSb6KarWN6tdnAAAAG6EfAADYBFAwTUBSSb6KarWN6tdnAAG9iYM5AAA=",
"owner": ""
},
{
"id": "96",
"path": "Group/mailbox1/Inbox/Example Email Without Reference Number 3/2023-02-20 08:06:03 GMT/example.txt$AQMkADBlM2JlMTY0LThiMWItNDQAZGEtOGZlNy1lOGFmMmQ2YzU3NTkARgAAAx1iMr57LM5OsYnI4HW2aA8HANgEUDBNQFJJvopqtY3q12cAAAEboR8AAADYBFAwTUBSSb6KarWN6tdnAAG9iYM5AAAAAQYABAAAAw==",
"owner": ""
}
]
Get a unique list of match object IDs (id) (and the corresponding path value) from the output of both API requests. These IDs will be required when remediating the match objects.
For this example, the list of unique match object ids and the corresponding paths are:
id | path |
---|---|
103 | Group/mailbox1/Inbox/Example Email 1 With Ref Num 1290ABYZ3478/2023-02-20 … |
102 | Group/mailbox1/Inbox/Example Email 2 With Ref Num 1290ABYZ3478/2023-02-20 … |
95 | Group/mailbox1/Inbox/Example Email 2 With Ref Num 1290ABYZ3478/2023-02-20 … |
101 | Group/mailbox1/Inbox/Example Email 3 With Ref Num 1290ABYZ3478/2023-02-20 … |
94 | Group/mailbox1/Inbox/Example Email 3 With Ref Num 1290ABYZ3478/2023-02-20 … |
100 | Group/mailbox1/Inbox/Example Email 4 With Ref Num 1290ABYZ3478/2023-02-20 … |
99 | Group/mailbox1/Inbox/Example Email 4 With Ref Num 1290ABYZ3478/2023-02-20 … |
98 | Group/mailbox1/Inbox/Example Email 4 With Ref Num 1290ABYZ3478/2023-02-20 … |
105 | Group/mailbox1/Inbox/Example Email Without Reference Number 1/2023-02-20 … |
97 | Group/mailbox1/Inbox/Example Email Without Reference Number 2/2023-02-20 … |
104 | Group/mailbox1/Inbox/Example Email Without Reference Number 3/2023-02-20 … |
96 | Group/mailbox1/Inbox/Example Email Without Reference Number 3/2023-02-20 … |
Step 4 - Remediate Files with Matches
POST
https://er-master:8339/v1/targets/<target_id>/locations/<location_id>/remediation/<action>
Remediate the match objects containing 1290ABYZ3478 in the email subject, email content, and/or email attachment, based on the output in Step 3, where:
- target_id is 1295310479927725330 (see Defaults and Assumptions).
- location_id is 6481178332265563363 (see Defaults and Assumptions).
- action is delete.
- path and object_ids are the path and id values for each match object from Step 3.
- sign_off is user signing off on the remediation action.
Sample Request
cURL
curl --request POST 'https://er-master:8339/v1/targets/1295310479927725330/locations/6481178332265563363/remediation/delete' \
--user apiuser:password123 \
--header "Content-Type: application/json" \
--data-raw '{
"path": "Domain Users/test1/Inbox/Example Email 1 With Ref Num 1290ABYZ3478/2023-02-20 08:07:49 GMT$AAMkADBlM2JlMTY0LThiMWItNDRkYS04ZmU3LWU4YWYyZDZjNTc1OQBGAAAAAAAdYjK+eyzOTrGJyOB1tmgPBwDYBFAwTUBSSb6KarWN6tdnAAAAG6EfAADYBFAwTUBSSb6KarWN6tdnAAG9iYM7AAA=",
"sign_off": "userA",
"reason": "Emails to be deleted permanently.",
"object_ids": [
"103"
]
}'
Expected Response
202 Accepted
HTTP/1.1 202 Accepted
Content-Type: application/json
Content-Length: xxx
{
"path": "Domain Users/test1/Inbox/Example Email 1 With Ref Num 1290ABYZ3478/2023-02-20 08:07:49 GMT$AAMkADBlM2JlMTY0LThiMWItNDRkYS04ZmU3LWU4YWYyZDZjNTc1OQBGAAAAAAAdYjK+eyzOTrGJyOB1tmgPBwDYBFAwTUBSSb6KarWN6tdnAAAAG6EfAADYBFAwTUBSSb6KarWN6tdnAAG9iYM7AAA=",
"job_id": 1677052071
}
The Delete Permanently remediation action deletes the selected match object and leaves a tombstone text file in its place. Please see Remedial Actions in ER2 - Act Directly on Selected Location for more information.
The deleted file will no longer be picked up as a match object upon rescans of the same Target and Location.