API Overview

API Functions

The EmailReach Web Service API provides the following functions:

  • GetAuthToken
  • RegisterNewTestEmailAddress
  • FetchEmailReachConfiguration
  • FetchTestResults
  • FetchMessage

Every function except the “GetAuthToken” function requires an “AuthenticationObject”. This object is returned by the “GetAuthToken” function. The “AuthenticationObject” has a limited lifetime of 20 minutes, so while you do not need to “logout”, and you may use the object for many requests, this “key” will eventually expire and your code must be prepared for this. The alternative is to request a new key for every operation. The latter method is easier to code, safer and requires little overhead given modern network speeds.

Each email to be tested must be sent from a registered email address; the system ignores emails from unregistered addresses. Email addresses can be configured via the EmailReach web site, but the “RegisterNewTestEmailAddress” function is provided as a “convenience method” in case your customer needs to register a new email address as they are developing test emails.

You may also find it useful to tell your customers what tests will be run when the email is sent to the test system. You obtain the current test settings by calling the “FetchEmailReachConfiguration” function.

Once the message has been sent, you can begin polling for results by calling the “FetchTestResults” method. Each time you call this method it will return whatever results are available at that time. As much as 20 minutes can elapse from the time your servers send an email message until the test results are available, so you need to be prepared to either wait many minutes before calling this method or you must call this method many times while waiting for results. The number of tests run and the results of these tests will change during this polling time.

Once you have the results, you may want to obtain the message that the system received. This will allow your customer to verify that the entire message was received, and to determine if the message was modified by the process.