Views:
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: u*ser@example.com or user@ex*ample.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
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 to which the email message belongs
service
String
Name of the protected service
The value is exchange or gmail.