Getting Started

The SpamExperts REST API lets you automate the same core actions available in the product interface.
You can use it from any language that can send HTTPS requests and work with JSON.

To use the API, you need to request an API token from the support team.
Most endpoints require authentication with this token, given with the HTTP-X-AUTH-TOKEN header.

📘

We use the $BASE_URL variable for indicating the hostname throughout this guide. If you're a MailAssure customer, this is https://antispamcloud.com

Basics

• All connections use HTTPS.
• Requests and responses are JSON by default.
• The API follows common REST patterns.

📘

Most code examples in this guide use curl so they can be easily copy-pasted into a terminal. However, more complex requests with nested JSON structures will use python and the requests library for readability.

Prove connectivity and basic access first by checking the version:

curl -sS \
  -H "HTTP-X-AUTH-TOKEN: $API_TOKEN" \
  "$BASE_URL/api-v1/version/"

URL shapes

Most collection endpoints support multiple URL shapes:

Collection name-only

/collection/ applies to multiple instances (e.g. /address_aliases/)

Collection name with identifier

Many collections support multiple identifiers.
For example, the address_aliases collection supports a domain, local, alias_domain, alias_local.
You may use any number of identifiers, in the order they're defined in the API schema.

For address_aliases, you can use:

• /address_aliases/*domain*/ (applies to many instances)
• /address_aliases/*domain*/*local*/ (applies to many instances)
• /address_aliases/*domain*/*local*/*alias_domain*/ (applies to many instances)
• /address_aliases/*domain*/*local*/*alias_domain*/*alias_local*/ (applies to one instance)

In general, only if you include all the identifiers for a collection then the request will apply to one instance. If you omit any identifier, the request applies to multiple instances.

Collection name with identifier and property

After including the collection and identifiers, you can optionally include a property name to access or modify just that property.

For address_aliases, you can use:

• /address_aliases/*domain*/*local*/*alias_domain*/*alias_local*/relay (applies to one instance property)

❗️

Note how in the property endpoint, there is not trailing slash. For the other endpoints, the trailing slash is required. If you don't include a trailing slash, you will be redirected to the URL with the trailing slash.

HTTP Methods

Most collections support these methods:

• GET for retrieving one or more instances
• POST for creating one or more instances
• PUT for updating one or more instances
• DELETE for removing one or more instances

Request body rules

• GET and DELETE: no request body
• PUT: a JSON object
• PUT on a property endpoint: a JSON value
• POST for one instance: a JSON object
• POST for many instances: a JSON list of objects

Set Content-Type: application/json on requests that send JSON.

Common query features

The q parameter

Most endpoints support the q parameter for selecting fields, filtering, ordering, grouping, and aggregate functions.

Use fields to select which fields are returned

curl -sS --get \
  -H "HTTP-X-AUTH-TOKEN: $API_TOKEN" \
  --data-urlencode 'q={"fields":[{"field":"domain"}]}' \
  "$BASE_URL/api-v1/relays/"

📘

The fields option is required for all GET requests.

filters lets you select records that match specific criteria

Common operators include:

• ==, !=
• >, <, >=, <=
• in, not_in
• like, not_like
• ip_match
• is_null, is_not_null

Filters can be combined into Boolean expressions with and and or.

Sorting, grouping, and counts

Use these options inside q as needed:

• order_by
• group_by
• count
• distinct
• page_count

Most endpoints also support aggregate field functions such as sum and group_concat.

Other parameters

• page_size: number of results per page
• page: page number, starting at 1
• count: whether to include the total count of matching records in the response (default false)

Datetime values

Date and datetime filters can usually be expressed as:

• ISO-formatted values
• relative values such as 20 minutes ago, 2 hours ago, or 7 days ago

Example requests

List domains

curl -sS --get \
  -H "HTTP-X-AUTH-TOKEN: $API_TOKEN" \
  --data-urlencode 'q={"fields":[{"field":"domain"}]}' \
  "$BASE_URL/api-v1/relays/"

Add a domain

The minimum required fields are:

• domain
• username
• quarantine_password

If the domain contains non-ASCII characters, send the IDNA-encoded value in domain.

curl -sS \
  -H "HTTP-X-AUTH-TOKEN: $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{"domain":"api.example.org","username":"legacy","quarantine_password":""}]' \
  "$BASE_URL/api-v1/relays/"

A domain without destinations cannot process mail. In practice, include routes when you create the domain:

curl -sS \
  -H "HTTP-X-AUTH-TOKEN: $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{"domain":"api2.example.org","username":"legacy","quarantine_password":"","routes":[{"host":"mx.example.org","port":25}]}]' \
  "$BASE_URL/api-v1/relays/"