Enterprise Recon v1 API

All Documentation > ER2 v1 API > Examples > Scan and Remediate Emails and Attachments Containing Specific Reference Numbers

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

Some of the sample requests or responses may have been trimmed for readability but should not impact the clarity of the content.

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

A separate API request will need to be made for each reference number that should be found in the email subject, email content, and/or email attachment.

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 …

The "path" values in the above table have been trimmed for readability.

Step 4 - Remediate Files with Matches

Remediation can result in the permanent erasure or modification of data. Once performed, remedial actions cannot be undone.

Remedial actions cannot be undo. Review the scan results for match objects before performing remediation.

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