Overview

 

Consistent User Experience

We recognize that not all users prefer to send their tests via email. The concept of the API will not change. However we have made improvements across the various processes and functions that govern the API in Version 4. Version 4 API email processing has the ability to strip X-Headers from an email, and saves these headers so that the user can use them as tags for future API lookups.

 

Authentication

Every API request will require an API Key and Password. The API credentials need to be sent using HTTP Basic Authentication. We highly recommend using an SSL connection to prevent others from potentially confiscating your credentials.

 

Sandbox

There is a sandbox zone setup so you can test every request in our API without being charged. However, the sandbox will always return the same result for each individual API request. The sandbox can be accessed by using the following URL (not available via SSL):

http://sandbox.emailonacid.com/v4/

More detailed sandbox calls can be found under the individual API pages.

 

RESTful

Our API uses a RESTful architecture, accepting and returning either XML or JSON. The system will only accept POST requests and must contain the following HTTP headers:

XML:

Accept: application/xml
Content-Type: application/xml

JSON:

Accept: application/json
Content-Type: application/json

If those headers are not present, an error will be generated and sent as the response. Details on errors are described here.

 

Request Validation

Every API request will be validated prior to processing. For XML requests, it will be done against our .XSD file. For JSON requests, each request has an individual JSON Schema it will be validated against, created with JSON Schema.

If the request does not validate, an error will be generated and sent as the response. The .XSD file can be downloaded here. The JSON Schema files can be found under each API request's page.

 

Client Frames

Client frames are images that test results are shown inside of. For example, on an iPhone 6 result, the image of an iPhone 6 is the "client frame".

Download Client Frames  

API Inbox Submission

Starting with V4, API Tests may be submitted by emailing your test content directly to us. Submitting tests this way helps to avoid any unintended issues with content being adjusted due to formatting or storage issues prior to sending it out for testing.

To submit an API Inbox test, simply send your test email to the API Email GUID address provided to you with your credentials. If you need this information, please contact support@emailonacid.com for assistance.

X-Headers

When sending in your tests, you can supply custom X-Headers along with your test content, which we store to assist in test retrieval. As a rule, all custom X-Headers beginning with "X-EOA" are reserved.

You may also use the following predefined X-Headers to overwrite the clients used for a single Email Test:

X-Header Description
X-EOA-CLIENTS

Corresponds to getClientList's response object email_client->clients->client->client_code where code_preview is FALSE

X-EOA-CODEBASES

Corresponds to getClientList's response object email_client->clients->client->client_code where code_preview is TRUE

X-EOA-BROWSERCODES

Corresponds to getClientList's response object email_client->browsers->browser->code


A number of codes may be strung together using pipes ( | ) to separate values. Therefore a set of identifiers may be sent at once without with proper concatenation with a character limit of up to 998 characters per line, per RFC #2822 and 5322. Below is an example of how the API expects the codes to be formatted. Input that does not follow this format will result in tests not being run for the malformed parameters:


X-EOA-CLIENTS: |9|
X-EOA-BROWSERCODES: |8_1_8|14_1_4|16_1_14|
X-EOA-CODEBASES: |26|36|
    

Additionally, the following predefined X-Headers can be used to specify several parameters from the createTest call to assist in tracking:

X-Header Description
X-EOA-USER-GUID

Corresponds to createTest's request object user_guid

X-EOA-REFERENCE-ID

Corresponds to createTest's request object test_id


Below is an example of how the API expects these fields to be formatted. Input that does not follow this format may result in tests not being created:


X-EOA-USER-GUID: USER_GUID_VALUE
X-EOA-REFERENCE-ID: CUSTOMER_REFERENCE_ID_VALUE
    

For an example of how to set custom X-Headers for various clients, see the following link, or consult your ESP or mail client documentation:

Test Retrieval

After sending a test, the API Inbox process will handle the email and submit it as an API test.

You can now use the GetTestList API call to look up submitted tests using either the date range sent, and/or x-header names and values.

You may then use the returned eoa_test_ids with any other calls to get desired API information.

 

API Test Storage

API Test results are stored on our servers for 30 days after a test has been processed. After 30 days the results will be removed from our system. We do this for the following purposes:

  1. To let you be in complete control of your results
  2. So there is no dependence on our system for archived results
  3. Disk usage
  4. Bandwidth usage

Note: All of the original API requests will be stored indefinitely for reporting purposes.

 

API Error Codes

Our API will return an error (or exception) if something goes wrong in the processing or your request contains incomplete/invalid data.

Note: All error responses will also have a Status Code of 400 or greater, depending on the error.

Error Response:

XML:

<?xml version="1.0" encoding="utf-8"?>
<xml>
	<error>
		<error_type>EOAExcpetion:InvalidTestID</error_type>
		<message>The test ID you have requested could not be found. It may be that the test does 
exist but the account you're authenticating with does not have access to it.</message> </error> </xml>

JSON:

{   "error":
    [
        {   "error_type":"EOAException:InvalidTestID",
            "message":"The Test ID you have requested could not be found. It may be that the test does exist but the account you're authenticating with does not have access to it."
        }
    ]
}

Error Types and Messages:

Type Message
EOAException:InvalidContentType Invalid Header Content-Type and Content-Accept values. These must both be present and set to application/xml, or application/json for Version 4 or newer.
EOAException:InvalidXML Your POSTed XML failed to parse. Please check its validity.
EOAException:InvalidXMLFormat The XML supplied did not validate against our XSD. Please review our XSD and update your XML accordingly.
EOAException:InvalidJSON Your POSTed JSON failed to parse. Please check its validity.
EOAException:InvalidJSONFormat The JSON supplied did not validate against our JSON Schema. Please review our JSON Schema file and update your JSON accordingly.
EOAException:NotImplemented You're attempting to request a resource that doesn't exist, or requesting an existing resource with an unsupported request method.
EOAException:InvalidContent An error has occurred while loading your email content. It appears that all of your email content was removed after we ran it through our content filters. Please check your email content and try the test again.
EOAException:NoHTML Missing HTML content.
EOAException:InvalidURL Our system couldn't load the URL you entered. Please verify the URL and try again.
EOAException:InvalidHtmlContent The POSTed HTML is not in Base64 format. Please resubmit the request with the HTML base64 encoded.
EOAException:InvalidSubject The Subject is not in Base64 format. Please resubmit the request with the Subject base64 encoded.
EOAException:InvalidTestID The test ID you have requested could not be found. It may be that the test does exist but the account you're authenticating with does not have access to it.
EOAException:MissingTestID Missing Email Test ID.
EOAException:NonNumericTestID Email Test ID must be numeric.
EOAException:NoSpamResults There are no spam results for the supplied Email Test ID.
EOAException:InvalidSeedKey The Seed List Key you provided is not valid. Please verify the Seed Key and try again.
EOAException:SMTPAuthentication Our system was unable to authenticate with your SMTP/MTA. Please verify the SMTP Information and try again. The authentication details are as follows:
EOAException:InvalidEncodingType Invalid Transfer-Encoding value. Acceptable values are: 7bit, 8bit, base64, binary or quoted-printable.
EOAException:InvalidCharSet Invalid Charset value.
EOAException:InvalidClientID The client_code you have requested could not be found. It may be that the code does not exist or that it is no longer supported.
EOAException:InvalidClientIDFree The client_code you have requested could not be found. It may be that the code does not exist or that it is not supported for free tests.
EOAException:InvalidIP The IP Address that was submitted is not valid. Please verify the IP Address and try again.
EOAException:MissingUserGUID User GUID must be set.
EOAException:Deprecated This call has been deprecated. Please check the documentation for updated method <Call Name>
EOAException:AccessDenied You do not have permission to access this call.
EOAException:TestLimitReached Test limit reached. Test will not be processed.