Email on Acid Spam Testing API
Standalone spam filter analysis and seed list management
OpenAPI Specification
openapi: 3.0.3
info:
title: Email on Acid Authentication Spam Testing API
description: 'REST API for automating email testing across 100+ email clients and devices, including email rendering previews, spam filter testing, seed list management, and accessibility checks. Now branded as Mailgun Inspect. Supports sandbox mode for development and test result storage for 90 days.
'
version: '5.0'
contact:
name: Email on Acid Support
url: https://www.emailonacid.com/contact/
license:
name: Proprietary
url: https://www.emailonacid.com/terms/
servers:
- url: https://api.emailonacid.com/v5
description: Email on Acid API v5
security:
- basicAuth: []
tags:
- name: Spam Testing
description: Standalone spam filter analysis and seed list management
paths:
/spam/clients:
get:
summary: Get available spam clients
operationId: getSpamClients
tags:
- Spam Testing
description: Retrieve metadata about currently active spam filter clients available for testing.
responses:
'200':
description: List of spam clients
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/SpamClient'
'401':
$ref: '#/components/responses/AccessDenied'
/spam/tests:
get:
summary: Get all spam tests
operationId: getSpamTests
tags:
- Spam Testing
description: 'Retrieve a list of all standalone spam tests, with optional filtering and pagination. Tests are stored for 90 days.
'
parameters:
- $ref: '#/components/parameters/fromDate'
- $ref: '#/components/parameters/toDate'
- $ref: '#/components/parameters/subjectFilter'
- $ref: '#/components/parameters/resultsPerPage'
- $ref: '#/components/parameters/page'
responses:
'200':
description: List of spam tests
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/TestSummary'
'401':
$ref: '#/components/responses/AccessDenied'
post:
summary: Create spam test
operationId: createSpamTest
tags:
- Spam Testing
description: 'Create and submit a standalone spam filter test. Either `html` or `url` must be provided. Supports eoa, smtp, and seed test methods.
'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSpamTestRequest'
example:
subject: My Email Subject
html: <html><body><p>Hello World</p></body></html>
transfer_encoding: 8bit
charset: utf-8
test_method: seed
from_address: my.test@example.com
responses:
'200':
description: Spam test created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSpamTestResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/AccessDenied'
'403':
$ref: '#/components/responses/PermissionError'
/spam/tests/{testId}:
get:
summary: Get spam test results
operationId: getSpamTestResults
tags:
- Spam Testing
description: Retrieve spam verdict results for a specific standalone spam test.
parameters:
- $ref: '#/components/parameters/testId'
responses:
'200':
description: Spam filter results per client
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/SpamResult'
'401':
$ref: '#/components/responses/AccessDenied'
'404':
$ref: '#/components/responses/InvalidTestID'
delete:
summary: Delete spam test
operationId: deleteSpamTest
tags:
- Spam Testing
description: Permanently delete a specific standalone spam test.
parameters:
- $ref: '#/components/parameters/testId'
responses:
'200':
description: Spam test deleted successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'401':
$ref: '#/components/responses/AccessDenied'
'404':
$ref: '#/components/responses/InvalidTestID'
/spam/tests/{testId}/seedlist:
get:
summary: Get spam test seed list
operationId: getSpamTestSeedList
tags:
- Spam Testing
description: Retrieve the seed list email addresses for a seed-method spam test.
parameters:
- $ref: '#/components/parameters/testId'
responses:
'200':
description: List of seed list email addresses
content:
application/json:
schema:
type: array
items:
type: string
format: email
'401':
$ref: '#/components/responses/AccessDenied'
'404':
$ref: '#/components/responses/InvalidTestID'
/spam/seedlist:
get:
summary: Reserve seed list
operationId: reserveSeedList
tags:
- Spam Testing
description: 'Pre-reserve a seed list before creating a spam test. Returns a key and list of seed addresses to send email to prior to test creation.
'
responses:
'200':
description: Reserved seed list key and addresses
content:
application/json:
schema:
$ref: '#/components/schemas/ReserveSeedListResponse'
'401':
$ref: '#/components/responses/AccessDenied'
components:
responses:
PermissionError:
description: Account plan does not permit this operation
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
name: PermissionError
message: Your plan does not include this feature
BadRequest:
description: Invalid request parameters or JSON
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
name: InvalidJSON
message: Malformed JSON in request body
AccessDenied:
description: Authentication failure
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
name: AccessDenied
message: Invalid API credentials
InvalidTestID:
description: Test not found or not accessible
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
name: InvalidTestID
message: Test not found or access denied
schemas:
SuccessResponse:
type: object
properties:
success:
type: boolean
example: true
CreateSpamTestRequest:
type: object
required:
- subject
properties:
subject:
type: string
description: Email subject line (encoded per transfer_encoding)
html:
type: string
description: HTML email content (required if url not provided)
url:
type: string
format: uri
description: URL to email content (required if html not provided)
transfer_encoding:
type: string
enum:
- base64
- quoted-printable
- 7bit
- 8bit
default: 8bit
description: Content transfer encoding
charset:
type: string
default: utf-8
description: Character encoding
sandbox:
type: boolean
default: false
description: Test mode without content creation
reference_id:
type: string
description: Enterprise tracking reference identifier
customer_id:
type: string
description: Required for reseller packages
test_method:
type: string
enum:
- eoa
- smtp
- seed
default: eoa
description: Spam testing method
from_address:
type: string
format: email
description: Sender email address
key:
type: string
description: Pre-generated seedlist key
smtp_info:
$ref: '#/components/schemas/SmtpInfo'
TestSummary:
type: object
properties:
id:
type: string
description: Unique test identifier
date:
type: integer
format: int64
description: Unix timestamp of test creation
type:
type: string
enum:
- email-test
- spam-test
description: Test type classification
headers:
type: object
additionalProperties:
type: string
description: Custom X-headers associated with the test
ReserveSeedListResponse:
type: object
properties:
key:
type: string
description: Pre-reserved seed list key for use in test creation
address_list:
type: array
items:
type: string
format: email
description: Seed email addresses to send email to before creating the test
SpamResult:
type: object
properties:
client:
type: string
description: Spam filter client name
type:
type: string
enum:
- b2c
- b2b
description: Spam client type (business-to-consumer or business-to-business)
spam:
type: integer
nullable: true
description: 'Spam verdict: 1 = marked as spam, 0 = neutral/no decision, -1 = not spam, null/empty = pending
'
details:
type: string
description: Additional spam filter analysis details
SpamClient:
type: object
properties:
client:
type: string
description: Spam filter client name
type:
type: string
enum:
- b2c
- b2b
description: Spam client type
description:
type: string
description: Description of the spam filter client
ErrorResponse:
type: object
properties:
error:
type: object
properties:
name:
type: string
description: Error type identifier
enum:
- AccessDenied
- RateLimited
- InvalidJSON
- InvalidParameter
- InvalidTestID
- InvalidClient
- PermissionError
- TestLimitReached
message:
type: string
description: Human-readable error description
SmtpInfo:
type: object
description: SMTP configuration for smtp test method
required:
- host
properties:
host:
type: string
description: SMTP server hostname
port:
type: integer
default: 25
description: SMTP port number
secure:
type: string
enum:
- ssl
- tls
- ''
default: ''
description: Connection security type
username:
type: string
description: SMTP authentication username
password:
type: string
description: SMTP authentication password
CreateSpamTestResponse:
type: object
properties:
id:
type: string
description: Unique spam test identifier
reference_id:
type: string
description: Enterprise reference identifier
customer_id:
type: string
description: Enterprise customer identifier
address_list:
type: array
items:
type: string
format: email
description: Seed list addresses to send email to
parameters:
resultsPerPage:
name: results
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 200
default: 50
description: Number of results to return per page
subjectFilter:
name: subject
in: query
required: false
schema:
type: string
description: Exact subject line match (case-insensitive)
page:
name: page
in: query
required: false
schema:
type: integer
minimum: 1
default: 1
description: Page number for paginated results
testId:
name: testId
in: path
required: true
schema:
type: string
description: Unique identifier for the test
fromDate:
name: from
in: query
required: false
schema:
type: string
description: Start of date range (ISO date string, Unix timestamp, or relative term like "yesterday")
toDate:
name: to
in: query
required: false
schema:
type: string
description: End of date range (ISO date string, Unix timestamp, or relative term like "yesterday")
securitySchemes:
basicAuth:
type: http
scheme: basic
description: 'HTTP Basic Authentication using `<api_key>:<account_password>` base64-encoded. Use "sandbox:sandbox" credentials for sandbox testing.
'