Get Clients

This call returns a list of our currently active spam clients with some information about them.

URLs:

GET https://api.emailonacid.com/v5/spam/clients

Example Response:

[
  {
    "client": "SPAM CLIENT 1",
    "type": "b2c",
    "description": "SPAM CLIENT DESCRIPTION"
  },
  {
    "client": "SPAM CLIENT 2",
    "type": "b2b",
    "description": "SPAM CLIENT DESCRIPTION"
  }
]

Create Spam Test

This call creates a new spam test and submits it to our system for processing.

All requests must contain a subject property and one source property (either html or url). Customers on a user-based reseller package must provide the customer_id as well. All other properties are optional. In the following table, each property and its default value is shown.

The test_method property determines the method we use to run your spam test. There are three options described here in order of accuracy.

Seed List Testing

We will provide you with a list of addresses and you will send your email through your preferred ESP or application to all of the addresses. The accuracy of this method depends on how similar your test send is to your production send.

SMTP Testing

SMTP testing works by providing us with credentials to your SMTP server that we then use to send the email. Because the sending method will differ, we cannot be certain that production results will look identical. Depending on the settings of your domain, this can result in both false negatives and false positives.

EOA Testing

Email on Acid will send the email from our servers and check the spam results. This will check for email content, subject line, and sender email address performance.

URL:

POST https://api.emailonacid.com/v5/spam/tests

Example Request Body:

{
  "subject": "My Email Subject",
  "html": "My HTML",
  "transfer_encoding": "8bit",
  "charset": "utf-8",
  "reference_id": "123ABC",
  "customer_id": "1",
  "test_method": "seed",
  "from_address": "my.test@example.com"
}

Example Response:

{
  "id": "<UNIQUE ID>",
  "reference_id": "123ABC",
  "customer_id": "1",
  "address_list": [
    "spam_address1@example.com",
    "spam_address2@example.com"
  ]
}

Request Details

Element Type Description Default
subject String The subject line of your email, encoded as declared in transfer_encoding. None; Required
html String The email source of your email, encoded as declared in transfer_encoding. None; Required if no url
url String A URL pointing to the email source of your email. None; Required if no html
transfer_encoding String One of base64, quoted-printable, 7bit, or 8bit. 8bit; subject and html should be encoded as described by this field.
charset String The character set your HTML is encoded in. utf-8; subject and html should be encoded as described by this field.
sandbox Boolean If true, run without creating any actual content. false
reference_id String Enterprise customers can set this value for searching and internal reporting. None; Enterprise only
customer_id String Enterprise customers can set this value for searching and internal reporting. None; Enterprise only
tags Array of String Non-Enterprise customers can set this value for searching and tagging. None; Non-Enterprise only
test_method String One of "eoa", "smtp", or "seed". The meanings of these values are explained in the Spam Test section. "eoa"
smtp_info Object An object containing the SMTP Authentication info. None; Required if test_method is "smtp"
smtp_info->host String The SMTP host. None; Required
smtp_info->port Integer The SMTP port. 25
smtp_info->secure String One of "ssl", "tls", or "". ""
smtp_info->username String The SMTP username. None
smtp_info->password String The SMTP password. None
from_address String Address to send the email from. None
key String Seedlist Key to use. Generated ahead of time using Reserve Seed List. None; Optional if test_method is "seed"

Get Tests

This call returns a list of all available Spam Tests and some metadata about them. Spam Tests are stored for 90 days.

URL:

GET https://api.emailonacid.com/v5/spam/tests

Example Response:

[
  {
    "id": "<test_id>",
    "date": 1585408493,
    "type": "email-test",
    "headers": {
        "X-EXAMPLE": "My Header"
    }
  },
  {
    "id": "<test_id>",
    "date": 1585408493,
    "type": "spam-test",
    "headers": {}
  }
]

Search Tests

This call returns a list of Spam Tests that match the criteria in the query string and some metadata about them. Its structure is identical to the above call.

The query string is a standard URL parameterized version containing any or all of the following parameters.

URL:

GET https://api.emailonacid.com/v5/spam/tests?<query_string>

Query String Details

Name Description Example
from The starting point of your test date range. from=2020-03-28 15:14:53, from=1585408493, from=yesterday
to The ending point of your test date range. to=2020-03-28 15:14:53, to=1585408493, to=yesterday
subject The "subject" field of returned tests must contain the exact string. This search is case-insensitive. subject=My+example+test, subject=Another%20example, subject=A%2B tests
headers Enterprise users can use this field in a KV array of x-headers submitted with the test. This is an AND match, meaning all headers must be present to return. headers[x-fun]=most+fun&headers[x-cake]=best+cake
tags Non-enterprise customers can use this field as an array of tags submitted with the test. This is an AND match, meaning all tags must be present to return. tags[]=most&tags[]=fun&tags[]=best&tags[]=cake
results The number of results to return. Must be between 1 and 200. The default value is 50 results=50
page The page number. If you submit a number higher than the number of pages in the data, an empty array will be returned. The default value is 1 page=2

Get Results

This call returns an object containing the status of your spam result.

URL:

GET https://api.emailonacid.com/v5/spam/tests/<test_id>

Example Response:

[
  {
    "client": "SPAM CLIENT 1",
    "type": "b2c",
    "spam": 1,
    "details": "SPAM DETAILS"
  },
  {
    "client": "SPAM CLIENT 2",
    "type": "b2b",
    "spam": -1,
    "details": ""
  }
]

Response Details

Element Description
client The name of the spam client.
type Either b2b (Business-to-Business) or b2c (Business-to-Customer), indicating whether the spam filter is typically deployed in corporate email systems or for personal email accounts.
spam Whether this message was marked as spam. 1 indicates it was spam; 0 indicates no decision (or "neutral"); -1 indicates it was not spam. An empty value means this filter has not returned.
details If a filter provides additional details, they will be returned here.

Delete Test

This call marks a Spam Test as deleted. Once it is deleted, it cannot be recovered.

URL:

DELETE https://api.emailonacid.com/v5/spam/tests/<test_id>

Example Response:

{
  "success": true
}

Get Seed List

This call returns a list of email addresses to send to for your seed list type spam test. If your spam test was not a seed list type, you will receive an error.

URL:

GET https://api.emailonacid.com/v5/spam/tests/<test_id>/seedlist

Example Response:

[
  "address1@example.com",
  "address2@example.com"
]

Reserve Seed List

This call reserves a list of email addresses to send to for your seed list type spam test. This call is only necessary if you need to have the seed list prior to test creation. The key value must be provided when you create a Spam Test or Email Test with spam included, in order to override the system-generated value.

URL:

GET https://api.emailonacid.com/v5/spam/seedlist

Example Response:

{
    "key": "EXAMPLE",
    "address_list": [
        "EXAMPLE@spc.emailonacid.com",
        "cloudmark+EXAMPLE@cm.emailonacid.com",
    ]
}