Transactional Email tracks emails on a per-message basis, so opens, clicks and delivery data are tracked for individual emails sent through your account. You can add tags and metadata to give further context to the emails you send.
Transactional Email automatically indexes a number of fields that you can use to search or find interesting trends relevant to your sending. Searching is available in the web application and via the API.
Date Ranges
Before you get started, it's important to note how long messages are searchable in Transactional Email. Detailed information for delivered messages is stored for 30 days, while bounced message data is kept for 90 days for record-keeping purposes. Stats for the account and tag-based stats are stored indefinitely. Overall stats can be viewed on the Dashboard of your Transactional Email account or using the senders, tags, and templates API calls.
Query Syntax
Transactional Email searches utilize Lucene queries, and by default we search all indexed fields for your search terms (unless a field is specified).
From the Lucene documentation:
A query is broken up into terms and operators. There are two types of terms: Single Terms and Phrases.
A Single Term is a single word such as "test" or "hello".
A Phrase is a group of words surrounded by double quotes such as "hello dolly".
Multiple terms can be combined together with Boolean operators to form a more complex query.
Transactional Email supports all of the boolean operators like AND, OR, and NOT, along with wildcards (* for multiple character and ? for single-character wildcards—just do not start a search with a wildcard).
If you want to search a specific field for something, use the field name followed by a colon and then your search term or phrase. The following fields are indexed by Transactional Email and can be used for searching message data:
| Field Name | Description |
|---|---|
| state | Search by the status of the email. Options are 'sent', 'bounced', 'soft-bounced', 'rejected', 'spam', and 'unsub' |
| sender | Search the sender/from email address for the message |
| ts | Unix timestamp when the message was sent. Supports searching a range, such as ts:[START_TIME TO STOP_TIME] where START_TIME is the starting time, and STOP_TIME is the end time for the range. |
| full_email | Search the full email address for the recipient |
| A tokenized field for recipient email address | |
| subject | The subject line of the message |
| tags | The tags applied to the message |
| opens.ts | Unix timestamp when the recipient opened the message. Supports searching a range, such as opens.ts:[START_TIME TO STOP_TIME] where START_TIME is the starting time, and STOP_TIME is the end time for the range. |
| opens.location | Search for the location where a recipient opened the message. |
| opens.ua | Search based on the user-agent detected for an open event. Value is 'null' if no user-agent is detected. |
| opens.ip | Search based on the IP address where an open originated. |
| clicks.ts | Unix timestamp when the recipient clicked a tracked URL in the message. Supports searching a range, such as clicks.ts:[START_TIME TO STOP_TIME] where START_TIME is the starting time, and STOP_TIME is the end time for the range. |
| clicks.location | Search for the location where a recipient clicked the message. |
| clicks.ua | Search based on the user-agent detected for a click event. Value is 'null' if no user-agent is detected. |
| clicks.ip | Search based on the IP address where a click originated. |
| url | Use to search for messages where the recipient clicked on a specific URL or URL pattern |
| u_metadatafield | Search your indexed custom metadata field, where metadatafield is the name of the field. |
| subaccount | Search by the subaccount ID that sent the message. Supports wildcards. |
| smtp_events.ts | Unix timestamp when the SMTP event occurred. Supports searching a range, such as smtp_events.ts:[START_TIME TO STOP_TIME] where START_TIME is the starting time, and STOP_TIME is the end time for the range. |
| smtp_events.type | Search the event type. Options are 'sent' and 'deferred'. |
| smtp_events.diag | Search the SMTP diagnostic messages for a keyword or phrase. |
| smtp_events.source_ip | Search by the Transactional Email source IP that sent the message. |
| smtp_events.destination_ip | Search the destination IP that Transactional Email connected to in order to deliver the message. |
| smtp_events.size | Search based on the size of the SMTP message in bytes. Supports searching a range such as smtp_events.size:[MINIMUM TO MAXIMUM] where MINIMUM is the starting time, and MAXIMUM is the end time for the range. |
Examples
subject:welcome OR subject:bienvenidos
Searches messages that contain 'welcome' or 'bienvenidos' in the subject line
full_email:joe@domain.* AND sender:me@company.com
Searches for messages sent to recipients whose email addresses start with joe@domain (to capture, for example joe@domain.com, joe@domain.net and joe@domain.org) that were also sent by me@company.com
email:gmail.com
Searches for all recipients with 'gmail.com' in the address. If you have a recipient with the address gmail.com@domain.com, that will also be included in this search, but this will generally return all recipients for the gmail.com domain.
ts:[1349049600 TO 1349053200] AND subject:"Order Receipt" AND opens.ts:[1349049600 TO 1349056800]
Searches messages which were:
- Sent between 1349049600 Unix Time (October 1, 2012, 00:00:00 GMT) and 1349053200 Unix Time (October 1, 2012, 01:00:00 GMT); and
- That have a subject line that contains the phrase "Order Receipt"; and
-
Which were opened between 1349049600 Unix Time (October 1, 2012, 00:00:00 GMT) and 1349056800 (October 1, 2012, 02:00:00 GMT).
url:twitter.com OR url:facebook.com
Searches for messages where the recipients clicked URLs that start with either twitter.com or facebook.com
tags:Welcome AND tags:a_test
Searches for messages that are tagged with both 'Welcome' and 'a_test'