API Documentation


Postman Integration

Email on Acid has a Postman Collection available for quick and easy exercise of our REST-based APIs. Variables for API credentials and other data elements can be found at the collection level. Use the button below for easy import into Postman. Don’t have Postman? Click here.



All calls in this version are JSON, and must be authenticated with HTTP Basic Authentication. You will be provided with an API key, and your password is configurable through the web portal. The header should be the string <api_key>:<account_password> encoded in base-64. An example of this header is below.

Authorization: Basic WW91ck93bkFjY291bnRzRW1haWxPbkFjaWRBUElLZXkwMTIzNDU2Nzg5OllvdXJTZWN1cmVQYXNzd29yZA==

Testing Your Settings


GET https://api.emailonacid.com/v5/auth

Example Response:

    "success": true

This URL will respond with error information if your request was set incorrectly.



If you wish to try our API, you can access it through a sandbox mode. Submit your request with the username and password of "sandbox".



The API seeks to follow broad tenets of RESTful application within each resource type, but is not strictly constrained by those standards. Each method will describe an endpoint and HTTP method to use to access it.


We expect each request with a body to be provided as JSON, and if an Accept header is provided, it must accept application/json

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

If the header does not match, an error will be generated and sent as the response. Details on errors can be found further down this page.


Request Validation

This API seeks to be as permissive as possible with all requests — if we can understand it, we will use it. As you go through these docs, each call will explain which fields are required. If we cannot understand your request, an error will be returned explaining how to fix your request.


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". We provide these images free of charge to create a more immersive experience for your application.

Download Client Frames  

Auto Inbox Submission

Email Tests may be submitted by emailing your test content directly to us. This helps eliminate any potential discrepancies from the processing of your content prior to the send. We recommend this method if you do not control the final content of your send.

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

To submit an Auto-Inbox test with a customer_id, you can use the "+" delimiter to attach the customer_id to your Auto-Inbox address, for example ZEv8x0fhjMAMSPL310MN+customer_id_here@api.mail.emailonacid.com. This allows our platform to accept emails directly from your customers and associate them with your API account.

X-Headers (Enterprise Only)

Enterprise customers can supply custom X-Headers along with test content, which we store to assist in test retrieval. As a rule, all custom X-Headers beginning with "X-EOA" are reserved for our use, but we will track any other X-Header provided.

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

X-Header Description

A comma-separated list of client IDs as returned from the client list method.

A set of identifiers may be sent at once 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: outlook03,outlook10,iphone6p9,gmail_chr22_win

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

X-Header Description

Corresponds to customer_id in the create email test request body.


Corresponds to reference_id in the create email test request body.

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:


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 Auto Inbox process will handle the email and submit it as an Email Test.

You can use the get test list API call to look up submitted tests.


Test Storage

Test results are stored on our servers for 90 days after a test has been processed. After 90 days the results will be removed from our system. This allows us to keep your results as fast as possible — though we will store the metadata internally for reporting purposes.


Micro Versions

These are incremental updates to add new functionality to existing API calls. To access them, simply use the micro version in place of "v5" in your existing API calls. Current Micro versions and their features are detailed below.

Current Micro Versions & Features



GET https://api.emailonacid.com/v5.0.1/auth

  • This version adds the "full thumbnail" element to the Email Testing Get Results call, which provides a URL to full-length thumbnails for each result, instead of the fixed-height ones returned in the "thumbnail" element.


API Errors

Our API will return an error 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:

{   "error":
    {   "name":"PermissionError",
        "message":"You do not have permission to access this resource"

Error Types and Messages:

Type Message
NoAccept Invalid Accept header values. If set, this value must accept application/json.
AccessDenied Your authentication to the API did not succeed. See the message for details on resolving the problem.
RateLimited You have made more requests to the API than your pricing plan allows. If you need more requests, please contact support.
InvalidJSON Your JSON failed to parse. Please check its validity.
WrongVersion You are trying to access the API with an incompatible version.
InvalidParameter Your GET query string was not parseable. See the message for further details.
NotFound The URL you requested could not be found.
BadMethod Your request used an unimplemented method. See the response's Accept header.
BadRequest There was a problem with your request. See the message for more details.
ServerError There was a problem processing your request. See the message for more details.
ProcessingError There was a problem processing your request. See the message for more details.
TestLimitReached For enterprise customers on a user-priced plan, the provided user has hit your established monthly test limit.
PermissionError Your plan does not provide access to this feature.
InvalidTestID The test ID provided could not be found or you do not have access to it.
NoClient A required client code URL parameter is missing.
NoClients A required clients parameter is missing.
InvalidClient The client code(s) provided could not be found.
InvalidFreeClient The mentioned clients are not included in free tests.
InvalidTestClient The mentioned clients could not be found in this test.
ClientNotFound The client code URL parameter provided could not be found in this test.
NoSubject A required subject field was missing.
NoSource You must provide either an HTML or URL source.
InvalidURL The URL source provided was invalid.
MissingCustomerID The enterprise package you are on requires a customer_id to be included.
SMTPError The SMTP credentials had an invalid hostname.
SMTPAuthenticationError The SMTP credentials provided could not be validated.
InvalidSpamType You submitted a test with an invalid type. Must be one of "eoa", "smtp", or "seed"
NoSpamResults This test was not run with spam processing.
NoSeedList This test was not run with seed list spam processing.