Getting Started

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

Use a customer API token with permission for the endpoint group you need.
Send the token in the HTTP-X-AUTH-TOKEN header.
Read access permits GET; write access also permits POST, PUT, and DELETE where the endpoint supports them.
For the recipient examples on this page, use a token with User Management permission.

Throughout this guide, $BASE_URL is the server's primary hostname, including https://.
For MailAssure, use https://client.securemail.management.
Set $API_TOKEN to your token without putting it directly into scripts or source control.

Basics

All connections use HTTPS.
Requests and responses use JSON.
Endpoint permissions and available methods depend on the endpoint group.

Most examples use curl. Python examples use the requests library for more complex JSON structures.

Check connectivity and read access by listing recipient domains:

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

This returns domains represented in the recipient list, not an inventory of all configured domains.
An empty result can be valid if there are no recipients visible to your token.

Collection URLs

The published recipient endpoint is /api-v1/recipients/.
Use the collection URL with a q query to select records, rather than adding identifiers or property names to the path.
Keep the trailing slash shown in the endpoint definition.

For example, select one recipient with both domain and local_part filters:

curl -sS --get \
  -H "HTTP-X-AUTH-TOKEN: $API_TOKEN" \
  --data-urlencode 'q={"fields":[{"field":"domain"},{"field":"local_part"},{"field":"timezone"}],"filters":[{"name":"domain","op":"==","val":"example.org"},{"name":"local_part","op":"==","val":"sam"}]}' \
  "$BASE_URL/api-v1/recipients/"

HTTP methods and request bodies

For /recipients/:

GET retrieves records selected by q, with no request body.
POST creates records from a non-empty JSON list of objects, even for one record.
PUT updates records selected by q with a JSON object.
DELETE removes records selected by q, with no request body.

Set Content-Type: application/json on requests that send JSON.
Always use explicit filters with PUT and DELETE to avoid changing every accessible record.
Log search and other read-only endpoints do not support all these methods.

Common query features

The `q` parameter

Pass q as a JSON-encoded query parameter.
The supported fields, operators, and aggregate functions are defined separately for each endpoint in the OpenAPI specifications.

Select response fields

Collection GET requests require q with a fields list.
For example, "fields":[{"field":"domain"},{"field":"local_part"}] selects two recipient fields.
Select each response name only once.

Filter records

Each comparison contains name, op, and val.
Common operators include:

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

The available operators depend on the field's type.
Use an array for the value of in and not_in.
Omit val for is_null and is_not_null.
Combine filters with nested and and or groups.

Sort, group, and count

These options belong inside q:

order_by sorts by selected response fields, with asc or desc direction.
group_by groups by selected fields supported as grouping keys.
count includes the number of rows in each result or group.
distinct removes duplicate rows.
page_count can be set to false to skip counting every matching row. The response may then omit num_results and total_pages.

Aggregate functions such as sum, avg, and group_concat are available only for fields that support them.
An aggregate response name, such as should_archive_sum, can also be used for sorting when selected.

Pagination

Pass these as separate query parameters, not inside q:

page: the page number, from 1 to 1000000.
page_size: the maximum number of results per page, from 1 to 1000.

count is a q option, not a separate query parameter.

Datetime values

Log filters accept date strings such as 2026-01-15 and datetime strings such as 2026-01-15 09:00:00.
UTC is assumed for datetime literals.
The log-query descriptions also allow relative values such as 2 days ago, although the OpenAPI validation patterns describe literal dates and datetimes only.

Example requests

Add a recipient

The required fields are domain and local_part.
Use an existing domain and send the part before @ as local_part.

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

Update a recipient's timezone

This changes only the recipient selected by both filters:

import json
import os

import requests

q = {
    "filters": [
        {"name": "domain", "op": "==", "val": "example.org"},
        {"name": "local_part", "op": "==", "val": "sam"},
    ]
}
response = requests.put(
    f"{os.environ['BASE_URL']}/api-v1/recipients/",
    headers={"HTTP-X-AUTH-TOKEN": os.environ["API_TOKEN"]},
    params={"q": json.dumps(q)},
    json={"timezone": "UTC"},
)
response.raise_for_status()