Function Reference

Return Codes

All of the API functions return an integer value that indicates whether the API was able to process the request. These codes do not provide any information about the tests; they simply indicate whether or not the request was processed at all. The current values are:

The value of “OK” indicates that the API processed the request and that it is able to return whatever information is available. In the case of test results, this value does not guarantee that any specific results are present (because the email may not have ever arrived at the EmailReach servers for example), it just indicates that the API was able to run a query against the test results server and that this query was processed correctly.

The value of “InvalidAuthToken” indicates that the authentication token that you provided is not valid. It is possible that it was valid at some time in the past, but, since authentication tokens have a limited lifetime, this lifetime may have expired and is not valid now. The solution to this problem is to call “GetAuthToken” and obtain a new authentication token.

Two additional return codes are possible if you are trying to register a new email address: “EmailAddressExists” and “EmailAddressError”. The first code, “EmailAddressExists”, indicates that the email address is already registered to another user and you may not register it. The second code, “EmailAddressError” indicates that the email address is either null or an empty string, or it was found in the database but the API cannot associate it with any user.

The “InvalidMessageID” return code is returned by the “FetchMessage” function when the email message ID is null, the empty string or it contains invalid characters. The “UserHasNoAccess” return code indicates that the email ID was found, but that message is associated with a user account other than the one indicated by the authentication token. This can happen when the same server handles messages for multiple clients and one client tries to see the test email for another client.

The last two codes are returned by “FetchTestResults”. This function can return three values that have the following meanings:

This combination is needed because the EmailReach servers cannot determine when a test is absolutely complete. Email servers can hold an email message for days before processing it, and, since a single test may require sending an email to 20 email addresses all supported by different providers, there is a chance that at least one email service will fail to process a message.