Sweep for Email Messages | Trend Micro Service Central

Searches email messages in Cloud App Security protected mailboxes for those that match meta information search criteria.

HTTPS Request

GET https://<serviceURL>/v1/sweeping/mails

Request Parameters

Parameter	Description
`mailbox`	Email address of the mailbox to search in Type a complete email address. Non-prefix wildcard is supported. Example: user@example.com or user@example.com
`lastndays`	Number of days (n × 24 hours) before the point of time when the request is sent, during which email messages are to search Cloud App Security saves the meta information of email messages in each mailbox for 90 days. Do not configure `lastndays` and `start`/`end` at the same time.
`start` `end`	Start and end time during which email message are to search. Format: ISO 8601 timestamp to the second or millisecond in UTC, yyyy-mm-ddThh:mm:ss[.mmm]Z. For example, `2016-07-22T01:51:31Z` or `2016-07-22T01:51:31.001Z`. Cloud App Security saves the meta information of email messages for 90 days. The request searches email messages according to the `start` and `end` settings: If both `start` and `end` are not specified, the request searches email messages within seven days (7 × 24 hours) before the point of time when the request is sent. If both `start` and `end` are specified, the request searches email messages within the configured duration. Make sure the end time is no earlier than the start time. If only `start` is specified, the request searches email messages within seven days (7 × 24 hours) after the point of the configured start time. If only `end` is specified, the request searches email messages within seven days (7 × 24 hours) before the point of the configured end time. Do not configure `lastndays` and `start`/`end` at the same time.
`subject`	Subject of email messages to search for To search for an exact phrase, for example, `example1 example2`, enclose the value in double quotes "example1 example2"; otherwise, Cloud App Security performs partial match based on the phrase. Example 1, if you set the value to `example1 example2`, Cloud App Security searches for email messages whose subject contains `example1`, or `example2`, or `example1 example2`. Example 2, if you set the value to `example1_example2-example3.txt_as_body`, Cloud App Security searches for email messages whose subject contains `example1_example2`, `example3`, `txt_as_body`, or `example1_example2-example3.txt_as_body`.
`file_sha1`	SHA-1 hash value of the attachment file to search for Cloud App Security uses exact match. Type a complete and valid SHA-1 hash value.
`file_sha256`	SHA-256 hash value of the attachment file to search for Cloud App Security uses exact match. Type a complete and valid SHA-256 hash value.
`file_name`	Name of the attachment file to search for Type the file name you want to search for, with or without a filename extension. Non-prefix wildcard is supported. Example: ex*ample
`file_extension`	Filename extension of attachment files to search for Type the filename extension you want to search for, without a dot ".". Non-prefix wildcard is supported. Example: do*
`url`	URL in email body or attachments to search for Type the exact URL you want to search for. Cloud App Security extracts the normalized URL part from the URL, that is, hostname + path, to search and display email messages containing any URL that matches this part. For example, if you want to search for email messages containing URL `https://example.com/path?option 1`, Cloud App Security uses example.com/path as the search criterion and displays in the response not only the email messages containing https://example.com/path?option 1 but also those containing https://example.com/path?option 2.
`sender`	Sender email address of email messages to search for Type a complete email address. Non-prefix wildcard is supported. Example: u*ser@example.com
`recipient`	Recipient email address of email messages to search for Type a complete email address. Non-prefix wildcard is supported. Example: u*ser@example.com
`message_id`	Internet message ID of the email message to search for It can be obtained from Microsoft Graph API or EWS API.
`source_ip`	Source IP address of email messages to search for An IP address with or without subnet mask is supported. Example: xx.yy.zz.ww or xx.yy.zz.ww/16
`source_domain`	Source domain of email messages to search for Type a complete domain name. Non-prefix wildcard is supported. Example:ex*ample.com
`limit`	Number of email messages whose meta information is to display at a time. A maximum of 1,000 email messages are allowed. If not specified, the value is set to 20 by default. If the total email messages requested exceed the specified limit, a URL is provided in the next_link field in the response. Use this URL to form a second request to retrieve meta information of the remaining email messages for the previous request. Repeat this until all information for the first request are obtained.

Request Example

Example 1: search for email messages in mailbox user@example.com received from 2019-02-12 01:51:31.001 to 2019-03-12 01:51:31.001 (UTC)

GET https://api.tmcas.trendmicro.com/v1/sweeping/mails?mailbox=user1@example1.com&
     start=2019-02-12T01:51:31.001Z&end=2019-03-12T01:51:31.001Z
     Authorization: Bearer 1de231142eef3f83928da98dc251fbebb6cafe77

Example 2: search for email messages with the subject containing phrase wire transfer and received within two days from the time when the request is sent, with the number of messages to display at a time being 10

GET https://api.tmcas.trendmicro.com/v1/sweeping/mails?subject="wire transfer"&lastndays=2&limit=10
Authorization: Bearer 1de231142eef3f83928da98dc251fbebb6cafe77

If the total email messages requested exceed 10, use the URL in the next_link field in the response to form a second request as:

GET https://api.tmcas.trendmicro.com/v1/sweeping/mails?subject="wire transfer"&lastndays=2&limit=10&
     skipToken=<randomly generated value>=
     Authorization: Bearer 1de231142eef3f83928da98dc251fbebb6cafe77

Response

On success, the service sends back an HTTP 200 response and returns a response body in JSON format; otherwise, the service sends back an error message in JSON format with error details. For more information about errors, see API Responses.

Response Example

HTTP/1.1 200
Content-Type: application/json

{
    "current_Link": "https://api.tmcas.trendmicro.com/v1/sweeping/mails?subject=test&start=2019-02-12T01:51:31.001Z&
     end=2019-12-12T01:51:31.001Z&limit=1",
    "next_Link": "https://api.tmcas.trendmicro.com/v1/sweeping/mails?subject=test&start=2019-02-12T01:51:31.001Z&
     end=2019-12-12T01:51:31.001Z&limit=1&skipToken=<randomly generated value>=",
    "value": [
        {
            "mail_attachments": [
                {
                    "file_sha1": "34924b49e416befd1106cad406d413e6e4a89577",
                    "file_sha256": "0bfc7d5fc0c7da4cd974c24676a97a5c8796689aaf40a978021554177d4ebf8e",
                    "file_name": "test.txt"
                 }
            ],
            "mail_message_subject": "test sample",
            "mail_urls": [
                "http://www.google.com"
                ],
            "mail_message_id": "<BL0PR01MB4178833793C138CE3414D53B777A0@BL0PR01MB4178.prod.example.com>",
            "mail_unique_id": "AAMkAGRhODQyZDAzLWNmNjEtNDY2OS1iOWM3LWVmODUxMDk7ZjE1ZgBGAAAAAAABcyFCsOdnTo
             hKgA0TJdjUBwAYbtU+cD0jRZmfu0kuMtvEAAAAAAEMAAAYbtU+cD0jRZmfu7kuMtvEAAF/JGRaAAA=",
            "mailbox": "user2@example2.com",
            "source_ip": "xx.yy.zz.ww",
            "mail_message_sender": "user3@example3.com",
            "mail_internet_headers": [
                {
                    "Value": "user3@example3.com",
                    "HeaderName": "Return-Path"
                }
            ],
            "mail_message_recipient": [
                "user2@example2.com"
            ],
            "source_domain": "example3.com",
            "mail_message_delivery_time": "2019-02-25T08:42:45.000Z",
            "org_id": "c2859385-35b4-4cc9-a402-b6f0513db0c9",
            "service": "exchange"
        }
    ]
}

Response Fields

The following table describes the available fields for the response body.

Note:

All time-related fields in the table are set to Coordinated Universal Time (UTC).

Field	Data Type	Description
`current_link`	String	URL in the current request
`next_link`	String	URL for the follow-up request if the requested email messages exceed the specified limit to display at a time. Use this URL to form a second request to retrieve meta information of the remaining email messages for the previous request. Repeat this until all information for the first request are obtained.
`value`	JSON array	Details of each email message found
`mail_attachments`	JSON array	Information about each attachment file in the email message
`mail_attachments/file_sha1`	String	SHA-1 hash value of the attachment file
`mail_attachments/file_sha256`	String	SHA-256 hash value of the attachment file
`mail_attachments/file_name`	String	Name of the attachment file
`mail_message_subject`	String	Subject of the email message
`mail_urls`	String	URL(s) contained in the email body or attachment
`mail_message_id`	String	Internet message ID of the email message
`mail_unique_id`	String	Unique ID of the email message
`mailbox`	String	Mailbox where the email message is
`source_ip`	String	Source IP address of the email message
`mail_message_sender`	String	Sender email address of the email message
`mail_internet_headers`	JSON array	Information about the Internet header of the email message
`mail_internet_headers/Value`	String	Sender email address of the email message
`mail_internet_headers/HeaderName`	String	Internet header name of the email address
`mail_message_recipient`	JSON array	A list of recipient email addresses of the email message
`source_domain`	String	Source domain of the email message
`mail_message_delivery_time`	ISO 8601 timestamp	Date and time when the email message was sent
`org_id`	String	ID that identifies the organization in which the cloud application tenant of the email message is provisioned
`service`	String	Name of the protected service The value is exchange or gmail.