List Mail Tracking Logs

Retrieves mail tracking logs that meet specified criteria.

HTTP Request

GET https://<serviceURL>/api/v1/log/mailtrackinglog?type=<type>[&domain=<domain>][&start=<start>][&end=<end>][&limit=<limit>][&token=<token>]

Request Parameters

Parameter	Required	Description
domain	No	Domain from which you want to retrieve mail tracking logs. If this parameter is not specified, the logs from all domains are queried.
direction	No	Direction of the logs that you want to retrieve. Options include: in out
type	Yes	Email traffic type of the logs that you want to retrieve. Options include: accepted_traffic blocked_traffic Important: Specify one type at a time.
start end	No	Start and end time period to retrieve logs. Format: ISO 8601 timestamp to the second or millisecond in UTC, yyyy-mm-ddThh:mm:ss[.mmm]Z Example: `2016-07-22T01:51:31Z` or `2016-07-22T01:51:31.001Z` The request retrieves logs generated within a maximum of 72 hours before the request is sent according to the `start` and `end` settings: If neither `start` nor `end` is specified, the request retrieves logs generated within five minutes of when the request is sent. If both `start` and `end` are specified, the request retrieves logs generated within the configured duration. Make sure the end time is no earlier than the start time. If only `start` is specified, the request retrieves logs generated within five minutes after the configured start time. If only `end` is specified, the request retrieves logs generated within five minutes before the configured end time.
limit	No	Maximum number of log items to return in each response. The default value is 500. If the total log items requested exceed the specified limit, a token is provided in the nextToken parameter in the response. Use this token to form a second request to retrieve the next set of log items. Repeat this until the nextToken parameter is not returned in a response.
token	No	Use the value of nextToken returned in the previous response to retrieve the next set of log items.

HTTP Request Example

GET https://<serviceURL>/api/v1/log/mailtrackinglog?domain=example.com&type=accepted_traffic&start=2020-11-25T00:00:00Z&end=2020-11-25T23:59:59Z&limit=1&token=Lu2XNNHim8CZpKoJEJKREJj6jpojv HTTP/1.1
Authorization: Basic c2FtcGxlOmZqZmo0OTBpNGpnaDAzM2dsajQzYXB3ZW1hMzEwdjEwamIxZ2lrM2oz
Accept-Encoding: gzip

Response

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

Status Code	Description
200	Successful. The mail tracking logs are returned in the response body.

The response body is an array of log objects in JSON format.

Response Example

HTTP/1.1 200
Content-Type: application/json;charset=UTF-8

{    
    "nextToken": "Lu2XNNHim8CZpKoJEJKREJj6jpojvvROIwMK6xL+zILf8DsPpkW5W8/XhJiWH5tsJh8VrkdCIvpmJPEd71JKaUVoxTzDTU8/3RZVvYMfxzSyGIl2XYpWj9Qo+wigLGpHY4w==",
    "logs": [
		{
			"genTime": "2020-11-25T06:53:19Z",
			"timestamp": "2020-11-25T06:53:18Z",
			"deliveryTime": "2020-11-25T06:53:28Z",
			"sender": "sender@example.com",
			"direction": "in",
			"messageID": "<7bebfeb6-f035-451f-8c4f-3377ab457b07@atl1s07mta2135.xt.local>",
			"subject": "response sample",
			"size": 66390,
			"mailID": "73173f80-2e0e-46df-b2dc-a62e80167067",
			"recipient": "rcpt@example.com",
			"action": "Delivered",
			"tlsInfo": "upstreamTLS: TLS 1.2; downstreamTLS: TLS 1.2",
			"headerFrom": "header_sender@example.com",
			"headerTo": [
				"header_rcpt1@example.com",
				"header_rcpt2@example.com",
				"header_rcpt3@example.com"
			],
			"senderIP": "1.1.1.1",
			"deliveredTo": "2.2.2.2",
			"attachments": [{
					"fileName": "test1.zip",
					"sha256": "f78960148721b59dcb563b9964a4d47e2a834a4259f46cd12db7c1cfe82ff32e"
				}, {
					"fileName": "test2.zip",
					"sha256": "329436266f3927e89ea961e26855c8bd1f51401d92babd6627e493295376daf5"
				}
			],
			"embeddedUrls": [
				"http://example1.com",
				"http://example2.com"
			],
                        "details": "250 2.0.0 Ok: queued as 3CBEFC0811"
		}
	]
}

Response Parameters

Name	Type	Description
nextToken	String	Token string for the follow-up request if the total log items requested exceed the specified limit to retrieve at a time. Use this string to form a second request to retrieve the next set of log items. Repeat this until the NextToken parameter is not returned in a response anymore.
logs	JSON array	Overall information of the requested mail tracking log items.
timestamp	ISO 8601 timestamp	Date and time when Trend Micro Email Security received the email message.
genTime	ISO 8601 timestamp	Date and time when the mail tracking log was generated.
deliveryTime	ISO 8601 timestamp	Date and time when Trend Micro Email Security sent the email message to the next hop. Note: This field is returned only when the returned action is Delivered, Bounced, Expired, or Deferred.
sender	String	Email address of the sender.
headerFrom	String	Email address of the sender in the mail header.
recipient	String	Email address of the recipient.
headerTo	String	Email address(es) of the recipient(s) in the mail header.
subject	String	Subject of the email message.
senderIP	String	Source IP address.
deliveredTo	String	Relay MTA address.
mailID	String	Internal email message ID.
direction	String	Direction of the email message.
messageID	String	ID of the email message.
size	Integer	Size of the email message, in bytes.
action	String	Action that Trend Micro Email Security took on the email message.
reason	String	Reason why the email message was blocked.
attachments	JSON array	Attachment information of the email message.
fileName	String	Name of the attachment file.
sha256	String	SHA256 checksum string of the attachment file.
embeddedUrl	String array	URL(s) embedded in the email message.
tlsInfo	String	Upstream and downstream TLS status.
details	String	When the request field type is set to accepted_traffic, this parameter indicates the details about why an action is taken on the email message, and is returned only when the action is Deferred, Delivered, Expired, or Bounced. When the request field type is set to blocked_traffic, this parameter indicates the details about why the email message is blocked.