Read deliverability analytics

The Deliverability API exposes the analytics behind the builders.ac Deliverability view. It is read-only and account-scoped: a credential can see only the senders and domains owned by its builders.ac account.

Deliverability APIv1alpha1Alpha / unstable

Base URL

https://api.builders.ac/api/deliverability/v1alpha1

API Key

age1…The same credential used by Mailbox v1beta1 and Provisioning.

v1alpha1 is unstable

This API is an alpha. Endpoint names, response fields, and availability rules can change before a stable release. Keep your client deployable and validate optional data.

Authenticate

Create a shared credential on the API credentials page. Send its age1… API Key as the bearer token. The paired API Secret is not used for Deliverability requests.

export BASE=https://api.builders.ac/api/deliverability/v1alpha1
export KEY=age1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

curl "$BASE/summary?range=7d" \
-H "Authorization: Bearer $KEY"

The same API Key also authenticates Mailbox v1beta1 and the internal-testing Provisioning v1alpha1 API.

Resources

Request	Returns
GET /summary	Traffic totals plus per-domain counts and percentages
GET /timeseries	Hourly or daily traffic points for the selected range
GET /bounces	Hard, soft, and pending bounce totals, ESP buckets, trend, and per-domain rates
GET /esp-distribution	Selected traffic classifications grouped into Microsoft, Google, and other providers
GET /checks	Check catalogue, 28-day status history, and current blacklist overview
GET /checks/{check}/results	Per-domain result details for one returned check and date

The complete request and response schemas are in the Deliverability reference.

Filters and ranges

Traffic endpoints accept these shared query parameters:

Parameter	Values	Default
range	1h, 8h, 24h, 3d, 7d, 14d	7d
sender_id	One account-owned snd_… TypeID	all senders
domain_id	One account-owned dom_… TypeID	all domains

/checks and /checks/{check}/results accept the sender and domain filters, but their history remains the fixed 28-day check window. Unknown or account-external filter IDs do not broaden a query.

For example:

curl -G "$BASE/timeseries" \
-H "Authorization: Bearer $KEY" \
--data-urlencode 'range=14d' \
--data-urlencode "domain_id=$DOMAIN_ID"

The response meta states the effective range, granularity, classification watermark, and computation time. Treat nullable metric values as unavailable, not as zero.

Traffic and bounces

Use /summary for KPI cards and per-domain comparison. Use /timeseries when you need the trend itself. The metrics distinguish sent, received, outreach, warmup, reply, autoresponse, other, and system traffic.

/bounces reports absolute counts even when a trustworthy rate cannot be calculated. If rate is null, inspect rate_unavailable; if sent_incomplete is true, do not compute your own rate from the returned denominator.

ESP distribution

Repeat the bracketed metrics[] query parameter to request up to eight metrics. It defaults to sent.

curl -G "$BASE/esp-distribution" \
-H "Authorization: Bearer $KEY" \
--data-urlencode 'range=7d' \
--data-urlencode 'metrics[]=sent' \
--data-urlencode 'metrics[]=reply'

Each requested metric is split into microsoft, google, and others. Read availability before assuming every metric is present. When gated is true, coverage is not sufficient to publish a trustworthy composition; coverage provides the measured ratio and threshold.

Domain checks

Domain checks are a two-step resource rather than traffic events:

1. Call GET /checks to obtain the public check catalogue, each day in the 28-day history, aggregate statuses, and current blacklist overview.
2. Choose a check.id and a history[].date returned by that response.
3. Call GET /checks/{check}/results?date=YYYY-MM-DD to retrieve the domain-level verdicts, reasons, observed value, and check time for that cell.

Do not invent check IDs. Blacklist checks can use dynamic IDs such as blacklist:<zone>, and the detail endpoint accepts only an ID and date present in the overview response.

curl -s "$BASE/checks" \
-H "Authorization: Bearer $KEY" > checks.json

CHECK_ID=$(jq -r '.checks[0].id' checks.json)
DATE=$(jq -r '.history[-1].date' checks.json)

curl -G "$BASE/checks/$CHECK_ID/results" \
-H "Authorization: Bearer $KEY" \
--data-urlencode "date=$DATE"

Possible check statuses are healthy, warning, error, and not-tested. Blacklist overview statuses are clear, listed, and unknown.

Errors and retries

Errors use RFC 9457 problem details. Branch on the machine-readable code, retain the correlation_id for support, and retry only when retryable is true. A 429 includes retry guidance; wait before trying again.

The public problem catalogue is available at GET /problems, and the OpenAPI contract at GET /openapi.json.