Press CTRL+K to open search

Email trace request

  • Published on Sep 4, 2026
  • 11 minute(s) read
Prev Next

This API retrieves email trace information as per the attributes and traffic type that are accessible in the Email Security — Cloud portal. Attributes can be specified individually or in combination. If no attributes are passed, a sorted list of messages (starting with the oldest) is returned based on their last modified status time.

POST https://<etp_instance_addr>/api/v1/messages/trace

Required headers:

Content-Type: application/json—Specifies that the server's response body is expected to be in JSON format.

x-fireeye-api-key: <key>—Specifies your personal API key.

Options

  • traffic_type—Traffic type defaults to inbound. To handle outbound traffic, set the traffic_type parameter to outbound.

Request body examples:

Values for ID and other fields are for illustration only.

{   "traffic_type" : "outbound",
    "attributes": {
        "fromEmail": {
            "value": ["test@etp.com"], "filter": "in", "includes": ["SMTP"]
            },
        "recipients": {
            "value": ["userb@etp-testdomain5.com", "usera@etp-testdomain5.com"], "filter": "in", "includes": ["SMTP", "HEADER"]
        },
        "subject": {
            "value": ["test message"], "filter": "in"
        },
        "period": {
            "range": {
                "fromAcceptedDateTime": "2017-07-11T04:52:26.365000+00:00",
                "toAcceptedDateTime": "2017-07-10T04:51:26.365000+00:00"
            }
        },
        "lastModifiedDateTime": {
            "value": "2017-07-11T04:51:26.365000+00:00", "filter": ">="
        },
        "status": {
            "value": ["accepted", "rejected"], "filter": "in"
        },
        "rejectionReason":{
            "value": ["ETP203"]
        },
        "atVerdict":{
            "value": ["pass"], "filter": "in"
        },
        "avVerdict": {
            "value": ["pass", "fail"], "filter": "in"
        },
        "asVerdict": {
            "value": ["pass"], "filter": "in"
        },
        "pvAction": {
            "value": ["others"], "filter": "not in"
        },
        "yaraVerdict": {
            "value": ["pass"], "action": ["no match"], "filter": "in",
        },
        "hasAttachment": {
            "value": false
        },
        "messageSize":{
            "min": 0, "max": 1000
        },
        "senderIP":{
            "value": ["10.128.1.1", "10.128.1.2"], "filter": "in"
        },
        "domains": {
            "value": ["etp-testdomain5.com"]
        },
        "domainGroups": {
            "value": ["test domain group"]
        },
        "tags": {
            "value": ["impersonation"], "filter": "in"
        },
        "hasRetroactiveAlert": {
            "value": true
        },
        "hasMaliciousQR": {
            "value": true
        },
        "remediateAction": {
            "value": ["delete", "move"], "filter": "not in"
        },
        "integrationType": {
            "value": ["SMTP"], "filter": "in"
        },
        "riskwareRules": {
            "value": ["65001", "65002"], "filter": "in"
        },
        "yaraRulesAction": {
            "value": ["alert and quarantine", "alert only", "monitor", "no match"], "filter": "in"
        },
        "dlpPolicyAction": {
            "value": ["drop"], "filter": "in"
        },
        "dlpClassifications": {
            "filter": "in",
            "value": [
                        "Classification 1"
                     ]
        },
        "dlpRules": {
            "filter": "in",
            "value": [
                         "Rule 1"
                     ]
        }
    },
    "size":20
}'

This example searches for messages that are between 0 and 1000 KB:

{
"attributes": {
   "messageSize":{
      "min": 0, "max": 1000
     }
   }
}

This example searches for messages that were rejected for error ETP203. Note that the status filter is mandatory when using the rejectionReason filter:

{
  "attributes": {
    "status":{
      "value":["rejected"], "filter":"in"
    },
    "rejectionReason":{
      "value":["ETP203"]
    }
  }
}

This example searches for the traffic parameter for outbound trace messages. Traffic type defaults to inbound.

{
  "traffic_type":"outbound",
  "attributes": {
    "messageSize":{
      "min": 0, "max": 1000
    }
  }
}

Request body fields:

All parameters are optional.

  • type: Specify the type of the query. Currently, this can have only one value: MessageAttributes.

  • size: (integer) The number of records returned by the search query. Default is 20 and range is 1-300.

  • attributes: The following attributes are available:

Parameter

Filter / Includes / Description

advancedThreatEngineConfiguration

  • Filter: in/not in

  • Array of valid strings: "urlallowmatch", "urlblockmatch", "attachmenthashallowmatch", "attachmenthashblockmatch"

    Values can be one or more strings.

    For example:

    {
"attributes": {
  "advancedThreatEngineConfiguration": { 
    "value": ["attachmenthashblockmatch", "urlblockmatch"],
    "filter": "in"
  }
 }
}

asVerdict

  • Filter: in/not in

  • Pass/fail verdict for antispam.

attachmentHashes

  • Filter: in/not in

  • Array of MD5 or SHA256 attachment hashes, 10 entries maximum.

    For example:

    "attributes":  
{
   "attachmentHashes": { 
     "value": ["a52861482c2984e928301cc69d1d78d6"],
     "filter": "in"
   }
 }

Note: MD5 sums will be followed by SHA256 sums in a list in the attachmentHashes response field

attachmentNames

  • Filter: in/not in

  • Array of attachment names, 10 entries maximum.

    For example:

    "attributes": 
 {
   "attachmentNames": { 
     "value": ["file.doc", "list.pdf"],
     "filter": "in"
   }
 }

atVerdict

  • Filter: in/not in

  • Pass/fail verdict for advanced threat

avVerdict

  • Filter: in/not in

  • Pass/fail verdict for antivirus

customRuleNames

  • Filter: in/not in

  • Array of custom rule names, 10 entries maximum. Supports full text search.

    For example:

    "attributes": {
  "customRuleNames": {
    "value": ["Modify Subject"],
    "filter": "in"
  }
}

dlpClassification

  • Filter: in/not in

  • List of DLP classifications, 10 entries maximum. Supports full text search.

    For example:

    "attributes": {
  "dlpClassifications": {
        "filter": "in",
        "value": ["Modify Subject"]
  }
}

dlpPolicyAction

  • Filter: in/not in

  • Value: "drop" or "quarantine" or "bcc" or "no_action"

dlpRules

  • Filter: in/not in

  • List of DLP Rules, 10 entries maximum. Supports full text search.

    For example:

    "attributes": {
  "dlpRules": {
        "filter": "in",
        "value": ["Modify Subject"]
  }
}

domains

  • Array of domain names, 10 entries maximum.

domainGroups

  • Array of domain group names, 10 entries maximum.

fileTypes

  • Filter: in/not in

  • Array of attachment file types, 10 entries maximum.

    For example:

    "attributes": {
  "fileTypes": {
    "value": ["reg", "com"],
    "filter": "in"
  }
}

fromEmail

  • Filter: in/not in

  • Includes: SMTP, HEADER

  • List of From email-addresses, 10 entries maximum.

hasAttachment

  • true or false.

    For example:

"attributes": {
    "hasAttachment": {
                "value": true
            }

hasMaliciousQR

  • Filter: in/not in

  • true or false.

    For example:

    "attributes": {
    "hasMaliciousQR": {
                "value": true
            }

hasReleaseJustification

  • true or false.

    For example:

    "attributes": {
    "hasReleaseJustification": {
                "value": true
            }

hasRetroactiveAlert

  • Filter: in/not in

  • true or false.

    For example:

    "attributes": {
    "hasRetroactiveAlert": {
                "value": true
            }

integrationType

  • Filter: in/not in

  • "SMTP" or "MS365_API"

    For example:

    "attributes": {
    "integrationType": {
                "value": ["SMTP"], "filter": "in"
            }

lastModifiedDateTime

  • Filter: ">" (greater than), "<" (less than), ">=" (greater th n or equal to), "<=" (less than or equal to)

  • Date (format compliant with ISO8601) corresponding to last modified date. Time is in ISO format.

For example:

2017-10-03T00:00:00.000Z

messageSize

  • Range in KB from min (default: 0) to max (default: none).

period

  • range: fromAcceptedDateTime, toAcceptedDateTime (format compliant with ISO8601).

pvAction

  • Filter: in/not in

  • Array of one or more of: drop or quarantine, drop or quarantine or remediate, others.

recipients

  • Filter: in/not in

  • Includes: SMTP, HEADER

  • Array of To/Cc email addresses, 10 entries maximum .

rejectionReason

  • Array of Email Security — Cloud rejection reason codes:

    • ETP102—Recipient rejected

    • ETP103—Downstream MTA not responsive

    • ETP104—Routing loop detected

    • ETP110—Rate limit exceeded

    • ETP200—DHAP match

    • ETP201—RBL match

    • ETP203—SPF Failure

    • ETP204—DKIM Failure

    • ETP205—DMARC Failure

    • ETP300—Start TLS not issued

    • ETP301—Invalid Sending MTA IP Address

    • ETP302—Email Size over Max Limit

    • ETP400—Deny List Match - Sender IP

    • ETP401—Deny List Match - Reverse Domain

    • ETP402—Deny List Match - Country

    • ETP403—Deny List Match - Recipient Denylist

    • ETP404—Deny List Match - Sender Denylist

    • ETP405—Deny List Match - Sender Domain

Note: The value of status must be rejected for this attribute to work.

For example:

{
  "attributes":{
    "status":{
      "value":["rejected"],
      "filter":"in"
    },
    "rejectionReason":{
      "value":["ETP203"]
    }
  }
}

remediateAction

  • Filter: in/not in

  • Array of valid remediate actions: "delete", "failure", "move", "monitor", "quarantine", "released", "release_failure"

    For example:

    "attributes": {
    "remediateAction": {
        "value": ["delete", "move"],
        "filter": "not in"
    }
}

riskwareRules

  • Filter: in/not in

  • List of Valid riskware rule IDs:

    "0", "65000", "65001", "65002", "65003", "65004", "65007", "65008", "65009", "65010", "65011", "65012", "65013", "65016", "65017", "65020", "65021", "65022", "65023", "65024", "65025", "65027", "65028", "65029", "65030", "65031", "65033", "65034", "65036", "65037", "65041", "65043", "65044"

    For example:

    "attributes": {
  "riskwareRules": { 
    "value": ["65001", "65002"],
    "filter": "in"
  }
 }

senderIP

  • Filter: in/not in

  • Array of sender IP addresses, 10 entries maximum.

size

  • Filter: Integer

  • Number of records returned. Size Range: 1-300 (default is 20).

status

  • Filter: in/not in

  • Array of email status values:

    • accepted

    • deleted

    • delivered

    • dropped

    • dropped oob

    • permanent failure

    • processing

    • quarantined

    • rejected

    • temporary failure

    • scanned

    • scan bypassed

    • split

subject

  • Text to search for in the subject.

tags

  • Filter: in/not in

  • Array of tags to search for in Email Trace: "impersonation", "auto_remediation", "manual_remediation", "native_remediation", "released", url_click_blocked, url_clicked_before_malicious_classification, spam_level-low, spam_level-medium, spam_level-high, notification, and encrypted_attachment.

    Has sub-field of "value".

    To know more about the tags, see Impersonation, Remediation policies and .Releasing quarantined emails

    For example,

    "tags": {
	  "value": ["manual_remediation"],
	  "filter": "not in"
	},

urlDomains

  • Filter: in/not in

  • Array of URL domains, 10 entries maximum.

    For example:

    "attributes": {
  "urlDomains": {
    "value": ["example.com"],
    "filter": "in"
  }
}

    The search uses exact match. You must use the full domain name, including the subdomains and not including the http or https protocol. 'www.example.com' and 'example.com' are considered different domains and should be searched individually.

userSubmissionType

  • Filter: in/not in

  • List of valid end user submission types: 'junk', 'phishing', or 'others'

    "attributes": {
  "userSubmissionType": {
     "value": ["others"],
     "filter": "in"
  }
}

yaraRulesAction

  • Filter: in/not in

  • List of Valid YARA rules actions.

    alert and quarantine, alert only, monitor, no match

    For example:

    "attributes": {
  "yaraRulesAction": {
    "value": ["alert and quarantine", "alert only", "monitor", "no match"],
    "filter": "in"
  }
}

yaraVerdict

  • Filter: in/not in

  • Pass/fail verdict for YARA.

    The action field can be an array of [monitor, no match] for items with a Pass verdict. The default value of the action field for items with a Fail verdict is block.

    For example:

    "attributes": {
    "yaraVerdict": {
              "value": ["pass"], "action": ["no match"], "filter": "in",
             }
    }

    Warning: Parameter yaraVerdict in API request is deprecated and will be removed.

Important

Parameters that take a list require an array.

For scrolling through all the trace records (using the fromLastModifiedOn field), use the "end" time (of "fromLastModifiedOn") of the first API response in the "lastModifiedDateTime" field of the next API call. For example, from this response of the first call:

...
"meta": {
  "fromLastModifiedOn": {
    "start": "2019-08-21T10:02:46.052",
    "end": "2019-08-26T11:21:46.533"
  },
  "total": 1880,
  "copyright": "Copyright 2019 Fireeye Inc"
}

Use the end value in the next request body:

{
  "attributes":{
    "lastModifiedDateTime": {
      "value": "2019-08-26T11:21:46.533Z",
      "filter": ">="
    }
  }
}

Email trace response

Values for ID and other fields are for illustration only.

{
  "data": [
    {
      "attributes": {
        "acceptedDateTime": "2019-08-07T10:54:54.000",
        "countryCode": "us",
        "domain": "etp-testdomain5.com",
        "downStreamMsgID": "250 2.0.0 Ok: queued as ACBA05B3C",
        "emailSize": 0.52,
        "lastModifiedDateTime": "2017-07-11T04:51:26.365000",
        "originalMessageID": "\u003c20190807162453.092921@JDEORE-MBP\u003e",
        "recipientHeader": [
          "userb@etp-testdomain5.com"
        ],
        "recipientSMTP": [
          "userb@etp-testdomain5.com"
        ],
        "tags": [
          "impersonation"
        ],
        "senderHeader": "",
        "senderSMTP": "test@etp.com",
        "senderIP": "10.128.1.1",
        "status": "accepted",
        "subject": "test message",
        "verdicts": {
          "AS": "pass",
          "AV": "pass",
          "AT": "pass",
          "PV": "pass",
          "YARA": "pass",
          "ActionYARA": "no match"
        },
        "riskwareRules": [
          "65001"
        ],
        "yaraRulesAction": "no match"
      },
      "included": [
        {
          "type": "domain",
          "attributes": {
            "name": "etp-testdomain5.com"
          }
        }
      ],
      "hasRetroactiveAlert": true,
      "hasMaliciousQR": true,
      "integrationType": "SMTP",
      "dlpPolicyAction": "drop",
      "id": "6D1004243EFDAA4D55b90d4f3",
      "type": "trace"
    }
  ],
  "meta": {
    "total": 193299,
    "size": 20,
    "copyright": "Copyright 2019 Fireeye Inc",
    "fromLastModifiedOn": {
      "start": "2019-07-31T08:12:32.030Z",
      "end": "2017-07-11T04:51:27.365000Z"
    },
    "warnings": [
      "Fields verdicts.YARA and verdicts.ActionYARA in API response are deprecated and will be removed. Please refer to API documentation for more details.",
      "Parameter yaraVerdict in API request is deprecated and will be removed. Parameter yaraRulesAction can be used to filter Yara matches to get same results. Please refer to API documentation for more details."
    ]
  }
}
Error response header:
{
  "errors": [
    {
      "code": "ETP101",
      "detail": "hasAttachment has to be a Boolean",
      "status": "rejected",
      "title":  "Invalid Query Parameter"
    }
  ]
}

Response fields:

  • code—Email Security — Cloud-specific response code.

  • detail—Details of the error.

  • status—The HTTP status code applicable to this problem, expressed as a string.

  • title—The error title.

cURL code sample: email trace

This will display all the records in the specified time and date range that received the Email Accepted timestamp. Line breaks have been added for readability.

curl -k -X POST https://etp.us.fireeye.com/api/v1/messages/trace 
-H "Content-Type: application/json" -H "x-fireeye-api-key: xxxxxxxxxxxxx" -d
'
{
  "attributes": {
    "period": {
      "range": {
        "fromAcceptedDateTime": "2018-11-06T13:13:36.000Z",
        "toAcceptedDateTime": "2018-11-28T13:13:36.000Z"
     }
  },
  "recipients": {
    "value": ["usera"],
    "filter": "in",
    "includes": ["SMTP", "HEADER"]
    }
  },
  "Type": "MessageAttributes",
  "size": 1
}
'

This cURL sample includes the following options:

  • -X POST—This option changes the HTTP method to POST.

  • -H "Content-Type: application/json"—This header specifies that the server's response body is expected to be in JSON format.

  • -H 'x-fireeye-api-key: xxxxxxxxxxxxxxx'—This header specifies your personal API key.

  • https://etp.us.fireeye.com/v1/messages/trace—The email trace request URL. Replace etp.us.fireeye.com with the IP address of your Email Security — Cloud instance.

  • -d '<data>'—The attributes to search for.

Results

This example returns a list of messages with the specified attributes.

Related articles
Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy.
Products
Company
Top Features
Solutions
Existing Users
Connect With Us
Sales and Support
Copyright © Abc Inc. All Rights Reserved