Email Scout Reports

Email Scout Reports email log search results to report recipients.
Use a token with Email Scout Reports Management permission for the relevant filter direction.
Read access permits listing reports; write access also permits creating, updating, and deleting them.

Report endpoints

The published scheduled-report collections are:

Incoming filter: /api-v1/periodic_reports_delivery/
Outgoing filter: /api-v1/periodic_reports_submission/

The specifications also expose /api-v1/domain_delivery_periodic_reports/ and /api-v1/domain_submission_periodic_reports/ for domain reports.
These use the same delivery and submission report schemas, respectively.

Use the collection URL with q filters to select a domain or report ID.
Do not add a domain or ID to the URLs used in these examples.

Report fields

Both delivery and submission reports expose:

id, a read-only integer
domain
name
destination
from_address
subject
query
template_name
schedule
report_state
disabled
pdf_report

Delivery reports also expose recipient. Submission reports expose sender instead.
The published schemas do not expose minute, hour, day, month, weekday, next_scheduled, owner, or include_standard_branding.
Use the string-valued schedule field rather than separate cron fields.
For example, 0 9 * * * represents a daily 09:00 schedule.

The query field is a JSON-encoded string containing a log search query, not a nested JSON object.
It must include fields and use fields supported by the corresponding delivery or submission log endpoint.

The published subject pattern permits ASCII letters, digits, spaces, and _@:/,=- only.

Example: list incoming-filter reports

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

Example: find an outgoing-filter report

Filter by both domain and report ID. Replace 123 with an existing report ID.
The response is still a collection response.

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

Example: create an outgoing-filter report

The required fields are destination, domain, name, and query.
Send a non-empty JSON list, even when creating only one report.
This example adds a daily schedule and limits the stored log query to the report's domain.

curl -sS \
  -H "Content-Type: application/json" \
  -H "HTTP-X-AUTH-TOKEN: $API_TOKEN" \
  --data '[
    {
      "domain": "api.example.org",
      "destination": "[email protected]",
      "name": "Example report",
      "report_state": false,
      "sender": "[email protected]",
      "subject": "Example ESR",
      "schedule": "0 9 * * *",
      "query": "{\"fields\":[{\"field\":\"message_id\"},{\"field\":\"datetime\"},{\"field\":\"sender\"}],\"order_by\":[{\"field\":\"datetime\",\"direction\":\"desc\"}],\"filters\":[{\"name\":\"domain\",\"op\":\"==\",\"val\":\"api.example.org\"}]}"
    }
  ]' \
  "$BASE_URL/api-v1/periodic_reports_submission/"

Templates and previews

Reports can refer to an existing template using template_name.
Template listing and editing endpoints are deliberately excluded from the customer-token API.

The published preview endpoints are:

Incoming filter: POST /api-v1/preview_report_template/domain_delivery/
Outgoing filter: POST /api-v1/preview_report_template/domain_submission/

Send a JSON object with:

domain, required and non-empty
custom_template, required
from_address, optional
subject, optional

The preview contract does not include template_name or a q parameter.
Its custom_template and subject patterns permit ASCII letters, digits, spaces, and _@:/,=- only.
HTML and Jinja2 markup are outside this published subset, so the example uses plain text.

Example: preview an incoming-filter report

curl -sS \
  -H "HTTP-X-AUTH-TOKEN: $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.org","custom_template":"Email Scout Report preview","from_address":"[email protected]","subject":"ESR preview"}' \
  "$BASE_URL/api-v1/preview_report_template/domain_delivery/"

Automatic ESR

Automatic ESR manages incoming-filter report settings for detected mailboxes.
The published endpoints are:

/api-v1/auto_esr_settings/
/api-v1/auto_esr_exclusions/

Settings expose id, domain, name, query, schedule, from_address, subject, template_name, legacy, pdf_report, distribution_list_esr, shared_mailbox_esr, and send_welcome_email.
The id is read-only. Creating settings requires domain, name, and query.
The settings schema does not expose a timezone or an embedded exclusions field.

Exclusions are separate records with id, auto_esr_id, domain, and local_part.
The id is read-only. Creating an exclusion requires auto_esr_id, domain, and local_part.
Use auto_esr_id to associate an exclusion with its settings record.

Example: list automatic ESR settings for a domain

curl -sS --get \
  -H "HTTP-X-AUTH-TOKEN: $API_TOKEN" \
  --data-urlencode 'page_size=1' \
  --data-urlencode 'q={"fields":[{"field":"id"},{"field":"domain"},{"field":"legacy"},{"field":"schedule"}],"filters":[{"name":"domain","op":"==","val":"api.example.org"}]}' \
  "$BASE_URL/api-v1/auto_esr_settings/"

Example: find an automatic ESR exclusion

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