{ "openapi": "3.1.0", "info": { "title": "Motorical Public API", "version": "1.2.0", "description": "Transactional email HTTP API and analytics for Motorical Sending SMTP — same job class as SendGrid/Postmark-style send APIs. One Motor Block per project: an isolated sending stream with its own domain, auth, keys, SMTP credentials, rates, logs, webhooks, and automation. Public API covers email sending, analytics, logs, configuration, domain health, webhooks, and exports. SMTP submission is an out-of-band protocol on mail.motorical.com:2587 (STARTTLS) or :2465 (implicit TLS) using password, OAuth 2.0 access token as SMTP password (or XOAUTH2), or mTLS + password — see https://docs.motorical.com/smtp-integration/authentication-methods. Do not use OAuth access tokens or Bearer tokens on POST /v1/send (Motor Block ApiKey mk_live_ only)." }, "servers": [ { "url": "https://api.motorical.com", "description": "Motorical production API" }, { "url": "https://motorical.com", "description": "Dashboard host — OAuth AS endpoints" } ], "tags": [ { "name": "Motor Blocks", "description": "Isolated sending streams (Motor Blocks) — domains, keys, SMTP, rates, logs" }, { "name": "Send", "description": "Transactional email via HTTP API (POST /v1/send)" }, { "name": "OAuth", "description": "Motorical OAuth 2.0 authorization server (SMTP access tokens)" }, { "name": "Analytics", "description": "Metrics, deliverability, reputation, anomalies" }, { "name": "Logs", "description": "Log search and message lookups" }, { "name": "Config", "description": "Configuration & domain health" }, { "name": "Webhooks", "description": "Webhook endpoints and delivery monitoring" }, { "name": "Exports", "description": "Export jobs and previews" }, { "name": "Communications", "description": "Communications Block lists, templates, campaigns, suppressions, and analytics" } ], "paths": { "/api/oauth2/authorize": { "get": { "tags": [ "OAuth" ], "servers": [ { "url": "https://motorical.com" } ], "summary": "OAuth 2.0 authorization endpoint (consent HTML)", "description": "Starts the authorization-code flow for a Motor Block OAuth app. Returns an HTML consent page. After approve, redirects to redirect_uri with ?code=. Use the access token from /api/oauth2/token as the SMTP password on mail.motorical.com — not on POST /v1/send.", "parameters": [ { "name": "client_id", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "response_type", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "code" ] } }, { "name": "redirect_uri", "in": "query", "required": true, "schema": { "type": "string", "format": "uri" } }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string", "example": "email.send" } }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Consent HTML" }, "400": { "description": "invalid_request / invalid_client / invalid_scope" } } } }, "/api/oauth2/token": { "post": { "tags": [ "OAuth" ], "servers": [ { "url": "https://motorical.com" } ], "summary": "OAuth 2.0 token endpoint", "description": "Exchange an authorization code or refresh token for an access token. The access_token JWT is used as the SMTP password (PLAIN/LOGIN) or via XOAUTH2 on mail.motorical.com:2587.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "grant_type", "client_id", "client_secret" ], "properties": { "grant_type": { "type": "string", "enum": [ "authorization_code", "refresh_token" ] }, "code": { "type": "string", "description": "Required for authorization_code" }, "refresh_token": { "type": "string", "description": "Required for refresh_token" }, "client_id": { "type": "string" }, "client_secret": { "type": "string" }, "redirect_uri": { "type": "string", "format": "uri", "description": "Required for authorization_code; must match registration" } } } } } }, "responses": { "200": { "description": "Token response", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string" }, "token_type": { "type": "string", "example": "Bearer" }, "expires_in": { "type": "integer", "example": 3600 }, "refresh_token": { "type": "string" }, "scope": { "type": "string" }, "motor_block": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "smtp_username": { "type": "string" } } } } } } } }, "400": { "description": "invalid_grant / invalid_client" } } } }, "/api/oauth2/validate": { "get": { "tags": [ "OAuth" ], "servers": [ { "url": "https://motorical.com" } ], "summary": "Validate an OAuth access token", "description": "Optional helper to introspect a Motorical-issued SMTP access token (query or Authorization Bearer).", "parameters": [ { "name": "token", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "access_token", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Bearer " } ], "responses": { "200": { "description": "Token metadata when valid" }, "401": { "description": "Invalid or expired token" } } } }, "/api/public/token/account-key": { "post": { "tags": [ "Motor Blocks" ], "summary": "Mint a Public Analytics API token with an Account API Key", "description": "Use an Account API Key (`ak_live_...`) to create a short-lived bearer token for `/api/public/v1` endpoints. The key can be supplied as `Authorization: ApiKey ak_live_...` or `X-Api-Key: ak_live_...`.", "security": [ { "accountApiKeyAuth": [] }, { "xApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "motorBlockId" ], "properties": { "motorBlockId": { "type": "string", "format": "uuid" }, "scopes": { "type": "array", "items": { "type": "string" } }, "ttlSeconds": { "type": "integer", "minimum": 60, "maximum": 900, "default": 300 } } } } } }, "responses": { "200": { "description": "Token minted" }, "401": { "description": "Account API key missing or invalid" }, "422": { "description": "Validation error" } } } }, "/api/public/token": { "post": { "tags": [ "Motor Blocks" ], "summary": "Mint a Public Analytics API token with a dashboard JWT", "description": "Dashboard and trusted-session flow for creating a short-lived bearer token for `/api/public/v1` endpoints. Server-to-server integrations should prefer `/api/public/token/account-key`.", "security": [ { "dashboardBearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "motorBlockId" ], "properties": { "motorBlockId": { "type": "string", "format": "uuid" }, "scopes": { "type": "array", "items": { "type": "string" } }, "ttlSeconds": { "type": "integer", "minimum": 60, "maximum": 900, "default": 300 } } } } } }, "responses": { "200": { "description": "Token minted" }, "401": { "description": "Dashboard JWT missing or invalid" }, "422": { "description": "Validation error" } } } }, "/api/public/v1/motor-blocks": { "get": { "tags": [ "Motor Blocks" ], "summary": "List motor blocks bound to the token", "description": "Returns the Motor Block(s) associated with the current public API token.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotorBlocksListResponse" } } } } } } }, "/api/public/v1/motor-blocks/{id}/overview": { "get": { "tags": [ "Analytics" ], "summary": "Motor Block overview", "description": "One-call overview including totals, rates, reputation, rate limits, anomalies, and top domains.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OverviewResponse" } } } } } } }, "/api/public/v1/motor-blocks/{id}/daily-summary": { "get": { "tags": [ "Analytics" ], "summary": "Daily summary", "description": "Daily rollups for a recent window (sent, delivered, bounced, complained, plus rates).", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "days", "in": "query", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "OK" } } } }, "/api/public/v1/motor-blocks/{id}/rate-limits": { "get": { "tags": [ "Analytics" ], "summary": "Motor Block rate limits", "description": "Current usage vs burst, hourly, and daily rate limits.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitsResponse" } } } } } } }, "/api/public/v1/motor-blocks/{id}/metrics": { "get": { "tags": [ "Analytics" ], "summary": "Metrics series and totals", "description": "Aggregated metrics (sent, delivered, bounced, complained) over hour/day buckets.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "interval", "in": "query", "schema": { "type": "string", "enum": [ "hour", "day" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricsResponse" } } } } } } }, "/api/public/v1/motor-blocks/{id}/deliverability": { "get": { "tags": [ "Analytics" ], "summary": "Deliverability by recipient domain", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "OK" } } } }, "/api/public/v1/motor-blocks/{id}/reputation": { "get": { "tags": [ "Analytics" ], "summary": "Reputation score", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/public/v1/motor-blocks/{id}/anomalies": { "get": { "tags": [ "Analytics" ], "summary": "Anomaly detection (bounce spikes)", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/public/v1/motor-blocks/{id}/providers": { "get": { "tags": [ "Analytics" ], "summary": "Provider breakdown (gmail, outlook, yahoo, other)", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "OK" } } } }, "/api/public/v1/motor-blocks/{id}/error-codes": { "get": { "tags": [ "Analytics" ], "summary": "SMTP error code diagnostics", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "OK" } } } }, "/api/public/v1/motor-blocks/{id}/logs": { "get": { "tags": [ "Logs" ], "summary": "Search logs with cursor pagination", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "currentOutcome", "in": "query", "schema": { "type": "string", "enum": [ "queued", "processed", "deferred", "delivered", "bounced", "failed", "complained" ] } }, { "name": "query", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "includePII", "in": "query", "schema": { "type": "boolean" }, "description": "Requires logs.pii scope" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogsResponse" } } } }, "400": { "description": "Bad Request" }, "403": { "description": "Forbidden" } } } }, "/api/public/v1/messages/{id}": { "get": { "tags": [ "Logs" ], "summary": "Get message by send id (UUID)", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "includePII", "in": "query", "schema": { "type": "boolean" }, "description": "Requires logs.pii scope" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/public/v1/messages": { "get": { "tags": [ "Logs" ], "summary": "Lookup message by RFC Message-ID header", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "smtpMessageId", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "includePII", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/public/v1/messages/{id}/events": { "get": { "tags": [ "Logs" ], "summary": "Get message event timeline", "description": "Canonical lifecycle events from email_events.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "includePII", "in": "query", "schema": { "type": "boolean" }, "description": "Requires logs.pii scope" } ], "responses": { "200": { "description": "OK" } } } }, "/api/public/v1/motor-blocks/{id}/config": { "get": { "tags": [ "Config" ], "summary": "Motor Block config snapshot", "description": "Read-only, non-sensitive configuration snapshot and domain status.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/public/v1/motor-blocks/{id}/domain-health": { "get": { "tags": [ "Config" ], "summary": "Domain health (SPF/DKIM/DMARC)", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/public/v1/motor-blocks/{id}/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "List webhooks", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } }, "post": { "tags": [ "Webhooks" ], "summary": "Create webhook", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } } }, "required": [ "url" ] } } } }, "responses": { "201": { "description": "Created" } } } }, "/api/public/v1/motor-blocks/{id}/webhooks/{webhookId}": { "put": { "tags": [ "Webhooks" ], "summary": "Update webhook", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } }, "delete": { "tags": [ "Webhooks" ], "summary": "Delete webhook", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/public/v1/motor-blocks/{id}/webhooks/{webhookId}/test": { "post": { "tags": [ "Webhooks" ], "summary": "Enqueue a test webhook delivery", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Accepted" } } } }, "/api/public/v1/motor-blocks/{id}/webhooks/{webhookId}/deliveries": { "get": { "tags": [ "Webhooks" ], "summary": "Webhook delivery history", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "OK" } } } }, "/api/public/v1/motor-blocks/{id}/webhooks/{webhookId}/stats": { "get": { "tags": [ "Webhooks" ], "summary": "Webhook delivery stats", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "hours", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 168 } } ], "responses": { "200": { "description": "OK" } } } }, "/api/public/v1/motor-blocks/{id}/events/stream": { "get": { "tags": [ "Analytics" ], "summary": "Event stream (SSE)", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/public/v1/motor-blocks/{id}/exports": { "post": { "tags": [ "Exports" ], "summary": "Create export job", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "jobType": { "type": "string", "enum": [ "logs", "metrics" ] }, "params": { "type": "object" } } } } } }, "responses": { "202": { "description": "Accepted" } } }, "get": { "tags": [ "Exports" ], "summary": "List recent export jobs", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/public/v1/motor-blocks/{id}/exports/preview": { "get": { "tags": [ "Exports" ], "summary": "Preview recent logs (no job creation)", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "includePII", "in": "query", "schema": { "type": "boolean" }, "description": "Requires logs.pii scope" } ], "responses": { "200": { "description": "OK" } } } }, "/api/public/v1/exports/{jobId}": { "get": { "tags": [ "Exports" ], "summary": "Get export job status", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/public/v1/exports/{jobId}/download": { "get": { "tags": [ "Exports" ], "summary": "Download export file (signed token)", "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "token", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/v1/test-email": { "post": { "tags": [ "Send" ], "summary": "Test SMTP setup parameters", "description": "Validate SMTP setup parameters for customer setup flows. Authenticated with a Motor Block API key supplied as `Authorization: ApiKey mk_live_...` or `X-Api-Key: mk_live_...`.", "security": [ { "apiKeyAuth": [] }, { "xApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "method", "host", "port", "username", "to", "subject" ], "properties": { "method": { "type": "string", "enum": [ "basic_auth", "starttls", "api_key", "oauth2", "mtls" ] }, "host": { "type": "string" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535 }, "username": { "type": "string" }, "password": { "type": "string" }, "to": { "type": "string", "format": "email" }, "subject": { "type": "string" }, "requireTLS": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "SMTP test accepted" }, "401": { "description": "Motor Block API key missing or invalid" }, "422": { "description": "Validation error" } } } }, "/v1/send": { "post": { "tags": [ "Send" ], "summary": "Send or validate an email", "description": "Queue an email for immediate delivery, or validate the payload only when `dryRun: true`. Authenticated via Motor Block API key (`Authorization: ApiKey mk_live_...` or `X-Api-Key: mk_live_...`).\n\n**Dry run:** `dryRun: true` performs the same authentication, domain, DNS, recipient, subject, and body-size checks but does not insert an email log or push delivery work to Redis.\n\n**Idempotency:** Include an `Idempotency-Key` header to prevent duplicate sends on retries (24h window).\n\n**Webhook verification:** Delivery events are posted to your webhook endpoints with an `X-Motorical-Signature` header containing an HMAC-SHA256 hex digest computed over the JSON body using the webhook secret you received at creation time. Verify with: `crypto.createHmac(\"sha256\", secret).update(body).digest(\"hex\")`.", "security": [ { "apiKeyAuth": [] }, { "xApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "from", "to", "subject" ], "properties": { "from": { "type": "string", "format": "email", "description": "Sender address (must match motor block domain)" }, "to": { "oneOf": [ { "type": "string", "format": "email" }, { "type": "array", "items": { "type": "string", "format": "email" }, "maxItems": 50 } ] }, "subject": { "type": "string", "maxLength": 998 }, "text": { "type": "string", "description": "Plain text body" }, "html": { "type": "string", "description": "HTML body" }, "headers": { "type": "object", "description": "Custom headers applied to the outgoing message and DKIM-signed (e.g. In-Reply-To, References, Reply-To, List-Unsubscribe, custom X-*). Reserved/spoofable headers are rejected with 400 DISALLOWED_HEADERS: From, Sender, Return-Path, To, Cc, Bcc, Subject, Date, Message-ID, MIME-Version, Content-*, DKIM-Signature, Received, Authentication-Results, ARC-*, X-Motorical-*. Header values containing CR/LF are also rejected.", "additionalProperties": { "type": "string" } }, "dryRun": { "type": "boolean", "default": false, "description": "Validate without queueing or writing email logs" } } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Unique key to prevent duplicate sends (24h window)" } ], "responses": { "200": { "description": "Email queued, or payload validated when dryRun=true", "content": { "application/json": { "schema": { "type": "object", "properties": { "dryRun": { "type": "boolean" }, "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "acceptanceStatus": { "type": "string", "enum": [ "queued", "validated" ] }, "from": { "type": "string" }, "to": { "type": "array", "items": { "type": "string" } }, "subject": { "type": "string" }, "domain": { "type": "string" }, "bodySize": { "type": "integer" }, "recipientCount": { "type": "integer" }, "timestamp": { "type": "string", "format": "date-time" } } }, "message": { "type": "string" } } } } } }, "400": { "description": "Disallowed custom header(s) (code DISALLOWED_HEADERS) or invalid from address" }, "403": { "description": "Domain mismatch or unverified" }, "422": { "description": "Validation error" }, "429": { "description": "Rate limit exceeded" } } } }, "/v1/status": { "get": { "tags": [ "Send" ], "summary": "Get HTTP Send API service status", "responses": { "200": { "description": "Service status" } } } }, "/comm-api/api/health": { "get": { "tags": [ "Communications" ], "summary": "Communications API health", "description": "Communications Block endpoint.", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } } } }, "/comm-api/api/lists": { "get": { "tags": [ "Communications" ], "summary": "List contact lists", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "security": [ { "tenantHeaderAuth": [] } ] }, "post": { "tags": [ "Communications" ], "summary": "Create a contact list", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "security": [ { "tenantHeaderAuth": [] } ] }, "delete": { "tags": [ "Communications" ], "summary": "Bulk delete contact lists", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/lists/from-filter": { "post": { "tags": [ "Communications" ], "summary": "Create a smart list from filters", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/lists/{id}": { "delete": { "tags": [ "Communications" ], "summary": "Delete a contact list", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/lists/{id}/contacts": { "get": { "tags": [ "Communications" ], "summary": "List contacts in a list", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "security": [ { "tenantHeaderAuth": [] } ] }, "post": { "tags": [ "Communications" ], "summary": "Add contacts to a list", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/lists/{id}/contacts/import": { "post": { "tags": [ "Communications" ], "summary": "Import list contacts from CSV", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/lists/{id}/contacts/export": { "get": { "tags": [ "Communications" ], "summary": "Export list contacts", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/contacts/upsert": { "post": { "tags": [ "Communications" ], "summary": "Create or update a contact", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/contacts/{id}": { "delete": { "tags": [ "Communications" ], "summary": "Delete a contact", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/contacts/{id}/unsubscribe": { "post": { "tags": [ "Communications" ], "summary": "Unsubscribe a contact", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/contacts/{id}/resubscribe": { "put": { "tags": [ "Communications" ], "summary": "Resubscribe a contact", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/templates": { "get": { "tags": [ "Communications" ], "summary": "List templates", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "security": [ { "tenantHeaderAuth": [] } ] }, "post": { "tags": [ "Communications" ], "summary": "Create a template", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "security": [ { "tenantHeaderAuth": [] } ] }, "delete": { "tags": [ "Communications" ], "summary": "Bulk delete templates", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/templates/validate": { "post": { "tags": [ "Communications" ], "summary": "Validate a template without saving", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/templates/{id}": { "get": { "tags": [ "Communications" ], "summary": "Get a template", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "security": [ { "tenantHeaderAuth": [] } ] }, "patch": { "tags": [ "Communications" ], "summary": "Update a template", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "security": [ { "tenantHeaderAuth": [] } ] }, "delete": { "tags": [ "Communications" ], "summary": "Delete a template", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/campaigns": { "get": { "tags": [ "Communications" ], "summary": "List campaigns", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "security": [ { "tenantHeaderAuth": [] } ] }, "post": { "tags": [ "Communications" ], "summary": "Create a campaign", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/campaigns/{id}": { "get": { "tags": [ "Communications" ], "summary": "Get campaign details", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "security": [ { "tenantHeaderAuth": [] } ] }, "delete": { "tags": [ "Communications" ], "summary": "Delete a campaign", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/campaigns/{id}/settings": { "patch": { "tags": [ "Communications" ], "summary": "Update campaign settings", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/campaigns/{id}/schedule": { "post": { "tags": [ "Communications" ], "summary": "Schedule a campaign", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/campaigns/{id}/cancel": { "post": { "tags": [ "Communications" ], "summary": "Cancel a campaign", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/campaigns/deleted": { "get": { "tags": [ "Communications" ], "summary": "List deleted campaigns", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/campaigns/{id}/restore": { "patch": { "tags": [ "Communications" ], "summary": "Restore a campaign", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/campaigns/{id}/permanent": { "delete": { "tags": [ "Communications" ], "summary": "Permanently delete a campaign", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/campaigns/cleanup": { "delete": { "tags": [ "Communications" ], "summary": "Cleanup deleted campaigns", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/campaigns/{id}/compile": { "post": { "tags": [ "Communications" ], "summary": "Compile campaign content and audience", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/campaigns/{id}/events": { "get": { "tags": [ "Communications" ], "summary": "List campaign events", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/campaigns/{id}/stats": { "get": { "tags": [ "Communications" ], "summary": "Get campaign stats", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/campaigns/{id}/analytics": { "get": { "tags": [ "Communications" ], "summary": "Get campaign analytics", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/campaigns/{id}/click-breakdown": { "get": { "tags": [ "Communications" ], "summary": "Get click breakdown", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/campaigns/{id}/recipients": { "get": { "tags": [ "Communications" ], "summary": "List campaign recipients", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/campaigns/{id}/clicks": { "get": { "tags": [ "Communications" ], "summary": "List campaign clicks", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/recipients": { "get": { "tags": [ "Communications" ], "summary": "Search recipients", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/recipients/campaigns": { "get": { "tags": [ "Communications" ], "summary": "List recipient campaign groupings", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/recipients/filter": { "post": { "tags": [ "Communications" ], "summary": "Filter recipients", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/recipients/export": { "post": { "tags": [ "Communications" ], "summary": "Export recipients", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/recipients/bulk-delete": { "post": { "tags": [ "Communications" ], "summary": "Bulk delete recipients", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/recipients/bulk-move": { "post": { "tags": [ "Communications" ], "summary": "Bulk move recipients", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/recipients/restore": { "post": { "tags": [ "Communications" ], "summary": "Restore recipients", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/recipients/deleted": { "get": { "tags": [ "Communications" ], "summary": "List deleted recipients", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/recipients/{id}/restore": { "patch": { "tags": [ "Communications" ], "summary": "Restore a recipient", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/recipients/{id}/permanent": { "delete": { "tags": [ "Communications" ], "summary": "Permanently delete a recipient", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/recipients/cleanup": { "delete": { "tags": [ "Communications" ], "summary": "Cleanup deleted recipients", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/suppressions": { "get": { "tags": [ "Communications" ], "summary": "List suppressions", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "security": [ { "tenantHeaderAuth": [] } ] }, "post": { "tags": [ "Communications" ], "summary": "Add a suppression", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/suppressions/{id}": { "delete": { "tags": [ "Communications" ], "summary": "Remove a suppression", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/suppressions/bulk": { "post": { "tags": [ "Communications" ], "summary": "Bulk import suppressions", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/suppressions/stats": { "get": { "tags": [ "Communications" ], "summary": "Get suppression stats", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/suppressions/import-bounces": { "post": { "tags": [ "Communications" ], "summary": "Import bounces into suppressions", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/tracking/events": { "get": { "tags": [ "Communications" ], "summary": "Search tracking events", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/tracking/export": { "get": { "tags": [ "Communications" ], "summary": "Export tracking events", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/tracking/stats": { "get": { "tags": [ "Communications" ], "summary": "Get tracking stats", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/unsubscribe-events": { "get": { "tags": [ "Communications" ], "summary": "List unsubscribe events", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/unsubscribe-analytics": { "get": { "tags": [ "Communications" ], "summary": "Get unsubscribe analytics", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/unsubscribe-trends": { "get": { "tags": [ "Communications" ], "summary": "Get unsubscribe trends", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/analytics/overview": { "get": { "tags": [ "Communications" ], "summary": "Get Communications analytics overview", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "security": [ { "tenantHeaderAuth": [] } ] } }, "/comm-api/api/gdpr/export": { "get": { "tags": [ "Communications" ], "summary": "Export GDPR data", "description": "Communications Block endpoint. Requires `X-Tenant-Id` for tenant scoping.", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" } } } } } }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant entitlement required" }, "404": { "description": "Not found" } }, "security": [ { "tenantHeaderAuth": [] } ] } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Short-lived Public Analytics API token used for /api/public/v1 endpoints." }, "dashboardBearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Dashboard session JWT used only to mint Public Analytics API tokens." }, "accountApiKeyAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Account API key for token minting. Format: ApiKey ak_live_..." }, "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Motor Block API key. Format: ApiKey mk_live_..." }, "xApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-Api-Key", "description": "Alternative API key header. Use ak_live_... for token minting or mk_live_... for /v1/send." }, "tenantHeaderAuth": { "type": "apiKey", "in": "header", "name": "X-Tenant-Id", "description": "Communications Block tenant identifier used to scope lists, templates, campaigns, suppressions, and analytics." } }, "schemas": { "MotorBlocksListResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } } } }, "RateLimitsResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "burst": { "$ref": "#/components/schemas/LimitBucket" }, "hourly": { "$ref": "#/components/schemas/LimitBucket" }, "daily": { "$ref": "#/components/schemas/LimitBucket" } } } } }, "LimitBucket": { "type": "object", "properties": { "used": { "type": "integer" }, "limit": { "type": "integer" }, "remaining": { "type": "integer" }, "resetIn": { "type": "integer" } } }, "LogsResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/LogItem" } }, "nextCursor": { "type": "string", "nullable": true } } } } }, "MessageSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "smtpMessageId": { "type": "string", "nullable": true }, "recipient": { "type": "string" }, "currentOutcome": { "type": "string", "enum": [ "queued", "processed", "deferred", "delivered", "bounced", "failed", "complained" ] }, "smtpCode": { "type": "string", "nullable": true }, "queuedAt": { "type": "string", "format": "date-time" } } }, "MessageResource": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "smtpMessageId": { "type": "string", "nullable": true }, "currentOutcome": { "type": "string" }, "isTerminal": { "type": "boolean" }, "from": { "type": "string" }, "recipient": { "type": "string" }, "subject": { "type": "string" }, "queuedAt": { "type": "string", "format": "date-time" }, "processedAt": { "type": "string", "format": "date-time", "nullable": true }, "deliveredAt": { "type": "string", "format": "date-time", "nullable": true }, "bouncedAt": { "type": "string", "format": "date-time", "nullable": true }, "smtpCode": { "type": "string", "nullable": true }, "smtpResponse": { "type": "string", "nullable": true } } }, "WebhookEvent": { "type": "object", "properties": { "event": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "smtpMessageId": { "type": "string", "nullable": true }, "motorBlockId": { "type": "string", "format": "uuid" }, "from": { "type": "string" }, "recipient": { "type": "string" }, "recipients": { "type": "array", "items": { "type": "string" } }, "subject": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "currentOutcome": { "type": "string" }, "isTerminal": { "type": "boolean" }, "smtpCode": { "type": "string", "nullable": true }, "smtpResponse": { "type": "string", "nullable": true } } }, "LogItem": { "$ref": "#/components/schemas/MessageSummary" }, "MetricsResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "series": { "type": "array", "items": { "$ref": "#/components/schemas/MetricsPoint" } }, "totals": { "$ref": "#/components/schemas/MetricsTotals" } } } } }, "MetricsPoint": { "type": "object", "properties": { "t": { "type": "string", "format": "date-time" }, "total": { "type": "integer" }, "processed": { "type": "integer" }, "delivered": { "type": "integer" }, "bounced": { "type": "integer" }, "deferred": { "type": "integer" }, "failed": { "type": "integer" }, "complained": { "type": "integer" } } }, "MetricsTotals": { "type": "object", "properties": { "total": { "type": "integer" }, "processed": { "type": "integer" }, "delivered": { "type": "integer" }, "bounced": { "type": "integer" }, "deferred": { "type": "integer" }, "failed": { "type": "integer" }, "complained": { "type": "integer" } } }, "OverviewResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "timeWindow": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } } }, "totals": { "type": "object", "properties": { "sent": { "type": "integer" }, "delivered": { "type": "integer" }, "bounced": { "type": "integer" }, "complained": { "type": "integer" } } }, "rates": { "type": "object", "properties": { "deliveryRate": { "type": "number" }, "bounceRate": { "type": "number" }, "complaintRate": { "type": "number" } } } } } } }, "MessageResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/MessageResource" } } } } } }