FetchTestResults

After you send a test email to the EmailReach service, you will want to obtain the results. Because the EmailReach service retains test results for many tests, the primary question that the service has is to find out which results you want. You specify the results that you want by providing a set of search criteria.

In C#, the function declaration is:

TestResults FetchTestResults(string authToken, TestParams testParams)

and the WSDL declaration is:

<s:element name="FetchTestResults">
<s:complexType>
<s:sequence>
  <s:element minOccurs="0" maxOccurs="1" name="authToken" type="s:string" />
  <s:element minOccurs="0" maxOccurs="1" name="testParams" type="tns:TestParams" />
  </s:sequence>
  </s:complexType>
  </s:element>

The only required search parameters are:

• the sender’s email address
• the “includeMessage” flag
• the “matchFirst” flag

The sender’s email address is the exact address that will appear in the headers for the message in the form “a@b.com”.

Set the “includeMessage” flag to “true” if you want the email message that was received embedded in the HTML formatted document. Some services have asked to exclude this because there is no way to fully isolate the HTML in the test email from the HTML formatting of the report. If the HTML is the test email is malformed, the formatted report will also be malformed. This has caused many report failures.

The “matchFirst” flag requires a bit of background information. The web service can return only one test result, but the test parameters that you send my not be that specific and may find thousands of results. If only one can be returned, should the service return the first one in the set, or the last one? By default, the service assumes you want the most recent results and it returns the last one it finds. You can override this by setting this “matchFirst” flag to “true” which will tell the service to return the first test result it finds.

There are two other sets of criteria. The first set is the “searchBySubject” flag and the actual email subject string. You must set the “searchBySubject” flag to “true” if you want to use the subject in the search. You must also replace any special HTML characters in the subject with their equivalent HTML entities.

The second set of criteria are the “searchByDate” flag, and the “startDate” and “endDate”. You must set the “searchByDate” flag to true to specify a target date range. You may send only one date or both dates. If you send only the “startDate”, the service will examine test results for all emails received on or after that date and time. If you send only the “endDate”, the service will examine test results for all emails up to the specified date and time. This implies that if you send both, the service will examine results for all emails received between this dates and times. The service assumes these values are timestamps, and if you send only the date portion, the time defaults to midnight.  We will discuss how to use these criteria to iterate over all results in the database later in this document.

In C#, the declaration for the parameter structure is:

struct TestParams
 {
string fromAddress;
boolean searchByDate;
boolean searchBySubject;
string startDate;
string endDate;
string subject;
boolean includeMessage;
boolean matchFirst;
}

and the WSDL is:

<s:complexType name="TestParams">
<s:sequence>
  <s:element minOccurs="0" maxOccurs="1" name="fromAddress" type="s:string" />
  <s:element minOccurs="1" maxOccurs="1" name="searchByDate" type="s:boolean" />
  <s:element minOccurs="1" maxOccurs="1" name="searchBySubject" type="s:boolean" />
  <s:element minOccurs="0" maxOccurs="1" name="startDate" type="s:string" />
  <s:element minOccurs="0" maxOccurs="1" name="endDate" type="s:string" />
  <s:element minOccurs="0" maxOccurs="1" name="subject" type="s:string" />
  <s:element minOccurs="1" maxOccurs="1" name="includeMessage" type="s:boolean" />
  <s:element minOccurs="1" maxOccurs="1" name="matchFirst" type="s:boolean" />
  </s:sequence>
  </s:complexType>

The structure returned by the query contains:

• the return code for the function (discussed earlier)
• the array of test results
• a URL for  the formatted PDF report
• the HTML formatted report

In C#, the declaration for this structure is:

            struct TestResults
            {
                        int returnCode;
                        TestResult[] results;
                        string pdfUrl;
                        string testHTML;
            }

and the WSDL is:

<s:complexType name="TestResults">
<s:sequence>
  <s:element minOccurs="1" maxOccurs="1" name="returnCode" type="s:int" />
  <s:element minOccurs="0" maxOccurs="1" name="results" type="tns:ArrayOfTestResult" />
  <s:element minOccurs="0" maxOccurs="1" name="pdfUrl" type="s:string" />
  <s:element minOccurs="0" maxOccurs="1" name="testHTML" type="s:string" />
  </s:sequence>
  </s:complexType>

Each test result contains:

• information about whether the message passed the test
• prescriptive information to improve a less than positive result
• information about how the result is displayed in the preformatted reports

The “testID” field matches the “testID” field in the EmailReach configuration. The “messageID” is the value that was assigned to the sending email server.

The “result” and “score” fields provide the test quality information. The “result” field has the following values:

These are independent values for each test. The entire set of tests is complete when all values for this field are zero. It is possible that this will never occur, so you should be prepared to give up after a period of time; 20 minutes is usually long enough to wait.

The “score” field tells you whether the message passed or failed the test. It has the following values:

Any value other than zero indicates a problem. A value of one indicates the message failed the test (e.g. your message was sent to the “spam”folder), while a value of three suggests that the message might not pass the test depending on the individual recipient. A value of two indicates a problem running the test; it is probably caused by a problem in the message, such as an invalid character for the selected character set. A value of four suggests the message has not (and perhaps never will) be received by the EmailReach test server, and a value of –1 indicates that the test cannot be performed (perhaps an email service is not available).

Two fields, “app_priority” and “dashboard_priority” are provided to indicate where these results are displayed within the formatted HTML result report. The “app_priority” field has the values show below:

 
Each of these items is a tab with the same name in the formatted report. Each tab presents the results in a tree display. The level of the test result in the tree is set by the “dashboard_priority”, which has these values:

The four remaining fields, “reason”, “explanation”, “app_remedy”, “remedy” provide additional information about the test result, and changes that can be made to improve the score. The information is always provided even if the score is a passing result, so its presence is not an indicator of the result. The “app_remedy” field provides information about the target score or other judgement information. The “remedy” field provides specific measures that you might consider to improve the result. The “Reason” field and the “Explanation” field provide additional background information about the test and the way the test works.

A sample test result is shown below:

The C# declaration of the structure is:

struct TestResult
{
int testID;
string messageID;
int result;
int score;
int app_id;
int filter_id;
string reason;
string explanation;
int app_priority;
string app_remedy;
int dashboard_priority;
string remedy;
}

and the WSDL declaration is:

<s:complexType name="TestResult">
<s:sequence>
  <s:element minOccurs="1" maxOccurs="1" name="testID" type="s:int" />
  <s:element minOccurs="0" maxOccurs="1" name="messageID" type="s:string" />
  <s:element minOccurs="1" maxOccurs="1" name="result" type="s:int" />
  <s:element minOccurs="1" maxOccurs="1" name="score" type="s:int" />
  <s:element minOccurs="1" maxOccurs="1" name="app_id" type="s:int" />
  <s:element minOccurs="1" maxOccurs="1" name="filter_id" type="s:int" />
  <s:element minOccurs="0" maxOccurs="1" name="reason" type="s:string" />
  <s:element minOccurs="0" maxOccurs="1" name="explanation" type="s:string" />
  <s:element minOccurs="1" maxOccurs="1" name="app_priority" type="s:int" />
  <s:element minOccurs="0" maxOccurs="1" name="app_remedy" type="s:string" />
  <s:element minOccurs="1" maxOccurs="1" name="dashboard_priority" type="s:int" />
  <s:element minOccurs="0" maxOccurs="1" name="remedy" type="s:string" />
  </s:sequence>
  </s:complexType>