{ "openapi": "3.1.0", "info": { "title": "builders.ac Deliverability API", "version": "v1alpha1", "description": "Read-only deliverability analytics for a builders.ac account. Authenticate with an active Provisioning Core API credential; this alpha may change before a stable release." }, "servers": [ { "url": "https://api.builders.ac/api/deliverability/v1alpha1" } ], "tags": [ { "name": "Meta" }, { "name": "Traffic" }, { "name": "Bounces" }, { "name": "ESP" }, { "name": "Domain checks" } ], "paths": { "/": { "get": { "tags": [ "Meta" ], "operationId": "deliverabilityApiIndex", "summary": "Describe this API version", "responses": { "200": { "description": "API metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiIndex" } } } } } } }, "/openapi.json": { "get": { "tags": [ "Meta" ], "operationId": "getDeliverabilityOpenApi", "summary": "Retrieve this OpenAPI document", "responses": { "200": { "description": "OpenAPI contract", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/problems": { "get": { "tags": [ "Meta" ], "operationId": "listDeliverabilityProblems", "summary": "List problem types", "responses": { "200": { "description": "Problem catalogue", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemList" } } } } } } }, "/problems/{code}": { "get": { "tags": [ "Meta" ], "operationId": "getDeliverabilityProblem", "summary": "Retrieve one problem type", "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9_]+$" } } ], "responses": { "200": { "description": "Problem type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemCatalogueEntry" } } } }, "404": { "$ref": "#/components/responses/Problem" } } } }, "/summary": { "get": { "tags": [ "Traffic" ], "operationId": "getDeliverabilitySummary", "summary": "Retrieve traffic totals and a per-domain summary", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Range" }, { "$ref": "#/components/parameters/SenderId" }, { "$ref": "#/components/parameters/DomainId" } ], "responses": { "200": { "description": "Traffic summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Summary" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } } } }, "/timeseries": { "get": { "tags": [ "Traffic" ], "operationId": "getDeliverabilityTimeseries", "summary": "Retrieve the traffic time series", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Range" }, { "$ref": "#/components/parameters/SenderId" }, { "$ref": "#/components/parameters/DomainId" } ], "responses": { "200": { "description": "Traffic time series", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Timeseries" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } } } }, "/bounces": { "get": { "tags": [ "Bounces" ], "operationId": "getDeliverabilityBounces", "summary": "Retrieve bounce totals, trends, and per-domain rates", "description": "This aggregate resource intentionally omits mailbox-level event payloads; individual events belong to the Mailbox Events API.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Range" }, { "$ref": "#/components/parameters/SenderId" }, { "$ref": "#/components/parameters/DomainId" } ], "responses": { "200": { "description": "Bounce analytics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bounces" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } } } }, "/esp-distribution": { "get": { "tags": [ "ESP" ], "operationId": "getDeliverabilityEspDistribution", "summary": "Retrieve message volumes grouped by mailbox provider", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Range" }, { "$ref": "#/components/parameters/SenderId" }, { "$ref": "#/components/parameters/DomainId" }, { "name": "metrics[]", "in": "query", "description": "One or more metrics. Repeat this bracketed parameter for multiple values. Defaults to sent.", "schema": { "type": "array", "minItems": 1, "maxItems": 8, "items": { "$ref": "#/components/schemas/MetricName" }, "default": [ "sent" ] }, "style": "form", "explode": true } ], "responses": { "200": { "description": "ESP distribution", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EspDistribution" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } } } }, "/checks": { "get": { "tags": [ "Domain checks" ], "operationId": "getDeliverabilityChecks", "summary": "Retrieve the 28-day domain-check grid and blacklist overview", "description": "The check rows are data-driven. Use each returned check id when requesting detail; do not maintain a client-side list. This public resource is always masked and rejects the staff-only debug query parameter. Non-healthy, non-blacklist cells are reported as not-tested; blacklist warnings and errors remain visible.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/SenderId" }, { "$ref": "#/components/parameters/DomainId" } ], "responses": { "200": { "description": "Domain-check overview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Checks" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } } } }, "/checks/{check}/results": { "get": { "tags": [ "Domain checks" ], "operationId": "getDeliverabilityCheckResults", "summary": "Retrieve per-domain results for one check and date", "description": "Public masking also applies to details and the staff-only debug query parameter is rejected. A non-healthy, non-blacklist cell has an empty domains list even when internal diagnostic findings exist. Blacklist warning and error details remain visible.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "check", "in": "path", "required": true, "description": "An id returned by GET /checks, including dynamic blacklist: ids.", "schema": { "type": "string", "pattern": "^[a-z0-9:._-]+$" } }, { "name": "date", "in": "query", "required": true, "description": "A date returned in GET /checks history.", "schema": { "type": "string", "format": "date" } }, { "$ref": "#/components/parameters/SenderId" }, { "$ref": "#/components/parameters/DomainId" } ], "responses": { "200": { "description": "Domain-level check results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckResults" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "age1…", "description": "The shared builders.ac API Key (`age1...`). Send the API Key as the Bearer token; the matching API Secret never crosses the wire." } }, "parameters": { "Range": { "name": "range", "in": "query", "description": "Time window. Defaults to 7d.", "schema": { "$ref": "#/components/schemas/Range" } }, "SenderId": { "name": "sender_id", "in": "query", "description": "Restrict data to one sender owned by the authenticated account.", "schema": { "$ref": "#/components/schemas/SenderId" } }, "DomainId": { "name": "domain_id", "in": "query", "description": "Restrict data to one domain owned by the authenticated account.", "schema": { "$ref": "#/components/schemas/DomainId" } } }, "responses": { "Problem": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "schemas": { "ApiIndex": { "type": "object", "additionalProperties": false, "required": [ "service", "version", "status" ], "properties": { "service": { "const": "deliverability-api" }, "version": { "const": "v1alpha1" }, "status": { "const": "alpha" } } }, "Range": { "type": "string", "enum": [ "1h", "8h", "24h", "3d", "7d", "14d" ], "default": "7d" }, "SenderId": { "type": "string", "pattern": "^snd_[0-9a-z]{26}$" }, "DomainId": { "type": "string", "pattern": "^dom_[0-9a-z]{26}$" }, "MetricName": { "type": "string", "enum": [ "sent", "received", "outreach", "warmup", "reply", "autoresponse", "other", "system" ] }, "MetricValues": { "type": "object", "additionalProperties": false, "properties": { "sent": { "type": [ "integer", "null" ], "minimum": 0 }, "received": { "type": [ "integer", "null" ], "minimum": 0 }, "outreach": { "type": [ "integer", "null" ], "minimum": 0 }, "warmup": { "type": [ "integer", "null" ], "minimum": 0 }, "reply": { "type": [ "integer", "null" ], "minimum": 0 }, "autoresponse": { "type": [ "integer", "null" ], "minimum": 0 }, "other": { "type": [ "integer", "null" ], "minimum": 0 }, "system": { "type": [ "integer", "null" ], "minimum": 0 } } }, "TrafficMeta": { "type": "object", "additionalProperties": false, "properties": { "range": { "$ref": "#/components/schemas/Range" }, "granularity": { "type": "string", "enum": [ "hour", "day" ] }, "classification_since": { "type": "string", "format": "date-time" }, "computed_at": { "type": "string", "format": "date-time" }, "tenants": { "type": [ "array", "object", "null" ] } } }, "Summary": { "type": "object", "additionalProperties": false, "required": [ "totals", "domains", "meta" ], "properties": { "totals": { "$ref": "#/components/schemas/MetricValues" }, "domains": { "type": "array", "items": { "$ref": "#/components/schemas/DomainSummary" } }, "meta": { "$ref": "#/components/schemas/TrafficMeta" } } }, "DomainSummary": { "type": "object", "additionalProperties": false, "required": [ "domain_id", "name", "sender_id", "sent", "received", "outreach", "warmup", "replies", "autoresponses", "classification_thin", "mailbox_count", "sent_percent", "outreach_percent", "warmup_percent" ], "properties": { "domain_id": { "$ref": "#/components/schemas/DomainId" }, "name": { "type": "string" }, "sender_id": { "oneOf": [ { "$ref": "#/components/schemas/SenderId" }, { "type": "null" } ] }, "sent": { "type": "integer", "minimum": 0 }, "received": { "type": "integer", "minimum": 0 }, "outreach": { "type": [ "integer", "null" ], "minimum": 0 }, "warmup": { "type": [ "integer", "null" ], "minimum": 0 }, "replies": { "type": [ "integer", "null" ], "minimum": 0 }, "autoresponses": { "type": [ "integer", "null" ], "minimum": 0 }, "classification_thin": { "type": "boolean" }, "mailbox_count": { "type": "integer", "minimum": 0 }, "sent_percent": { "type": [ "number", "null" ] }, "outreach_percent": { "type": [ "number", "null" ] }, "warmup_percent": { "type": [ "number", "null" ] } } }, "Timeseries": { "type": "object", "additionalProperties": false, "required": [ "trend", "meta" ], "properties": { "trend": { "type": "array", "items": { "$ref": "#/components/schemas/TrendPoint" } }, "meta": { "$ref": "#/components/schemas/TrafficMeta" } } }, "TrendPoint": { "type": "object", "additionalProperties": false, "required": [ "day" ], "properties": { "day": { "type": "string" }, "date": { "type": "string", "format": "date" }, "state": { "type": "string" }, "sent": { "type": [ "integer", "null" ], "minimum": 0 }, "received": { "type": [ "integer", "null" ], "minimum": 0 }, "outreach": { "type": [ "integer", "null" ], "minimum": 0 }, "warmup": { "type": [ "integer", "null" ], "minimum": 0 }, "reply": { "type": [ "integer", "null" ], "minimum": 0 }, "autoresponse": { "type": [ "integer", "null" ], "minimum": 0 }, "other": { "type": [ "integer", "null" ], "minimum": 0 }, "system": { "type": [ "integer", "null" ], "minimum": 0 } } }, "EspBuckets": { "type": "object", "additionalProperties": false, "required": [ "microsoft", "google", "others" ], "properties": { "microsoft": { "type": "integer", "minimum": 0 }, "google": { "type": "integer", "minimum": 0 }, "others": { "type": "integer", "minimum": 0 } } }, "Bounces": { "type": "object", "additionalProperties": false, "required": [ "totals", "by_esp", "trend", "by_domain" ], "properties": { "totals": { "$ref": "#/components/schemas/BounceTotals" }, "by_esp": { "$ref": "#/components/schemas/EspBuckets" }, "trend": { "type": "array", "items": { "$ref": "#/components/schemas/BounceTrendPoint" } }, "by_domain": { "type": "array", "items": { "$ref": "#/components/schemas/DomainBounce" } } } }, "BounceTotals": { "type": "object", "additionalProperties": false, "required": [ "hard", "soft", "pending", "sent", "rate_unavailable" ], "properties": { "hard": { "type": "integer", "minimum": 0 }, "soft": { "type": "integer", "minimum": 0 }, "pending": { "type": "integer", "minimum": 0 }, "sent": { "type": "integer", "minimum": 0 }, "rate_unavailable": { "type": [ "string", "null" ] } } }, "BounceTrendPoint": { "type": "object", "additionalProperties": false, "required": [ "day", "microsoft", "google", "others" ], "properties": { "day": { "type": "string" }, "date": { "type": "string", "format": "date" }, "microsoft": { "type": "integer", "minimum": 0 }, "google": { "type": "integer", "minimum": 0 }, "others": { "type": "integer", "minimum": 0 } } }, "DomainBounce": { "type": "object", "additionalProperties": false, "required": [ "domain_id", "name", "sent", "bounces", "hard_bounces", "soft_bounces", "pending_bounces", "sent_incomplete", "rate_unavailable", "rate" ], "properties": { "domain_id": { "$ref": "#/components/schemas/DomainId" }, "name": { "type": "string" }, "sent": { "type": "integer", "minimum": 0 }, "bounces": { "type": "integer", "minimum": 0 }, "hard_bounces": { "type": "integer", "minimum": 0 }, "soft_bounces": { "type": "integer", "minimum": 0 }, "pending_bounces": { "type": "integer", "minimum": 0 }, "sent_incomplete": { "type": "boolean" }, "rate_unavailable": { "type": [ "string", "null" ] }, "rate": { "type": [ "number", "null" ], "minimum": 0 } } }, "EspDistribution": { "type": "object", "additionalProperties": false, "required": [ "metrics", "gated", "availability", "coverage", "meta" ], "properties": { "metrics": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/EspBuckets" }, "propertyNames": { "$ref": "#/components/schemas/MetricName" } }, "gated": { "type": "boolean" }, "availability": { "type": "object", "additionalProperties": { "type": "boolean" } }, "coverage": { "type": "object", "additionalProperties": false, "required": [ "ratio", "threshold", "agent", "trace" ], "properties": { "ratio": { "type": [ "number", "null" ] }, "threshold": { "type": [ "number", "null" ] }, "agent": { "type": "integer", "minimum": 0 }, "trace": { "type": "integer", "minimum": 0 } } }, "meta": { "$ref": "#/components/schemas/TrafficMeta" } } }, "Checks": { "type": "object", "additionalProperties": false, "required": [ "checks", "history", "blacklists" ], "properties": { "checks": { "type": "array", "items": { "$ref": "#/components/schemas/Check" } }, "history": { "type": "array", "items": { "$ref": "#/components/schemas/CheckHistoryDay" } }, "blacklists": { "type": "array", "items": { "$ref": "#/components/schemas/BlacklistOverview" } } } }, "Check": { "type": "object", "additionalProperties": false, "required": [ "id", "label", "group" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "group": { "type": "string" }, "kind": { "type": "string" } } }, "CheckStatus": { "type": "string", "enum": [ "healthy", "warning", "error", "not-tested" ] }, "BlacklistStatus": { "type": "string", "enum": [ "clear", "listed", "unknown" ] }, "CheckHistoryDay": { "type": "object", "additionalProperties": false, "required": [ "date", "statuses" ], "properties": { "date": { "type": "string", "format": "date" }, "statuses": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/CheckStatus" } } } }, "BlacklistOverview": { "type": "object", "additionalProperties": false, "required": [ "zone", "name", "kind", "status", "checked", "detail" ], "properties": { "zone": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string" }, "status": { "$ref": "#/components/schemas/BlacklistStatus" }, "checked": { "type": [ "string", "null" ], "format": "date-time" }, "detail": { "type": "string" } } }, "CheckResults": { "type": "object", "additionalProperties": false, "required": [ "check", "date", "summary", "domains" ], "properties": { "check": { "$ref": "#/components/schemas/Check" }, "date": { "type": "string", "format": "date" }, "summary": { "type": "object", "additionalProperties": false, "required": [ "total", "warnings", "errors" ], "properties": { "total": { "type": "integer", "minimum": 0 }, "warnings": { "type": "integer", "minimum": 0 }, "errors": { "type": "integer", "minimum": 0 } } }, "domains": { "type": "array", "items": { "$ref": "#/components/schemas/DomainCheckResult" } } } }, "DomainCheckResult": { "type": "object", "additionalProperties": false, "required": [ "domain_id", "name", "sender_id", "sender_name", "status", "reasons", "value", "checked_at" ], "properties": { "domain_id": { "$ref": "#/components/schemas/DomainId" }, "name": { "type": "string" }, "sender_id": { "oneOf": [ { "$ref": "#/components/schemas/SenderId" }, { "type": "null" } ] }, "sender_name": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/CheckStatus" }, "reasons": { "type": "array", "items": { "type": "string" } }, "value": { "type": [ "string", "null" ] }, "checked_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Problem": { "type": "object", "required": [ "type", "title", "status", "detail", "code", "retryable", "correlation_id" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "detail": { "type": "string" }, "code": { "type": "string" }, "retryable": { "type": "boolean" }, "correlation_id": { "type": "string" }, "retry_after": { "type": "string", "format": "date-time" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "additionalProperties": true }, "ProblemCatalogueEntry": { "type": "object", "additionalProperties": false, "required": [ "type", "code", "title", "status", "detail", "retryable" ], "properties": { "type": { "type": "string", "format": "uri" }, "code": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "detail": { "type": "string" }, "retryable": { "type": "boolean" } } }, "ProblemList": { "type": "object", "additionalProperties": false, "required": [ "object", "data" ], "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProblemCatalogueEntry" } } } } } } }