Introduction

The EmailReach API was designed so our customers can obtain the results of EmailReach’s test suite upon the emails that they typically send to their customers. The API's design assumes you have sent a uniquely identifiable message, and you want a report of the test results for this single test.The core capabilities of our API are presented below.

EmailReach’s testing suite helps you determine what happens to your email messages when email service providers receive them. The EmailReach system does this by maintaining a set of email accounts with various service providers, and then periodically   polling these services for results.

Our system reports the results that it has gathered whenever it looks for new test messages. The challenge in this method is that the service has to aggregate results from many services into a single report. It does this using a simple rule: all results received for messages with the same email subject from the same email address within a 15 minute window will be combined into a single set of results.

This means that your system needs to perform some tasks of its own. First, your system will have to send the email and keep track of which emails it sent. Next, it will have to wait for the emails to be received and for the results to be aggregated. Finally, it will have to understand that clocks on servers don’t always agree, that the EmailReach servers and your servers may not be in the same time zone, and that it takes real time for email to travel from the sender to the receiver.

The general email testing workflow is:

1): A test email is prepared. A unique subject is assigned to it so you can identify not just this message but this specific test of this message. Your test email must be submitted from an email address which is registered in your EmailReach account profile.

2): The test email is sent. We recommend that you keep a record of this event. A timestamp should be retained to identify the starting time for a search range.

3): Wait at least 15 minutes. EmailReach has determined that very few additional results will be obtained by waiting more than 20 minutes.

4): Send a request for results via the API to the EmailReach system. If it fails to return any results, and assuming you provided a truly unique subject, move the starting time for the search back at least 24 hours (or possibly remove it entirely) and try again. You have probably run into to differences in the way time zones are handled. The EmailReach servers are in the US Pacific Time Zone, which is GMT minus 7 or 8 (depending on whether Daylight Saving Time is in effect). To avoid concerns about the date when the message was received, it’s best to just back the starting time up a full day.

5): After your test results are received, you may prepare your own report using the test configuration information and the results, or you can embed the EmailReach HTML or PDF reports into your webpage.

The API does not provide facilities for building lists of test results. It is possible to do this, but the API may take a minute to respond to each request because it always prepares complete HTML and PDF reports. This also means that the API will return the results for a single test regardless of the number of test sets discovered by your query, so you will have to send numerous requests to discover all available test sets. If this is something that you’d like to do on a regular basis, we suggest building your own separate application that can obtain this information in the background.