{ "openapi": "3.1.0", "info": { "title": "Emailer API API", "version": "1.24.1", "summary": "Email delivery, domains, API keys, suppressions, webhooks, and AI tools.", "description": "Emailer API API. Email acceptance is not delivery. Mail requires verified domains and activated dedicated sending infrastructure. Full-access API keys manage resources; sending-only keys may only submit email. Dashboard session writes require a permitted Origin or Referer. AI calls share one monthly allowance; an unconfigured provider returns 503 without consuming it. Unsupported features are not advertised as implemented.", "contact": { "name": "Emailer API", "url": "https://emailerapi.com/docs" }, "license": { "name": "Proprietary" } }, "servers": [ { "url": "https://emailerapi.com", "description": "Emailer API production" } ], "tags": [ { "name": "Emails", "description": "Send transactional email and inspect delivery status." } ], "paths": { "/v1/emails": { "post": { "tags": [ "Emails" ], "operationId": "sendEmail", "summary": "Send a transactional email", "description": "Queues a single transactional message for delivery. The response means the message was accepted and queued, not that it was delivered; delivery outcome arrives via the delivery log or a signed webhook.\n\nQuota is reserved atomically at accept time and counted per recipient: a message with three `to` addresses consumes three of the monthly allowance.\n\nSupply `Idempotency-Key` to make retries safe; a repeated key within 24 hours returns the original result instead of sending again. Changed payloads with the same idempotency key return 409. Live dispatch requires a ready OVH sending pool; 202 alone does not establish readiness. Retained email payload storage is bounded across single sends, batches and broadcasts, including canceled or completed messages while their bodies remain stored. Launch defaults are 64 MiB per account and 256 MiB globally; operators can configure MAIL_STORAGE_TENANT_BYTES and MAIL_STORAGE_GLOBAL_BYTES. Accounting includes a 1 KiB per-message allowance and serialized content/addresses/options/attachments; it is a logical budget, not measured disk usage. New admission is serialized globally and commits with quota and queue rows. Tenant storage exhaustion returns 429 mail_storage_limit_exceeded; global storage exhaustion returns 503. Low/unavailable database filesystem capacity returns 503 without keeping quota or partial rows. A valid retry of an already accepted idempotency key bypasses new storage admission. Delivery and cancellation do not free retained bytes. Existing history is backfilled without deleting content. These are storage limits in addition to daily/monthly recipient quotas; increasing them requires real host capacity. Production self-service mail requires a verified owner email, current domain signing, a verified application integration, and a fresh approved event for the exact template and recipient. Blocked requests reserve no quota or mail storage. Previously accepted idempotent receipts remain readable without creating new mail. Dispatch independently rechecks account, template, event, suppression, domain and node health. Production requires one To recipient, a reviewed immutable template version with restricted variables, and a fresh unused verified event bound to the exact tenant, recipient and rendered email. Metadata labels and customer-published templates alone do not authorize mail. Cc/Bcc, custom headers, attachments and content overrides are rejected. Marketing subscription preferences do not block required transactional mail; bounce and complaint suppressions still do.", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Client-generated unique key. Retrying with the same key returns the original accepted message rather than sending a duplicate.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendEmailRequest" }, "examples": { "verifiedCode": { "summary": "Use actual IDs from transactional setup and event verification", "value": { "to": "customer@example.com", "template": { "id": "11111111-1111-4111-8111-111111111111", "variables": { "CODE": "123456" } }, "metadata": { "event": "account.verification", "transaction_id": "22222222-2222-4222-8222-222222222222" } } } } } } }, "responses": { "202": { "description": "Accepted and queued for delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendEmailResponse" }, "examples": { "accepted": { "value": { "id": "dd303a7c-9c67-4db7-9725-df8e4c80b0ed", "status": "queued", "quota": { "dailyRemaining": 299, "monthlyRemaining": 8999, "dayResetsAt": "2026-09-07T00:00:00.000Z", "monthResetsAt": "2026-10-01T00:00:00.000Z" }, "createdAt": "2026-09-06T12:00:00.000Z", "recipients": 1 } } } } } }, "400": { "description": "Malformed or invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The `from` domain is not verified for this tenant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantically invalid message, e.g. neither `html` nor `text` supplied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Recipient quota or per-account retained storage limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Global retained storage limit, insufficient disk capacity or required configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency key was used for different content." }, "404": { "description": "Template not found in this account" } } }, "get": { "tags": [ "Emails" ], "operationId": "listEmails", "summary": "List sent emails and their delivery status", "description": "Returns a paginated list of messages belonging to the authenticated tenant, newest first. The tenant is taken from the API key, never from a parameter, so there is no input that widens the scope. Requires a full-access API key; sending-only keys return 403.\n\n`limit` is clamped to 1-100 and defaults to 25; `offset` is clamped to a minimum of 0 and defaults to 0. Values that are not finite numbers fall back to those defaults rather than erroring. An empty `status` is treated as absent. Supports cursor pagination with after or before; use pagination=cursor for the first cursor page. Offset fields remain available on legacy offset pages. A cursor page returns object, data and has_more.", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum number of messages to return. Truncated to an integer and clamped to 1-100. Defaults to 25.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "offset", "in": "query", "required": false, "description": "Number of messages to skip. Truncated to an integer and clamped to a minimum of 0. Defaults to 0.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "status", "in": "query", "required": false, "description": "Restrict the list to messages in this delivery status. Omitted or empty returns every status.", "schema": { "type": "string", "enum": [ "queued", "dispatching", "provider_accepted", "partial", "uncertain", "delivered", "bounced", "complained", "suppressed", "failed", "canceled" ] } }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "pagination", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "cursor" ] } } ], "responses": { "200": { "description": "A page of messages for this tenant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailList" }, "examples": { "page": { "value": { "object": "list", "data": [ { "id": "dd303a7c-9c67-4db7-9725-df8e4c80b0ed", "status": "queued", "from": "AMG ", "to": [ "dev@example.com" ], "subject": "Reset your password", "recipients": 1, "createdAt": "2026-09-06T12:00:00.000Z", "updatedAt": "2026-09-06T12:00:00.000Z", "providerMessageId": null, "lastError": null } ], "total": 1, "limit": 25, "offset": 0, "has_more": false } } } } } }, "401": { "description": "Missing, malformed, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Sending-only key lacks read access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/emails/{id}": { "get": { "tags": [ "Emails" ], "operationId": "getEmail", "summary": "Retrieve a sent email and its delivery status", "description": "Returns the stored record for a message belonging to the authenticated tenant. Messages are only visible to the tenant that sent them. Requires a full-access API key; sending-only keys return 403.", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Message id returned by POST /v1/emails.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The message record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Email" } } } }, "401": { "description": "Missing, malformed, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such message for this tenant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Sending-only key lacks read access." } } }, "patch": { "operationId": "updateEmail", "summary": "Reschedule an email before dispatch starts", "tags": [ "Emails" ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Email updated.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Invalid API key." }, "403": { "description": "Domain restriction or verification failure." }, "404": { "description": "Email not found." }, "409": { "description": "Idempotency conflict or dispatch already started." }, "429": { "description": "Recipient quota exceeded." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "scheduled_at" ], "additionalProperties": false, "properties": { "scheduled_at": { "type": "string", "format": "date-time", "nullable": false, "description": "ISO 8601 timezone timestamp, strictly in the future and within 30 days. Idempotent retries replay after this time." } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "description": "Only scheduled queued emails with no dispatch attempts can be rescheduled. Conflicting dispatch returns 409." } }, "/v1/api-keys": { "post": { "operationId": "post__api_keys", "tags": [ "API Keys" ], "summary": "Create a new API key", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyRequest" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyResponse" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "403": { "description": "Full-access key required" }, "404": { "description": "Not found in this account" } }, "security": [ { "apiKey": [] }, { "session": [] } ] }, "get": { "operationId": "get__api_keys", "tags": [ "API Keys" ], "summary": "Retrieve a list of API keys", "parameters": [ { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationAfter" }, { "$ref": "#/components/parameters/PaginationBefore" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListApiKeysResponse" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "403": { "description": "Full-access key required" }, "404": { "description": "Not found in this account" } }, "security": [ { "apiKey": [] }, { "session": [] } ] } }, "/v1/api-keys/{api_key_id}": { "patch": { "operationId": "patch__api_keys__api_key_id_", "tags": [ "API Keys" ], "summary": "Update an existing API key", "parameters": [ { "name": "api_key_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The API key ID." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateApiKeyRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateApiKeyResponse" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "403": { "description": "Full-access key required" }, "404": { "description": "Not found in this account" } }, "security": [ { "apiKey": [] }, { "session": [] } ] }, "delete": { "operationId": "delete__api_keys__api_key_id_", "tags": [ "API Keys" ], "summary": "Remove an existing API key", "parameters": [ { "name": "api_key_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The API key ID." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiKeyResponse" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "403": { "description": "Full-access key required" }, "404": { "description": "Not found in this account" } }, "security": [ { "apiKey": [] }, { "session": [] } ] } }, "/v1/suppressions": { "post": { "operationId": "post__suppressions", "tags": [ "Suppressions" ], "summary": "Create a suppression", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSuppressionOptions" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSuppressionResponseSuccess" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "403": { "description": "Full-access key required" }, "404": { "description": "Not found in this account" } }, "security": [ { "apiKey": [] }, { "session": [] } ] }, "get": { "operationId": "get__suppressions", "tags": [ "Suppressions" ], "summary": "Retrieve a list of suppressions", "parameters": [ { "name": "origin", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "bounce", "complaint", "manual" ] }, "description": "Filter suppressions by origin." }, { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationAfter" }, { "$ref": "#/components/parameters/PaginationBefore" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSuppressionsResponseSuccess" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "403": { "description": "Full-access key required" }, "404": { "description": "Not found in this account" } }, "security": [ { "apiKey": [] }, { "session": [] } ] } }, "/v1/suppressions/batch/add": { "post": { "operationId": "post__suppressions_batch_add", "tags": [ "Suppressions" ], "summary": "Add up to 100 suppressions at once", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchAddSuppressionsOptions" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchAddSuppressionsResponseSuccess" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "403": { "description": "Full-access key required" }, "404": { "description": "Not found in this account" } }, "security": [ { "apiKey": [] }, { "session": [] } ] } }, "/v1/suppressions/batch/remove": { "post": { "operationId": "post__suppressions_batch_remove", "tags": [ "Suppressions" ], "summary": "Remove up to 100 suppressions at once", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchRemoveSuppressionsOptions" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchRemoveSuppressionsResponseSuccess" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "403": { "description": "Full-access key required" }, "404": { "description": "Not found in this account" } }, "security": [ { "apiKey": [] }, { "session": [] } ] } }, "/v1/suppressions/{suppression}": { "get": { "operationId": "get__suppressions__suppression_", "tags": [ "Suppressions" ], "summary": "Retrieve a single suppression by ID or email", "parameters": [ { "name": "suppression", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Suppression ID or email address." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSuppressionResponseSuccess" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "403": { "description": "Full-access key required" }, "404": { "description": "Not found in this account" } }, "security": [ { "apiKey": [] }, { "session": [] } ] }, "delete": { "operationId": "delete__suppressions__suppression_", "tags": [ "Suppressions" ], "summary": "Remove a single suppression by ID or email", "parameters": [ { "name": "suppression", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Suppression ID or email address." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveSuppressionResponseSuccess" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "403": { "description": "Full-access key required" }, "404": { "description": "Not found in this account" } }, "security": [ { "apiKey": [] }, { "session": [] } ] } }, "/v1/keys": { "get": { "summary": "List dashboard API keys", "operationId": "get__v1_keys", "security": [ { "session": [] } ], "description": "", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PublicKey" } } } } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permission or invalid origin" }, "404": { "description": "Resource not found in this account" }, "405": { "description": "Method not allowed" }, "429": { "description": "Rate or quota limit" }, "503": { "description": "Required service not configured" } } }, "post": { "summary": "Create a dashboard API key", "operationId": "post__v1_keys", "security": [ { "session": [] } ], "description": "Creates a dashboard key and returns its secret once. Optional domain_id restricts a sending-only key to an active domain owned by this account. Foreign, deleted, malformed or full-access domain bindings are rejected.", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicKey" }, { "type": "object", "properties": { "key": { "type": "string", "description": "Secret returned once only." } } } ] } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permission or invalid origin" }, "404": { "description": "Resource not found in this account" }, "405": { "description": "Method not allowed" }, "429": { "description": "Rate or quota limit" }, "503": { "description": "Required service not configured" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 120 }, "scope": { "type": "string", "enum": [ "full", "sending" ] }, "domain_id": { "type": "string", "format": "uuid", "description": "Optional owned active sending domain. Requires scope sending." } }, "required": [ "name" ] } } } } } }, "/v1/keys/{id}": { "delete": { "summary": "Revoke a dashboard API key", "operationId": "delete__v1_keys__id_", "security": [ { "session": [] } ], "description": "", "responses": { "204": { "description": "Key revoked; empty response body." }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permission or invalid origin" }, "404": { "description": "Resource not found in this account" }, "405": { "description": "Method not allowed" }, "429": { "description": "Rate or quota limit" }, "503": { "description": "Required service not configured" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/v1/domains": { "get": { "summary": "List domains", "operationId": "get__v1_domains", "security": [ { "apiKey": [] }, { "session": [] } ], "description": "", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Domain" } } } } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permission or invalid origin" }, "404": { "description": "Resource not found in this account" }, "405": { "description": "Method not allowed" }, "429": { "description": "Rate or quota limit" }, "503": { "description": "Required service not configured" } }, "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Cursor ID in this account. Use either after or before." }, { "name": "before", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Cursor ID in this account. Use either after or before." } ] }, "post": { "summary": "Register a sending domain", "operationId": "post__v1_domains", "security": [ { "apiKey": [] }, { "session": [] } ], "description": "Ownership and signing configuration are controlled by Emailer API. Provisioning fields cannot be supplied by callers.", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permission or invalid origin" }, "404": { "description": "Resource not found in this account" }, "405": { "description": "Method not allowed" }, "429": { "description": "Rate or quota limit" }, "503": { "description": "Required service not configured" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } } } } } }, "/v1/domains/{id}": { "get": { "summary": "Retrieve a domain", "operationId": "get__v1_domains__id_", "security": [ { "apiKey": [] }, { "session": [] } ], "description": "", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permission or invalid origin" }, "404": { "description": "Resource not found in this account" }, "405": { "description": "Method not allowed" }, "429": { "description": "Rate or quota limit" }, "503": { "description": "Required service not configured" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "delete": { "summary": "Remove a domain", "operationId": "delete__v1_domains__id_", "security": [ { "apiKey": [] }, { "session": [] } ], "description": "Disables sending and hides the domain while retaining historical email and dispatch records.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "deleted": { "type": "boolean" } } } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permission or invalid origin" }, "404": { "description": "Resource not found in this account" }, "405": { "description": "Method not allowed" }, "429": { "description": "Rate or quota limit" }, "503": { "description": "Required service not configured" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/v1/domains/{id}/verify": { "post": { "summary": "Verify domain DNS", "operationId": "post__v1_domains__id__verify", "security": [ { "apiKey": [] }, { "session": [] } ], "description": "Check DNS ownership and SPF. The private signing service then generates a domain-specific DKIM key. Publish the returned DKIM and DMARC records and verify again. Customers cannot choose a key, pool or readiness result. sendingReady requires exact DNS and key checks; failed or stale checks block sending.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Domain" }, { "type": "object", "properties": { "checks": { "type": "array", "items": { "type": "object", "properties": { "purpose": { "type": "string" }, "name": { "type": "string" }, "ok": { "type": "boolean" }, "reason": { "type": "string" } } } }, "reason": { "type": "string" } } } ] } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permission or invalid origin" }, "404": { "description": "Resource not found in this account" }, "405": { "description": "Method not allowed" }, "429": { "description": "Rate or quota limit" }, "503": { "description": "Required service not configured" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/v1/webhooks": { "get": { "summary": "List webhooks", "operationId": "get__v1_webhooks", "security": [ { "apiKey": [] }, { "session": [] } ], "description": "", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } } } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permission or invalid origin" }, "404": { "description": "Resource not found in this account" }, "405": { "description": "Method not allowed" }, "429": { "description": "Rate or quota limit" }, "503": { "description": "Required service not configured" } }, "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Cursor ID in this account. Use either after or before." }, { "name": "before", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Cursor ID in this account. Use either after or before." } ] }, "post": { "summary": "Create a webhook", "operationId": "post__v1_webhooks", "security": [ { "apiKey": [] }, { "session": [] } ], "description": "Provide url or endpoint. Only public HTTPS destinations are allowed. Current supported event subscriptions are listed in the request schema.", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "type": "object", "properties": { "object": { "type": "string" }, "secret": { "type": "string", "description": "Signing secret returned once." } } } ] } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permission or invalid origin" }, "404": { "description": "Resource not found in this account" }, "405": { "description": "Method not allowed" }, "429": { "description": "Rate or quota limit" }, "503": { "description": "Required service not configured" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "endpoint": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "delivered", "deferred", "bounced", "complained", "email.delivered", "email.delivery_delayed", "email.bounced", "email.complained" ] } }, "enabled": { "type": "boolean" }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] } } } } } } } }, "/v1/webhooks/{id}": { "get": { "summary": "Retrieve a webhook", "operationId": "get__v1_webhooks__id_", "security": [ { "apiKey": [] }, { "session": [] } ], "description": "", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permission or invalid origin" }, "404": { "description": "Resource not found in this account" }, "405": { "description": "Method not allowed" }, "429": { "description": "Rate or quota limit" }, "503": { "description": "Required service not configured" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "patch": { "summary": "Update a webhook", "operationId": "patch__v1_webhooks__id_", "security": [ { "apiKey": [] }, { "session": [] } ], "description": "", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permission or invalid origin" }, "404": { "description": "Resource not found in this account" }, "405": { "description": "Method not allowed" }, "429": { "description": "Rate or quota limit" }, "503": { "description": "Required service not configured" } }, "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", "format": "uri" }, "endpoint": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "delivered", "deferred", "bounced", "complained", "email.delivered", "email.delivery_delayed", "email.bounced", "email.complained" ] } }, "enabled": { "type": "boolean" }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] } } } } } } }, "delete": { "summary": "Delete a webhook", "operationId": "delete__v1_webhooks__id_", "security": [ { "apiKey": [] }, { "session": [] } ], "description": "", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permission or invalid origin" }, "404": { "description": "Resource not found in this account" }, "405": { "description": "Method not allowed" }, "429": { "description": "Rate or quota limit" }, "503": { "description": "Required service not configured" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/v1/ai/templates": { "post": { "summary": "Draft an email and three subject lines", "operationId": "post__v1_ai_templates", "security": [ { "apiKey": [] }, { "session": [] } ], "description": "", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "subjects": { "type": "array", "items": { "type": "string" } }, "body": { "type": "object", "properties": { "text": { "type": "string" }, "html": { "type": "string" } } }, "model": { "type": "object", "properties": { "requested": { "type": "string" }, "resolved": { "type": "string" } } } } } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permission or invalid origin" }, "404": { "description": "Resource not found in this account" }, "405": { "description": "Method not allowed" }, "429": { "description": "Rate or quota limit" }, "503": { "description": "Required service not configured" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 1, "maxLength": 4000 }, "tone": { "type": "string", "maxLength": 100 }, "variables": { "type": "array", "items": { "type": "string" } } }, "required": [ "prompt" ] } } } } } }, "/v1/ai/subjects": { "post": { "summary": "Generate three subject variations", "operationId": "post__v1_ai_subjects", "security": [ { "apiKey": [] }, { "session": [] } ], "description": "", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "subjects": { "type": "array", "items": { "type": "string" } }, "model": { "type": "object", "properties": { "requested": { "type": "string" }, "resolved": { "type": "string" } } } } } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permission or invalid origin" }, "404": { "description": "Resource not found in this account" }, "405": { "description": "Method not allowed" }, "429": { "description": "Rate or quota limit" }, "503": { "description": "Required service not configured" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 1, "maxLength": 4000 }, "tone": { "type": "string", "maxLength": 100 }, "variables": { "type": "array", "items": { "type": "string" } } }, "required": [ "prompt" ] } } } } } }, "/v1/ai/explain-error": { "post": { "summary": "Explain a delivery failure", "operationId": "post__v1_ai_explain_error", "security": [ { "apiKey": [] }, { "session": [] } ], "description": "", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "summary": { "type": "string" }, "likelyCause": { "type": "string" }, "category": { "type": "string" }, "retryable": { "type": "boolean" }, "steps": { "type": "array", "items": { "type": "string" } }, "model": { "type": "object", "properties": { "requested": { "type": "string" }, "resolved": { "type": "string" } } } } } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permission or invalid origin" }, "404": { "description": "Resource not found in this account" }, "405": { "description": "Method not allowed" }, "429": { "description": "Rate or quota limit" }, "503": { "description": "Required service not configured" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "smtp_code": { "type": "string" }, "bounce_reason": { "type": "string" }, "recipient_domain": { "type": "string" } }, "required": [ "smtp_code", "bounce_reason" ] } } } } } }, "/v1/ai/debug": { "post": { "summary": "Explain a delivery failure", "operationId": "post__v1_ai_debug", "security": [ { "apiKey": [] }, { "session": [] } ], "description": "", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "summary": { "type": "string" }, "likelyCause": { "type": "string" }, "category": { "type": "string" }, "retryable": { "type": "boolean" }, "steps": { "type": "array", "items": { "type": "string" } }, "model": { "type": "object", "properties": { "requested": { "type": "string" }, "resolved": { "type": "string" } } } } } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permission or invalid origin" }, "404": { "description": "Resource not found in this account" }, "405": { "description": "Method not allowed" }, "429": { "description": "Rate or quota limit" }, "503": { "description": "Required service not configured" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "smtp_code": { "type": "string" }, "bounce_reason": { "type": "string" }, "recipient_domain": { "type": "string" } }, "required": [ "smtp_code", "bounce_reason" ] } } } } } }, "/v1/ai/usage": { "get": { "summary": "Retrieve shared AI allowance", "operationId": "get__v1_ai_usage", "security": [ { "apiKey": [] }, { "session": [] } ], "description": "", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "used": { "type": "integer" }, "limit": { "type": "integer" }, "remaining": { "type": "integer" }, "resetsAt": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permission or invalid origin" }, "404": { "description": "Resource not found in this account" }, "405": { "description": "Method not allowed" }, "429": { "description": "Rate or quota limit" }, "503": { "description": "Required service not configured" } } } }, "/v1/auth/signup": { "post": { "summary": "Signup for the dashboard", "operationId": "post__v1_auth_signup", "security": [], "description": "Requires a permitted Origin or Referer. Sets a secure HttpOnly session cookie.", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string" } } }, "tenant": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } } } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permission or invalid origin" }, "404": { "description": "Resource not found in this account" }, "405": { "description": "Method not allowed" }, "429": { "description": "Rate or quota limit" }, "503": { "description": "Required service not configured" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "format": "password" }, "tenantName": { "type": "string" } }, "required": [ "email", "password" ] } } } } } }, "/v1/auth/login": { "post": { "summary": "Login for the dashboard", "operationId": "post__v1_auth_login", "security": [], "description": "Requires a permitted Origin or Referer. Sets a secure HttpOnly session cookie.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string" } } }, "tenant": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } } } } } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permission or invalid origin" }, "404": { "description": "Resource not found in this account" }, "405": { "description": "Method not allowed" }, "429": { "description": "Rate or quota limit" }, "503": { "description": "Required service not configured" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "format": "password" }, "tenantName": { "type": "string" } }, "required": [ "email", "password" ] } } } } } }, "/v1/auth/me": { "get": { "summary": "Retrieve current dashboard session", "operationId": "get__v1_auth_me", "security": [ { "session": [] } ], "description": "", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string" } } }, "tenant": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "session": { "type": "object", "properties": { "expiresAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permission or invalid origin" }, "404": { "description": "Resource not found in this account" }, "405": { "description": "Method not allowed" }, "429": { "description": "Rate or quota limit" }, "503": { "description": "Required service not configured" } } } }, "/v1/auth/logout": { "post": { "summary": "Revoke current session", "operationId": "post__v1_auth_logout", "security": [ { "session": [] } ], "description": "", "responses": { "204": { "description": "Session revoked; empty response body." }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permission or invalid origin" }, "404": { "description": "Resource not found in this account" }, "405": { "description": "Method not allowed" }, "429": { "description": "Rate or quota limit" }, "503": { "description": "Required service not configured" } } } }, "/v1/usage/overview": { "get": { "summary": "Dashboard usage and delivery trend", "operationId": "get__v1_usage_overview", "security": [ { "session": [] } ], "description": " Includes sending_access status, code, message and expires_at for the authenticated account. Quota does not imply pilot approval; configured grant recipients are never disclosed here.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "quota": { "type": "object", "properties": { "day": { "type": "object", "properties": { "used": { "type": "integer" }, "limit": { "type": "integer" }, "resetsAt": { "type": "string", "format": "date-time" } } }, "month": { "type": "object", "properties": { "used": { "type": "integer" }, "limit": { "type": "integer" }, "resetsAt": { "type": "string", "format": "date-time" } } } } }, "trend": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "sent": { "type": "integer" }, "delivered": { "type": "integer" }, "bounced": { "type": "integer" } } } }, "sending_access": { "type": "object", "required": [ "status", "code", "message", "expires_at" ], "properties": { "status": { "type": "string", "enum": [ "pending", "pilot", "expired", "unavailable", "development" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } } } } } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permission or invalid origin" }, "404": { "description": "Resource not found in this account" }, "405": { "description": "Method not allowed" }, "429": { "description": "Rate or quota limit" }, "503": { "description": "Required service not configured" } } } }, "/v1/events/mta": { "post": { "summary": "Ingest an authenticated MTA delivery event", "operationId": "post__v1_events_mta", "security": [ { "mtaSignature": [] } ], "description": "Operator integration only. Tenant identity comes from the immutable dispatch correlation; caller-provided tenant IDs are not trusted.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event_receipt" ] }, "status": { "type": "string" }, "message_id": { "type": [ "string", "null" ] }, "previous_status": { "type": [ "string", "null" ] }, "status_after": { "type": [ "string", "null" ] }, "suppressed": { "type": "boolean" }, "pool_paused": { "type": "boolean" }, "webhooks_queued": { "type": "integer" } } } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permission or invalid origin" }, "404": { "description": "Resource not found in this account" }, "405": { "description": "Method not allowed" }, "429": { "description": "Rate or quota limit" }, "503": { "description": "Required service not configured" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event_id": { "type": "string" }, "wire_message_id": { "type": "string" }, "recipient": { "type": "string" }, "event": { "type": "string", "enum": [ "delivered", "deferred", "bounced", "complained" ] }, "smtp_code": { "type": "string" }, "diagnostic": { "type": "string" }, "occurred_at": { "type": "string", "format": "date-time" } }, "required": [ "event_id", "wire_message_id", "recipient", "event" ] } } } } } }, "/health": { "get": { "summary": "Read availability and dispatch readiness", "operationId": "get__health", "security": [], "description": "", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok", "degraded" ] }, "database": { "type": "object", "properties": { "reachable": { "type": "boolean" } } }, "dispatch": { "type": "object", "properties": { "mail": { "type": "object", "properties": { "ready": { "type": "boolean" }, "reason": { "type": "string" } } }, "webhooks": { "type": "object", "properties": { "ready": { "type": "boolean" }, "reason": { "type": "string" } } } } } } } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permission or invalid origin" }, "404": { "description": "Resource not found in this account" }, "405": { "description": "Method not allowed" }, "429": { "description": "Rate or quota limit" }, "503": { "description": "Required service not configured" } } } }, "/healthz": { "get": { "summary": "Read availability and dispatch readiness", "operationId": "get__healthz", "security": [], "description": "", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok", "degraded" ] }, "database": { "type": "object", "properties": { "reachable": { "type": "boolean" } } }, "dispatch": { "type": "object", "properties": { "mail": { "type": "object", "properties": { "ready": { "type": "boolean" }, "reason": { "type": "string" } } }, "webhooks": { "type": "object", "properties": { "ready": { "type": "boolean" }, "reason": { "type": "string" } } } } } } } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permission or invalid origin" }, "404": { "description": "Resource not found in this account" }, "405": { "description": "Method not allowed" }, "429": { "description": "Rate or quota limit" }, "503": { "description": "Required service not configured" } } } }, "/v1/emails/batch": { "post": { "operationId": "sendBatchEmails", "summary": "Atomically enqueue up to 100 emails", "tags": [ "Emails" ], "security": [ { "apiKey": [] } ], "responses": { "202": { "description": "Durably queued.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" } } } } } } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Invalid API key." }, "403": { "description": "Domain restriction or verification failure." }, "404": { "description": "Template not found in this account" }, "409": { "description": "Idempotency conflict or dispatch already started." }, "429": { "description": "Recipient quota or per-account retained storage limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Global retained storage limit, insufficient disk capacity or required configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/SendEmailRequest" } } } } }, "description": "All-or-nothing validation, verified domains, recipient quota reservation and enqueue. Ordered response IDs correspond to request order. Attachments, schedules and tags are supported. 202 is queue acceptance. Idempotency keys bind the entire ordered batch for 24 hours, separately from single email keys. A batch failure never leaves partial sends or quota charges. Expanded rendered bodies and Base64 attachments across a batch are limited to 42 MiB. Retained email payload storage is bounded across single sends, batches and broadcasts, including canceled or completed messages while their bodies remain stored. Launch defaults are 64 MiB per account and 256 MiB globally; operators can configure MAIL_STORAGE_TENANT_BYTES and MAIL_STORAGE_GLOBAL_BYTES. Accounting includes a 1 KiB per-message allowance and serialized content/addresses/options/attachments; it is a logical budget, not measured disk usage. New admission is serialized globally and commits with quota and queue rows. Tenant storage exhaustion returns 429 mail_storage_limit_exceeded; global storage exhaustion returns 503. Low/unavailable database filesystem capacity returns 503 without keeping quota or partial rows. A valid retry of an already accepted idempotency key bypasses new storage admission. Delivery and cancellation do not free retained bytes. Existing history is backfilled without deleting content. These are storage limits in addition to daily/monthly recipient quotas; increasing them requires real host capacity. Production self-service mail requires a verified owner email, current domain signing, a verified application integration, and a fresh approved event for the exact template and recipient. Blocked requests reserve no quota or mail storage. Previously accepted idempotent receipts remain readable without creating new mail. Dispatch independently rechecks account, template, event, suppression, domain and node health. Production requires one To recipient, a reviewed immutable template version with restricted variables, and a fresh unused verified event bound to the exact tenant, recipient and rendered email. Metadata labels and customer-published templates alone do not authorize mail. Cc/Bcc, custom headers, attachments and content overrides are rejected. Marketing subscription preferences do not block required transactional mail; bounce and complaint suppressions still do.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 } } ] } }, "/v1/emails/{id}/cancel": { "post": { "operationId": "cancelEmail", "summary": "Cancel a scheduled email before dispatch starts", "tags": [ "Emails" ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Email updated.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Invalid API key." }, "403": { "description": "Domain restriction or verification failure." }, "404": { "description": "Email not found." }, "409": { "description": "Idempotency conflict or dispatch already started." }, "429": { "description": "Recipient quota exceeded." } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "description": "Idempotent cancellation. Only scheduled emails with no dispatch attempts can be canceled. Quota reserved at acceptance is retained; no second quota charge is made. Serialized against dispatcher claims." } }, "/v1/emails/{email_id}/attachments": { "get": { "operationId": "emails/list-attachments", "tags": [ "Emails" ], "summary": "Retrieve a list of attachments for a sent email", "parameters": [ { "name": "email_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The ID of the email." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Maximum number of attachments to return." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Pagination cursor to fetch results after this attachment ID. Cannot be used with 'before'." }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Pagination cursor to fetch results before this attachment ID. Cannot be used with 'after'." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAttachmentsResponse" } } } }, "400": { "description": "Invalid cursor or limit." }, "401": { "description": "Authentication required." }, "403": { "description": "Full access required." }, "404": { "description": "Email or attachment not found." }, "503": { "description": "Dedicated download secret is not configured." } }, "security": [ { "apiKey": [] } ], "description": "Full-access API key or dashboard session required. Attachment content stays private; download_url is a bearer link valid for one hour. List pagination follows immutable attachment order." } }, "/v1/emails/{email_id}/attachments/{attachment_id}": { "get": { "operationId": "emails/get-attachment", "tags": [ "Emails" ], "summary": "Retrieve a single attachment for a sent email", "parameters": [ { "name": "email_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The ID of the email." }, { "name": "attachment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The ID of the attachment." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrievedAttachment" } } } }, "400": { "description": "Invalid cursor or limit." }, "401": { "description": "Authentication required." }, "403": { "description": "Full access required." }, "404": { "description": "Email or attachment not found." }, "503": { "description": "Dedicated download secret is not configured." } }, "security": [ { "apiKey": [] } ], "description": "Full-access API key or dashboard session required. Attachment content stays private; download_url is a bearer link valid for one hour. List pagination follows immutable attachment order." } }, "/v1/attachments/download/{token}": { "get": { "operationId": "downloadAttachment", "summary": "Download an attachment using an expiring signed link", "security": [], "description": "A valid unexpired token authorizes only one immutable attachment. No cookies or API key required. Suspended accounts cannot download. Response forces attachment download and is not cacheable.", "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Original file bytes.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Invalid, expired or unavailable download." }, "503": { "description": "Download secret not configured." } } }, "head": { "operationId": "inspectAttachmentDownload", "summary": "Read signed attachment download headers", "security": [], "description": "A valid unexpired token authorizes only one immutable attachment. No cookies or API key required. Suspended accounts cannot download. Response forces attachment download and is not cacheable.", "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Original file bytes.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Invalid, expired or unavailable download." }, "503": { "description": "Download secret not configured." } } } }, "/v1/emails/metrics": { "get": { "operationId": "getEmailMetrics", "summary": "Retrieve recipient delivery metrics from stored evidence", "security": [ { "apiKey": [] }, { "session": [] } ], "description": "Email-created-at recipient cohorts with delivery outcomes, permanent/transient/unclassified bounces, unique and total open/click observations, proxy/automation indicators, tracking coverage and rates. Engagement is deduplicated per link per minute, capped at 1,000 observations/link over 30 days; counts are not proof of human engagement. Rates name their denominator in response notes and are null when unmeasured. Historical untracked mail has null opens/clicks. No spam-folder placement or unsubscribe tracking. Detailed engagement history lasts 90 days; aggregate counts remain. Full-access key or session. Max 10,000 groups.", "parameters": [ { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string" }, "description": "ISO date or timezone timestamp; default six days before end_date at UTC midnight." }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string" }, "description": "ISO date inclusive through that day, or timezone timestamp. Defaults to now; future end clamped to now." }, { "name": "timezone", "in": "query", "required": false, "schema": { "type": "string" }, "description": "IANA timezone for period buckets; default UTC." }, { "name": "granularity", "in": "query", "required": false, "schema": { "type": "string" }, "description": "hourly, daily, weekly or monthly; default daily." }, { "name": "metrics", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated metric names. Omit for all; uncollected measurements are null." }, { "name": "dimensions", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated period, domain, email. No dimensions returns totals only." }, { "name": "domain_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Up to 100 comma-separated domain UUIDs." }, { "name": "email_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Up to 100 comma-separated email UUIDs." } ], "responses": { "200": { "description": "Known measurements and explicit unavailable metrics.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "metrics" ] }, "start_date": { "type": "string", "format": "date-time" }, "end_date": { "type": "string", "format": "date-time" }, "totals": { "type": "object", "properties": { "received": { "type": "number", "nullable": true }, "provider_accepted": { "type": "number", "nullable": true }, "delivered": { "type": "number", "nullable": true }, "delivery_delayed": { "type": "number", "nullable": true }, "failed": { "type": "number", "nullable": true }, "suppressed": { "type": "number", "nullable": true }, "bounced": { "type": "number", "nullable": true }, "complained": { "type": "number", "nullable": true }, "sent": { "type": "number", "nullable": true }, "bounced_transient": { "type": "number", "nullable": true }, "bounced_permanent": { "type": "number", "nullable": true }, "bounced_undetermined": { "type": "number", "nullable": true }, "opened": { "type": "number", "nullable": true }, "unique_opened": { "type": "number", "nullable": true }, "clicked": { "type": "number", "nullable": true }, "unique_clicked": { "type": "number", "nullable": true }, "unsubscribed": { "type": "number", "nullable": true }, "delivery_rate": { "type": "number", "nullable": true }, "open_rate": { "type": "number", "nullable": true }, "click_rate": { "type": "number", "nullable": true }, "bounce_rate": { "type": "number", "nullable": true }, "complaint_rate": { "type": "number", "nullable": true }, "unsubscribe_rate": { "type": "number", "nullable": true }, "proxy_observations": { "type": "number", "nullable": true }, "automated_observations": { "type": "number", "nullable": true }, "open_tracking_recipients": { "type": "number", "nullable": true }, "click_tracking_recipients": { "type": "number", "nullable": true }, "spam_placement_rate": { "type": "number", "nullable": true } } }, "data": { "type": "array", "items": { "type": "object" } }, "metrics": { "type": "array", "items": { "type": "string" } }, "dimensions": { "type": "array", "items": { "type": "string" } }, "granularity": { "type": "string" }, "timezone": { "type": "string" }, "measurement_unit": { "type": "string", "enum": [ "recipient" ] }, "date_basis": { "type": "string", "enum": [ "email_created_at" ] }, "unavailable_metrics": { "type": "array", "items": { "type": "string" } }, "notes": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "Invalid parameter, range, timezone or unsupported dimension." }, "401": { "description": "Authentication required." }, "403": { "description": "Full-access key required." } } } }, "/v1/templates": { "post": { "operationId": "templates_create", "tags": [ "Templates" ], "summary": "Create a template", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTemplateRequest" } } }, "required": true }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTemplateResponseSuccess" } } } }, "400": { "description": "Invalid template, variables or pagination", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Full-access key or permitted session origin required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Template not found in this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Alias already in use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "description": "Full-access API key or dashboard session. IDs and aliases are scoped to the authenticated account. Session writes require the configured Origin or Referer." }, "get": { "operationId": "templates_list", "tags": [ "Templates" ], "summary": "Retrieve a list of templates", "parameters": [ { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationAfter" }, { "$ref": "#/components/parameters/PaginationBefore" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTemplatesResponseSuccess" } } } }, "400": { "description": "Invalid template, variables or pagination", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Full-access key or permitted session origin required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Template not found in this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Alias already in use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "description": "Full-access API key or dashboard session. IDs and aliases are scoped to the authenticated account. Session writes require the configured Origin or Referer." } }, "/v1/templates/{id}": { "get": { "operationId": "templates_get", "tags": [ "Templates" ], "summary": "Retrieve a single template", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Template ID or alias." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Template" } } } }, "400": { "description": "Invalid template, variables or pagination", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Full-access key or permitted session origin required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Template not found in this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Alias already in use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "description": "Full-access API key or dashboard session. IDs and aliases are scoped to the authenticated account. Session writes require the configured Origin or Referer." }, "patch": { "operationId": "templates_update", "tags": [ "Templates" ], "summary": "Update an existing template", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Template ID or alias." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTemplateOptions" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTemplateResponseSuccess" } } } }, "400": { "description": "Invalid template, variables or pagination", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Full-access key or permitted session origin required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Template not found in this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Alias already in use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "description": "Full-access API key or dashboard session. IDs and aliases are scoped to the authenticated account. Session writes require the configured Origin or Referer." }, "delete": { "operationId": "templates_remove", "tags": [ "Templates" ], "summary": "Remove an existing template", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Template ID or alias." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveTemplateResponseSuccess" } } } }, "400": { "description": "Invalid template, variables or pagination", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Full-access key or permitted session origin required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Template not found in this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Alias already in use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "description": "Full-access API key or dashboard session. IDs and aliases are scoped to the authenticated account. Session writes require the configured Origin or Referer." } }, "/v1/templates/{id}/publish": { "post": { "operationId": "templates_publish", "tags": [ "Templates" ], "summary": "Publish a template", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Template ID or alias." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishTemplateResponseSuccess" } } } }, "400": { "description": "Invalid template, variables or pagination", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Full-access key or permitted session origin required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Template not found in this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Alias already in use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "description": "Full-access API key or dashboard session. IDs and aliases are scoped to the authenticated account. Session writes require the configured Origin or Referer." } }, "/v1/templates/{id}/duplicate": { "post": { "operationId": "templates_duplicate", "tags": [ "Templates" ], "summary": "Duplicate a template", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Template ID or alias." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DuplicateTemplateResponseSuccess" } } } }, "400": { "description": "Invalid template, variables or pagination", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Full-access key or permitted session origin required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Template not found in this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Alias already in use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "description": "Full-access API key or dashboard session. IDs and aliases are scoped to the authenticated account. Session writes require the configured Origin or Referer." } }, "/v1/audiences": { "post": { "operationId": "audiences_create", "tags": [ "Audiences" ], "summary": "Create a list of contacts", "deprecated": true, "description": "Full-access API key or dashboard session. Resources and cursors are tenant scoped. Session writes require a configured Origin or Referer. Collections default to 20 results and support limit=1..100 plus after/before cursors. Deprecated audiences share the same underlying identities as segments. Deleting a group preserves contacts.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAudienceOptions" } } }, "required": true }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAudienceResponseSuccess" } } } }, "400": { "description": "Invalid or immutable fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Full-access key or permitted session required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Contact/property already exists or explicit resubscription is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ] }, "get": { "operationId": "audiences_list", "tags": [ "Audiences" ], "summary": "Retrieve a list of audiences", "deprecated": true, "description": "Full-access API key or dashboard session. Resources and cursors are tenant scoped. Session writes require a configured Origin or Referer. Collections default to 20 results and support limit=1..100 plus after/before cursors. Deprecated audiences share the same underlying identities as segments. Deleting a group preserves contacts.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAudiencesResponseSuccess" } } } }, "400": { "description": "Invalid or immutable fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Full-access key or permitted session required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Contact/property already exists or explicit resubscription is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "parameters": [ { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationAfter" }, { "$ref": "#/components/parameters/PaginationBefore" } ] } }, "/v1/audiences/{id}": { "delete": { "operationId": "audiences_remove", "tags": [ "Audiences" ], "summary": "Remove an existing audience", "deprecated": true, "description": "Full-access API key or dashboard session. Resources and cursors are tenant scoped. Session writes require a configured Origin or Referer. Collections default to 20 results and support limit=1..100 plus after/before cursors. Deprecated audiences share the same underlying identities as segments. Deleting a group preserves contacts.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Audience ID." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveAudienceResponseSuccess" } } } }, "400": { "description": "Invalid or immutable fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Full-access key or permitted session required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Contact/property already exists or explicit resubscription is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ] }, "get": { "operationId": "audiences_get", "tags": [ "Audiences" ], "summary": "Retrieve a single audience", "deprecated": true, "description": "Full-access API key or dashboard session. Resources and cursors are tenant scoped. Session writes require a configured Origin or Referer. Collections default to 20 results and support limit=1..100 plus after/before cursors. Deprecated audiences share the same underlying identities as segments. Deleting a group preserves contacts.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Audience ID." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAudienceResponseSuccess" } } } }, "400": { "description": "Invalid or immutable fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Full-access key or permitted session required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Contact/property already exists or explicit resubscription is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ] } }, "/v1/contacts": { "post": { "operationId": "contacts_create", "tags": [ "Contacts" ], "summary": "Create a new contact", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateContactOptions" } } }, "required": true }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateContactResponseSuccess" } } } }, "400": { "description": "Invalid or immutable fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Full-access key or permitted session required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Contact/property already exists or explicit resubscription is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "description": "Full-access API key or dashboard session. Resources and cursors are tenant scoped. Session writes require a configured Origin or Referer. Collections default to 20 results and support limit=1..100 plus after/before cursors. Creation atomically validates memberships, properties and preferences. Existing contacts return 409; use PATCH to update. Global/topic opt-outs survive deletion/recreation. A create request cannot opt an address back in after an earlier opt-out; create without an override then explicitly PATCH to opt in." }, "get": { "operationId": "contacts_list", "tags": [ "Contacts" ], "summary": "Retrieve a list of contacts", "parameters": [ { "name": "segment_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter contacts by segment ID." }, { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationAfter" }, { "$ref": "#/components/parameters/PaginationBefore" }, { "name": "audience_id", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListContactsResponseSuccess" } } } }, "400": { "description": "Invalid or immutable fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Full-access key or permitted session required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Contact/property already exists or explicit resubscription is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "description": "Full-access API key or dashboard session. Resources and cursors are tenant scoped. Session writes require a configured Origin or Referer. Collections default to 20 results and support limit=1..100 plus after/before cursors." } }, "/v1/contacts/{id}": { "get": { "operationId": "contacts_get", "tags": [ "Contacts" ], "summary": "Retrieve a single contact by ID or email", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Contact ID or email address." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetContactResponseSuccess" } } } }, "400": { "description": "Invalid or immutable fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Full-access key or permitted session required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Contact/property already exists or explicit resubscription is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "description": "Full-access API key or dashboard session. Resources and cursors are tenant scoped. Session writes require a configured Origin or Referer. Collections default to 20 results and support limit=1..100 plus after/before cursors." }, "patch": { "operationId": "contacts_update", "tags": [ "Contacts" ], "summary": "Update a single contact by ID or email", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Contact ID or email address." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateContactOptions" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateContactResponseSuccess" } } } }, "400": { "description": "Invalid or immutable fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Full-access key or permitted session required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Contact/property already exists or explicit resubscription is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "description": "Full-access API key or dashboard session. Resources and cursors are tenant scoped. Session writes require a configured Origin or Referer. Collections default to 20 results and support limit=1..100 plus after/before cursors." }, "delete": { "operationId": "contacts_remove", "tags": [ "Contacts" ], "summary": "Remove an existing contact by ID or email", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Contact ID or email address." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveContactResponseSuccess" } } } }, "400": { "description": "Invalid or immutable fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Full-access key or permitted session required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Contact/property already exists or explicit resubscription is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "description": "Full-access API key or dashboard session. Resources and cursors are tenant scoped. Session writes require a configured Origin or Referer. Collections default to 20 results and support limit=1..100 plus after/before cursors. Removes contact details and memberships. Minimal tenant-scoped hashed opt-out state and subscription audit remain to prevent accidental resubscription." } }, "/v1/segments": { "post": { "operationId": "segments_create", "tags": [ "Segments" ], "summary": "Create a new segment", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSegmentOptions" } } }, "required": true }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSegmentResponseSuccess" } } } }, "400": { "description": "Invalid or immutable fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Full-access key or permitted session required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Contact/property already exists or explicit resubscription is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "description": "Full-access API key or dashboard session. Resources and cursors are tenant scoped. Session writes require a configured Origin or Referer. Collections default to 20 results and support limit=1..100 plus after/before cursors." }, "get": { "operationId": "segments_list", "tags": [ "Segments" ], "summary": "Retrieve a list of segments", "parameters": [ { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationAfter" }, { "$ref": "#/components/parameters/PaginationBefore" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSegmentsResponseSuccess" } } } }, "400": { "description": "Invalid or immutable fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Full-access key or permitted session required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Contact/property already exists or explicit resubscription is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "description": "Full-access API key or dashboard session. Resources and cursors are tenant scoped. Session writes require a configured Origin or Referer. Collections default to 20 results and support limit=1..100 plus after/before cursors." } }, "/v1/segments/{id}": { "get": { "operationId": "segments_get", "tags": [ "Segments" ], "summary": "Retrieve a single segment", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Segment ID." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSegmentResponseSuccess" } } } }, "400": { "description": "Invalid or immutable fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Full-access key or permitted session required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Contact/property already exists or explicit resubscription is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "description": "Full-access API key or dashboard session. Resources and cursors are tenant scoped. Session writes require a configured Origin or Referer. Collections default to 20 results and support limit=1..100 plus after/before cursors." }, "patch": { "operationId": "segments_update", "tags": [ "Segments" ], "summary": "Update an existing segment", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Segment ID." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSegmentOptions" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSegmentResponseSuccess" } } } }, "400": { "description": "Invalid or immutable fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Full-access key or permitted session required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Contact/property already exists or explicit resubscription is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "description": "Full-access API key or dashboard session. Resources and cursors are tenant scoped. Session writes require a configured Origin or Referer. Collections default to 20 results and support limit=1..100 plus after/before cursors." }, "delete": { "operationId": "segments_remove", "tags": [ "Segments" ], "summary": "Remove an existing segment", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Segment ID." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveSegmentResponseSuccess" } } } }, "400": { "description": "Invalid or immutable fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Full-access key or permitted session required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Contact/property already exists or explicit resubscription is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "description": "Full-access API key or dashboard session. Resources and cursors are tenant scoped. Session writes require a configured Origin or Referer. Collections default to 20 results and support limit=1..100 plus after/before cursors." } }, "/v1/topics": { "post": { "operationId": "topics_create", "tags": [ "Topics" ], "summary": "Create a new topic", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTopicOptions" } } }, "required": true }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTopicResponseSuccess" } } } }, "400": { "description": "Invalid or immutable fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Full-access key or permitted session required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Contact/property already exists or explicit resubscription is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "description": "Full-access API key or dashboard session. Resources and cursors are tenant scoped. Session writes require a configured Origin or Referer. Collections default to 20 results and support limit=1..100 plus after/before cursors." }, "get": { "operationId": "topics_list", "tags": [ "Topics" ], "summary": "Retrieve a list of topics", "parameters": [ { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationAfter" }, { "$ref": "#/components/parameters/PaginationBefore" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTopicsResponseSuccess" } } } }, "400": { "description": "Invalid or immutable fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Full-access key or permitted session required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Contact/property already exists or explicit resubscription is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "description": "Full-access API key or dashboard session. Resources and cursors are tenant scoped. Session writes require a configured Origin or Referer. Collections default to 20 results and support limit=1..100 plus after/before cursors." } }, "/v1/topics/{id}": { "get": { "operationId": "topics_get", "tags": [ "Topics" ], "summary": "Retrieve a single topic", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Topic ID." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetTopicResponseSuccess" } } } }, "400": { "description": "Invalid or immutable fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Full-access key or permitted session required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Contact/property already exists or explicit resubscription is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "description": "Full-access API key or dashboard session. Resources and cursors are tenant scoped. Session writes require a configured Origin or Referer. Collections default to 20 results and support limit=1..100 plus after/before cursors." }, "patch": { "operationId": "topics_update", "tags": [ "Topics" ], "summary": "Update an existing topic", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Topic ID." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTopicOptions" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTopicResponseSuccess" } } } }, "400": { "description": "Invalid or immutable fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Full-access key or permitted session required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Contact/property already exists or explicit resubscription is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "description": "Full-access API key or dashboard session. Resources and cursors are tenant scoped. Session writes require a configured Origin or Referer. Collections default to 20 results and support limit=1..100 plus after/before cursors." }, "delete": { "operationId": "topics_remove", "tags": [ "Topics" ], "summary": "Remove an existing topic", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Topic ID." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveTopicResponseSuccess" } } } }, "400": { "description": "Invalid or immutable fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Full-access key or permitted session required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Contact/property already exists or explicit resubscription is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "description": "Full-access API key or dashboard session. Resources and cursors are tenant scoped. Session writes require a configured Origin or Referer. Collections default to 20 results and support limit=1..100 plus after/before cursors." } }, "/v1/contact-properties": { "post": { "operationId": "contact-properties_create", "tags": [ "Contact Properties" ], "summary": "Create a new contact property", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateContactPropertyOptions" } } }, "required": true }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateContactPropertyResponseSuccess" } } } }, "400": { "description": "Invalid or immutable fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Full-access key or permitted session required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Contact/property already exists or explicit resubscription is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "description": "Full-access API key or dashboard session. Resources and cursors are tenant scoped. Session writes require a configured Origin or Referer. Collections default to 20 results and support limit=1..100 plus after/before cursors." }, "get": { "operationId": "contact-properties_list", "tags": [ "Contact Properties" ], "summary": "Retrieve a list of contact properties", "parameters": [ { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationAfter" }, { "$ref": "#/components/parameters/PaginationBefore" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListContactPropertiesResponseSuccess" } } } }, "400": { "description": "Invalid or immutable fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Full-access key or permitted session required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Contact/property already exists or explicit resubscription is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "description": "Full-access API key or dashboard session. Resources and cursors are tenant scoped. Session writes require a configured Origin or Referer. Collections default to 20 results and support limit=1..100 plus after/before cursors." } }, "/v1/contact-properties/{id}": { "get": { "operationId": "contact-properties_get", "tags": [ "Contact Properties" ], "summary": "Retrieve a single contact property", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Contact Property ID." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetContactPropertyResponseSuccess" } } } }, "400": { "description": "Invalid or immutable fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Full-access key or permitted session required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Contact/property already exists or explicit resubscription is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "description": "Full-access API key or dashboard session. Resources and cursors are tenant scoped. Session writes require a configured Origin or Referer. Collections default to 20 results and support limit=1..100 plus after/before cursors." }, "patch": { "operationId": "contact-properties_update", "tags": [ "Contact Properties" ], "summary": "Update an existing contact property", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Contact Property ID." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateContactPropertyOptions" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateContactPropertyResponseSuccess" } } } }, "400": { "description": "Invalid or immutable fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Full-access key or permitted session required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Contact/property already exists or explicit resubscription is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "description": "Full-access API key or dashboard session. Resources and cursors are tenant scoped. Session writes require a configured Origin or Referer. Collections default to 20 results and support limit=1..100 plus after/before cursors." }, "delete": { "operationId": "contact-properties_remove", "tags": [ "Contact Properties" ], "summary": "Remove an existing contact property", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Contact Property ID." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveContactPropertyResponseSuccess" } } } }, "400": { "description": "Invalid or immutable fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Full-access key or permitted session required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Contact/property already exists or explicit resubscription is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "description": "Full-access API key or dashboard session. Resources and cursors are tenant scoped. Session writes require a configured Origin or Referer. Collections default to 20 results and support limit=1..100 plus after/before cursors." } }, "/v1/contacts/{contact_id}/segments": { "get": { "operationId": "contacts_list-segments", "tags": [ "Contacts" ], "summary": "Retrieve a list of segments for a contact", "parameters": [ { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Contact ID or email address." }, { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationAfter" }, { "$ref": "#/components/parameters/PaginationBefore" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListContactSegmentsResponseSuccess" } } } }, "400": { "description": "Invalid or immutable fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Full-access key or permitted session required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Contact/property already exists or explicit resubscription is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "description": "Full-access API key or dashboard session. Resources and cursors are tenant scoped. Session writes require a configured Origin or Referer. Collections default to 20 results and support limit=1..100 plus after/before cursors." } }, "/v1/contacts/{contact_id}/segments/{segment_id}": { "post": { "operationId": "contacts_add-segment", "tags": [ "Contacts" ], "summary": "Add a contact to a segment", "parameters": [ { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Contact ID or email address." }, { "name": "segment_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Segment ID." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddContactToSegmentResponseSuccess" } } } }, "400": { "description": "Invalid or immutable fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Full-access key or permitted session required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Contact/property already exists or explicit resubscription is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "description": "Full-access API key or dashboard session. Resources and cursors are tenant scoped. Session writes require a configured Origin or Referer. Collections default to 20 results and support limit=1..100 plus after/before cursors." }, "delete": { "operationId": "contacts_remove-segment", "tags": [ "Contacts" ], "summary": "Remove a contact from a segment", "parameters": [ { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Contact ID or email address." }, { "name": "segment_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Segment ID." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveContactFromSegmentResponseSuccess" } } } }, "400": { "description": "Invalid or immutable fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Full-access key or permitted session required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Contact/property already exists or explicit resubscription is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "description": "Full-access API key or dashboard session. Resources and cursors are tenant scoped. Session writes require a configured Origin or Referer. Collections default to 20 results and support limit=1..100 plus after/before cursors." } }, "/v1/contacts/{contact_id}/topics": { "get": { "operationId": "contacts_list-topics", "tags": [ "Contacts" ], "summary": "Retrieve topics for a contact", "parameters": [ { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Contact ID or email address." }, { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationAfter" }, { "$ref": "#/components/parameters/PaginationBefore" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetContactTopicsResponseSuccess" } } } }, "400": { "description": "Invalid or immutable fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Full-access key or permitted session required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Contact/property already exists or explicit resubscription is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "description": "Full-access API key or dashboard session. Resources and cursors are tenant scoped. Session writes require a configured Origin or Referer. Collections default to 20 results and support limit=1..100 plus after/before cursors. Returns effective topic preferences from explicit subscriptions, remembered opt-outs, or immutable topic defaults. Global unsubscribed overrides all topics when sending broadcasts. It does not suppress transactional email." }, "patch": { "operationId": "contacts_update-topics", "tags": [ "Contacts" ], "summary": "Update topics for a contact", "parameters": [ { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Contact ID or email address." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateContactTopicsOptions" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateContactTopicsResponseSuccess" } } } }, "400": { "description": "Invalid or immutable fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Full-access key or permitted session required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Contact/property already exists or explicit resubscription is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "description": "Full-access API key or dashboard session. Resources and cursors are tenant scoped. Session writes require a configured Origin or Referer. Collections default to 20 results and support limit=1..100 plus after/before cursors." } }, "/v1/segments/{segment_id}/contacts": { "get": { "operationId": "segments_list_contacts", "tags": [ "Contacts" ], "summary": "List contacts in a segment", "parameters": [ { "name": "segment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationAfter" }, { "$ref": "#/components/parameters/PaginationBefore" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListContactsResponseSuccess" } } } }, "400": { "description": "Invalid or immutable fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Full-access key or permitted session required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Contact/property already exists or explicit resubscription is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "description": "Full-access API key or dashboard session. Resources and cursors are tenant scoped. Session writes require a configured Origin or Referer. Collections default to 20 results and support limit=1..100 plus after/before cursors." } }, "/v1/broadcasts": { "post": { "operationId": "broadcasts_create", "tags": [ "Broadcasts" ], "summary": "Create a broadcast", "description": "Unavailable in production: Emailer API is transactional-only. Full-access API key or dashboard session; session writes require Origin/Referer. Broadcasts snapshot the segment when submitted, skip ineligible recipients, and atomically reserve quota and enqueue personalized messages. Limit: 1000 contacts in a segment and 40 MiB aggregate rendered queue payload. Daily/monthly recipient quotas also apply. Templates support contact.property|fallback and RESEND_UNSUBSCRIBE_URL (AMG_UNSUBSCRIBE_URL alias), with HTML escaping for all contact substitutions. Missing visible unsubscribe links are appended. Quota is charged at submission, including future schedules, and is not refunded on cancellation. Repeated send with the identical schedule replays the existing run. Creating a broadcast is not idempotent; retrieve its ID before retrying submission. Queued means stored, not sent. Broadcast SMTP requires dedicated pool credentials plus operator-verified DKIM coverage of both List-Unsubscribe headers. One-click links expire 365 days after the intended send date. Opt-outs, contact identity and membership are rechecked before claim and immediately before SMTP; an already-started SMTP transaction cannot be recalled. Open/click tracking and bounce classifications are unavailable. Retained email payload storage is bounded across single sends, batches and broadcasts, including canceled or completed messages while their bodies remain stored. Launch defaults are 64 MiB per account and 256 MiB globally; operators can configure MAIL_STORAGE_TENANT_BYTES and MAIL_STORAGE_GLOBAL_BYTES. Accounting includes a 1 KiB per-message allowance and serialized content/addresses/options/attachments; it is a logical budget, not measured disk usage. New admission is serialized globally and commits with quota and queue rows. Tenant storage exhaustion returns 429 mail_storage_limit_exceeded; global storage exhaustion returns 503. Low/unavailable database filesystem capacity returns 503 without keeping quota or partial rows. A valid retry of an already accepted idempotency key bypasses new storage admission. Delivery and cancellation do not free retained bytes. Existing history is backfilled without deleting content. These are storage limits in addition to daily/monthly recipient quotas; increasing them requires real host capacity.", "security": [ { "apiKey": [] }, { "session": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string" } }, "required": [ "id", "status" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope or sender domain not permitted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Broadcast state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Broadcast too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Recipient quota or per-account retained storage limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Global retained storage limit, insufficient disk capacity or required configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBroadcastRequest" } } } } }, "get": { "operationId": "broadcasts_list", "tags": [ "Broadcasts" ], "summary": "List broadcasts", "description": "Full-access API key or dashboard session; session writes require Origin/Referer. Broadcasts snapshot the segment when submitted, skip ineligible recipients, and atomically reserve quota and enqueue personalized messages. Limit: 1000 contacts in a segment and 40 MiB aggregate rendered queue payload. Daily/monthly recipient quotas also apply. Templates support contact.property|fallback and RESEND_UNSUBSCRIBE_URL (AMG_UNSUBSCRIBE_URL alias), with HTML escaping for all contact substitutions. Missing visible unsubscribe links are appended. Quota is charged at submission, including future schedules, and is not refunded on cancellation. Repeated send with the identical schedule replays the existing run. Creating a broadcast is not idempotent; retrieve its ID before retrying submission. Queued means stored, not sent. Broadcast SMTP requires dedicated pool credentials plus operator-verified DKIM coverage of both List-Unsubscribe headers. One-click links expire 365 days after the intended send date. Opt-outs, contact identity and membership are rechecked before claim and immediately before SMTP; an already-started SMTP transaction cannot be recalled. Open/click tracking and bounce classifications are unavailable.", "security": [ { "apiKey": [] }, { "session": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "const": "list" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Broadcast" } } }, "required": [ "object", "has_more", "data" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope or sender domain not permitted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Broadcast state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Broadcast too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Recipient quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Unsubscribe configuration required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationAfter" }, { "$ref": "#/components/parameters/PaginationBefore" } ] } }, "/v1/broadcasts/{id}": { "get": { "operationId": "broadcasts_get", "tags": [ "Broadcasts" ], "summary": "Retrieve a broadcast", "description": "Full-access API key or dashboard session; session writes require Origin/Referer. Broadcasts snapshot the segment when submitted, skip ineligible recipients, and atomically reserve quota and enqueue personalized messages. Limit: 1000 contacts in a segment and 40 MiB aggregate rendered queue payload. Daily/monthly recipient quotas also apply. Templates support contact.property|fallback and RESEND_UNSUBSCRIBE_URL (AMG_UNSUBSCRIBE_URL alias), with HTML escaping for all contact substitutions. Missing visible unsubscribe links are appended. Quota is charged at submission, including future schedules, and is not refunded on cancellation. Repeated send with the identical schedule replays the existing run. Creating a broadcast is not idempotent; retrieve its ID before retrying submission. Queued means stored, not sent. Broadcast SMTP requires dedicated pool credentials plus operator-verified DKIM coverage of both List-Unsubscribe headers. One-click links expire 365 days after the intended send date. Opt-outs, contact identity and membership are rechecked before claim and immediately before SMTP; an already-started SMTP transaction cannot be recalled. Open/click tracking and bounce classifications are unavailable.", "security": [ { "apiKey": [] }, { "session": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Broadcast" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope or sender domain not permitted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Broadcast state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Broadcast too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Recipient quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Unsubscribe configuration required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "patch": { "operationId": "broadcasts_update", "tags": [ "Broadcasts" ], "summary": "Edit a draft broadcast", "description": "Full-access API key or dashboard session; session writes require Origin/Referer. Broadcasts snapshot the segment when submitted, skip ineligible recipients, and atomically reserve quota and enqueue personalized messages. Limit: 1000 contacts in a segment and 40 MiB aggregate rendered queue payload. Daily/monthly recipient quotas also apply. Templates support contact.property|fallback and RESEND_UNSUBSCRIBE_URL (AMG_UNSUBSCRIBE_URL alias), with HTML escaping for all contact substitutions. Missing visible unsubscribe links are appended. Quota is charged at submission, including future schedules, and is not refunded on cancellation. Repeated send with the identical schedule replays the existing run. Creating a broadcast is not idempotent; retrieve its ID before retrying submission. Queued means stored, not sent. Broadcast SMTP requires dedicated pool credentials plus operator-verified DKIM coverage of both List-Unsubscribe headers. One-click links expire 365 days after the intended send date. Opt-outs, contact identity and membership are rechecked before claim and immediately before SMTP; an already-started SMTP transaction cannot be recalled. Open/click tracking and bounce classifications are unavailable.", "security": [ { "apiKey": [] }, { "session": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } }, "required": [ "id" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope or sender domain not permitted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Broadcast state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Broadcast too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Recipient quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Unsubscribe configuration required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBroadcastRequest" } } } } }, "delete": { "operationId": "broadcasts_remove", "tags": [ "Broadcasts" ], "summary": "Delete a draft, canceled or completed broadcast", "description": "Full-access API key or dashboard session; session writes require Origin/Referer. Broadcasts snapshot the segment when submitted, skip ineligible recipients, and atomically reserve quota and enqueue personalized messages. Limit: 1000 contacts in a segment and 40 MiB aggregate rendered queue payload. Daily/monthly recipient quotas also apply. Templates support contact.property|fallback and RESEND_UNSUBSCRIBE_URL (AMG_UNSUBSCRIBE_URL alias), with HTML escaping for all contact substitutions. Missing visible unsubscribe links are appended. Quota is charged at submission, including future schedules, and is not refunded on cancellation. Repeated send with the identical schedule replays the existing run. Creating a broadcast is not idempotent; retrieve its ID before retrying submission. Queued means stored, not sent. Broadcast SMTP requires dedicated pool credentials plus operator-verified DKIM coverage of both List-Unsubscribe headers. One-click links expire 365 days after the intended send date. Opt-outs, contact identity and membership are rechecked before claim and immediately before SMTP; an already-started SMTP transaction cannot be recalled. Open/click tracking and bounce classifications are unavailable.", "security": [ { "apiKey": [] }, { "session": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "const": "broadcast" }, "id": { "type": "string", "format": "uuid" }, "deleted": { "const": true } }, "required": [ "object", "id", "deleted" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope or sender domain not permitted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Broadcast state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Broadcast too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Recipient quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Unsubscribe configuration required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/v1/broadcasts/{id}/send": { "post": { "operationId": "broadcasts_send", "tags": [ "Broadcasts" ], "summary": "Submit or schedule a broadcast", "description": "Full-access API key or dashboard session; session writes require Origin/Referer. Broadcasts snapshot the segment when submitted, skip ineligible recipients, and atomically reserve quota and enqueue personalized messages. Limit: 1000 contacts in a segment and 40 MiB aggregate rendered queue payload. Daily/monthly recipient quotas also apply. Templates support contact.property|fallback and RESEND_UNSUBSCRIBE_URL (AMG_UNSUBSCRIBE_URL alias), with HTML escaping for all contact substitutions. Missing visible unsubscribe links are appended. Quota is charged at submission, including future schedules, and is not refunded on cancellation. Repeated send with the identical schedule replays the existing run. Creating a broadcast is not idempotent; retrieve its ID before retrying submission. Queued means stored, not sent. Broadcast SMTP requires dedicated pool credentials plus operator-verified DKIM coverage of both List-Unsubscribe headers. One-click links expire 365 days after the intended send date. Opt-outs, contact identity and membership are rechecked before claim and immediately before SMTP; an already-started SMTP transaction cannot be recalled. Open/click tracking and bounce classifications are unavailable. Retained email payload storage is bounded across single sends, batches and broadcasts, including canceled or completed messages while their bodies remain stored. Launch defaults are 64 MiB per account and 256 MiB globally; operators can configure MAIL_STORAGE_TENANT_BYTES and MAIL_STORAGE_GLOBAL_BYTES. Accounting includes a 1 KiB per-message allowance and serialized content/addresses/options/attachments; it is a logical budget, not measured disk usage. New admission is serialized globally and commits with quota and queue rows. Tenant storage exhaustion returns 429 mail_storage_limit_exceeded; global storage exhaustion returns 503. Low/unavailable database filesystem capacity returns 503 without keeping quota or partial rows. A valid retry of an already accepted idempotency key bypasses new storage admission. Delivery and cancellation do not free retained bytes. Existing history is backfilled without deleting content. These are storage limits in addition to daily/monthly recipient quotas; increasing them requires real host capacity. Production self-service mail requires a verified owner email, current domain signing, a verified application integration, and a fresh approved event for the exact template and recipient. Blocked requests reserve no quota or mail storage. Previously accepted idempotent receipts remain readable without creating new mail. Dispatch independently rechecks account, template, event, suppression, domain and node health.", "security": [ { "apiKey": [] }, { "session": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string" } }, "required": [ "id", "status" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope or sender domain not permitted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Broadcast state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Broadcast too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Recipient quota or per-account retained storage limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Global retained storage limit, insufficient disk capacity or required configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "scheduled_at": { "type": "string", "format": "date-time" } }, "required": [], "additionalProperties": false } } } } } }, "/v1/broadcasts/{id}/cancel": { "post": { "operationId": "broadcasts_cancel", "tags": [ "Broadcasts" ], "summary": "Cancel pending broadcast messages", "description": "Full-access API key or dashboard session; session writes require Origin/Referer. Broadcasts snapshot the segment when submitted, skip ineligible recipients, and atomically reserve quota and enqueue personalized messages. Limit: 1000 contacts in a segment and 40 MiB aggregate rendered queue payload. Daily/monthly recipient quotas also apply. Templates support contact.property|fallback and RESEND_UNSUBSCRIBE_URL (AMG_UNSUBSCRIBE_URL alias), with HTML escaping for all contact substitutions. Missing visible unsubscribe links are appended. Quota is charged at submission, including future schedules, and is not refunded on cancellation. Repeated send with the identical schedule replays the existing run. Creating a broadcast is not idempotent; retrieve its ID before retrying submission. Queued means stored, not sent. Broadcast SMTP requires dedicated pool credentials plus operator-verified DKIM coverage of both List-Unsubscribe headers. One-click links expire 365 days after the intended send date. Opt-outs, contact identity and membership are rechecked before claim and immediately before SMTP; an already-started SMTP transaction cannot be recalled. Open/click tracking and bounce classifications are unavailable. Canceling a future schedule returns it to draft. Canceling a queued broadcast sets canceled and stops remaining queue entries. Accepted or in-flight SMTP cannot be recalled.", "security": [ { "apiKey": [] }, { "session": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string" } }, "required": [ "id", "status" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope or sender domain not permitted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Broadcast state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Broadcast too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Recipient quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Unsubscribe configuration required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/v1/broadcasts/{id}/recipients": { "get": { "operationId": "broadcasts_recipients", "tags": [ "Broadcasts" ], "summary": "List recipients with recorded broadcast events", "description": "Full-access API key or dashboard session; session writes require Origin/Referer. Broadcasts snapshot the segment when submitted, skip ineligible recipients, and atomically reserve quota and enqueue personalized messages. Limit: 1000 contacts in a segment and 40 MiB aggregate rendered queue payload. Daily/monthly recipient quotas also apply. Templates support contact.property|fallback and RESEND_UNSUBSCRIBE_URL (AMG_UNSUBSCRIBE_URL alias), with HTML escaping for all contact substitutions. Missing visible unsubscribe links are appended. Quota is charged at submission, including future schedules, and is not refunded on cancellation. Repeated send with the identical schedule replays the existing run. Creating a broadcast is not idempotent; retrieve its ID before retrying submission. Queued means stored, not sent. Broadcast SMTP requires dedicated pool credentials plus operator-verified DKIM coverage of both List-Unsubscribe headers. One-click links expire 365 days after the intended send date. Opt-outs, contact identity and membership are rechecked before claim and immediately before SMTP; an already-started SMTP transaction cannot be recalled. Open/click tracking and bounce classifications are unavailable. Filters use stored delivery events; sent denotes SMTP relay acceptance. One-click opt-outs are attributed to the broadcast run. Contact_id is null if the profile was deleted. opened/clicked and bounce_type filters return 501, never a fabricated empty measurement.", "security": [ { "apiKey": [] }, { "session": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "const": "list" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/BroadcastRecipient" } } }, "required": [ "object", "has_more", "data" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope or sender domain not permitted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Broadcast state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Broadcast too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Recipient quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Unsubscribe configuration required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Measurement unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "type", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "sent", "delivered", "opened", "clicked", "bounced", "complained", "unsubscribed", "suppressed" ] } }, { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationAfter" }, { "$ref": "#/components/parameters/PaginationBefore" }, { "name": "email", "in": "query", "schema": { "type": "string", "maxLength": 320 }, "description": "Literal case-insensitive substring filter." }, { "name": "bounce_type", "in": "query", "schema": { "type": "string" }, "description": "Returns 501 because bounce classification is unavailable." } ] } }, "/unsubscribe/{token}": { "get": { "operationId": "unsubscribe_get", "tags": [ "Subscriptions" ], "summary": "Show unsubscribe confirmation", "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 1600 } } ], "description": "Encrypted authenticated recipient/list claim is the sole authority. No API key, cookies or login required. GET/HEAD never mutate. POST accepts exactly List-Unsubscribe=One-Click in URL-encoded or multipart form data and never redirects. Repeated requests are idempotent. Global or original topic opt-outs survive deletion/recreation and apply even to suspended accounts. Responses are no-store and no-referrer. Do not log the token path. Real one-click deliverability requires DKIM covering List-Unsubscribe and List-Unsubscribe-Post.", "responses": { "200": { "description": "Confirmation or completed opt-out", "content": { "text/html": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid form", "content": { "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "Invalid, expired or unavailable claim", "content": { "text/html": { "schema": { "type": "string" } } } }, "413": { "description": "Form exceeds 4 KiB", "content": { "text/html": { "schema": { "type": "string" } } } } } }, "head": { "operationId": "unsubscribe_head", "tags": [ "Subscriptions" ], "summary": "Check an unsubscribe link without changing preferences", "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 1600 } } ], "description": "Encrypted authenticated recipient/list claim is the sole authority. No API key, cookies or login required. GET/HEAD never mutate. POST accepts exactly List-Unsubscribe=One-Click in URL-encoded or multipart form data and never redirects. Repeated requests are idempotent. Global or original topic opt-outs survive deletion/recreation and apply even to suspended accounts. Responses are no-store and no-referrer. Do not log the token path. Real one-click deliverability requires DKIM covering List-Unsubscribe and List-Unsubscribe-Post.", "responses": { "200": { "description": "Confirmation or completed opt-out" }, "400": { "description": "Invalid form" }, "404": { "description": "Invalid, expired or unavailable claim" }, "413": { "description": "Form exceeds 4 KiB" } } }, "post": { "operationId": "unsubscribe_post", "tags": [ "Subscriptions" ], "summary": "Apply a signed one-click opt-out", "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 1600 } } ], "description": "Encrypted authenticated recipient/list claim is the sole authority. No API key, cookies or login required. GET/HEAD never mutate. POST accepts exactly List-Unsubscribe=One-Click in URL-encoded or multipart form data and never redirects. Repeated requests are idempotent. Global or original topic opt-outs survive deletion/recreation and apply even to suspended accounts. Responses are no-store and no-referrer. Do not log the token path. Real one-click deliverability requires DKIM covering List-Unsubscribe and List-Unsubscribe-Post.", "responses": { "200": { "description": "Confirmation or completed opt-out", "content": { "text/html": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid form", "content": { "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "Invalid, expired or unavailable claim", "content": { "text/html": { "schema": { "type": "string" } } } }, "413": { "description": "Form exceeds 4 KiB", "content": { "text/html": { "schema": { "type": "string" } } } } }, "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "List-Unsubscribe": { "type": "string", "enum": [ "One-Click" ] } }, "required": [ "List-Unsubscribe" ], "additionalProperties": false } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "List-Unsubscribe": { "type": "string", "enum": [ "One-Click" ] } }, "required": [ "List-Unsubscribe" ], "additionalProperties": false } } } } } }, "/v1/contacts/imports": { "post": { "operationId": "contact_imports_create", "tags": [ "Contact Imports" ], "summary": "Upload and queue a contact import", "description": "Full-access API key or dashboard session; session writes require Origin/Referer. Upload CSV with multipart/form-data. Limits: 5 MiB UTF-8 CSV, 10000 data rows, 200 columns, 16384 characters per cell; body 6 MiB, parsed rows 10 MiB. This is below Resend current 200 MB limit. At most two active imports and 20 MiB parsed source per tenant; 100 MiB global queued source. Storage admission checks require sufficient free space. Imports process in durable batches of at most 25 rows: contact mutation, source deletion and count updates commit together. completed means every row was processed, not every row succeeded. Counts distinguish created/updated/skipped/failed. First 100 row errors retained without uploaded values. Source rows are deleted after processing. Upsert never clears a remembered global/topic opt-out; false/opt_in cannot resubscribe an opted-out address. Use an explicit contact update for resubscription. Skip does not change existing contacts. New property definitions are created from typed mappings, then bound by immutable ID; deletion/recreation cannot redirect a pending import. Boolean values accept true/false/1/0. Blank numeric/boolean cells leave existing properties unchanged. Suspended tenants are not processed. Storage pauses preserve progress and expose blocked_reason. No emails are sent by import. Optional Idempotency-Key replays an identical CSV/settings submission for 24 hours without creating another job; changed input returns 409.", "security": [ { "apiKey": [] }, { "session": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "object": { "const": "contact_import" } }, "required": [ "id", "object" ] } } } }, "400": { "description": "Invalid CSV/settings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Import too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Active import capacity exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Storage unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 256 } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CreateContactImportRequest" } } } } }, "get": { "operationId": "contact_imports_list", "tags": [ "Contact Imports" ], "summary": "List contact imports", "description": "Full-access API key or dashboard session; session writes require Origin/Referer. Upload CSV with multipart/form-data. Limits: 5 MiB UTF-8 CSV, 10000 data rows, 200 columns, 16384 characters per cell; body 6 MiB, parsed rows 10 MiB. This is below Resend current 200 MB limit. At most two active imports and 20 MiB parsed source per tenant; 100 MiB global queued source. Storage admission checks require sufficient free space. Imports process in durable batches of at most 25 rows: contact mutation, source deletion and count updates commit together. completed means every row was processed, not every row succeeded. Counts distinguish created/updated/skipped/failed. First 100 row errors retained without uploaded values. Source rows are deleted after processing. Upsert never clears a remembered global/topic opt-out; false/opt_in cannot resubscribe an opted-out address. Use an explicit contact update for resubscription. Skip does not change existing contacts. New property definitions are created from typed mappings, then bound by immutable ID; deletion/recreation cannot redirect a pending import. Boolean values accept true/false/1/0. Blank numeric/boolean cells leave existing properties unchanged. Suspended tenants are not processed. Storage pauses preserve progress and expose blocked_reason. No emails are sent by import. Optional Idempotency-Key replays an identical CSV/settings submission for 24 hours without creating another job; changed input returns 409.", "security": [ { "apiKey": [] }, { "session": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "const": "list" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ContactImport" } } }, "required": [ "object", "has_more", "data" ] } } } }, "400": { "description": "Invalid CSV/settings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Import too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Active import capacity exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Storage unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationAfter" }, { "$ref": "#/components/parameters/PaginationBefore" } ] } }, "/v1/contacts/imports/{id}": { "get": { "operationId": "contact_imports_get", "tags": [ "Contact Imports" ], "summary": "Retrieve import progress and row errors", "description": "Full-access API key or dashboard session; session writes require Origin/Referer. Upload CSV with multipart/form-data. Limits: 5 MiB UTF-8 CSV, 10000 data rows, 200 columns, 16384 characters per cell; body 6 MiB, parsed rows 10 MiB. This is below Resend current 200 MB limit. At most two active imports and 20 MiB parsed source per tenant; 100 MiB global queued source. Storage admission checks require sufficient free space. Imports process in durable batches of at most 25 rows: contact mutation, source deletion and count updates commit together. completed means every row was processed, not every row succeeded. Counts distinguish created/updated/skipped/failed. First 100 row errors retained without uploaded values. Source rows are deleted after processing. Upsert never clears a remembered global/topic opt-out; false/opt_in cannot resubscribe an opted-out address. Use an explicit contact update for resubscription. Skip does not change existing contacts. New property definitions are created from typed mappings, then bound by immutable ID; deletion/recreation cannot redirect a pending import. Boolean values accept true/false/1/0. Blank numeric/boolean cells leave existing properties unchanged. Suspended tenants are not processed. Storage pauses preserve progress and expose blocked_reason. No emails are sent by import. Optional Idempotency-Key replays an identical CSV/settings submission for 24 hours without creating another job; changed input returns 409.", "security": [ { "apiKey": [] }, { "session": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactImport" } } } }, "400": { "description": "Invalid CSV/settings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Import too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Active import capacity exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Storage unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/v1/webhooks/{webhook_id}/events": { "get": { "operationId": "get__v1_webhooks_webhook_id_events", "tags": [ "Webhooks" ], "summary": "List webhook events", "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Cursor must belong to this webhook/event. before is not supported." } ], "security": [ { "apiKey": [] }, { "session": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "const": "list" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventSummary" } } }, "required": [ "object", "has_more", "data" ] } } } }, "400": { "description": "Invalid cursor or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or suspended account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Full-access API key or dashboard session. Newest events/attempts first, UUID tie-breaker. Event IDs equal X-AMG-Delivery-Id. Each new claim and outcome are journaled atomically. Interrupted leases have outcome unknown; bounded automatic retries can duplicate endpoint receipt, so deduplicate by delivery ID. No history is fabricated for attempts before recording began: event detail exposes attempt_count, recorded_attempt_count, history_complete and history_started_at. sent_at means attempt start, not proof of receipt. HTTP status is null before a response or when the outcome is unknown. Response bodies are not retained and response is null with response_redacted=true. Endpoint URLs, signing material and raw network errors are not included. Deleting a webhook deletes its events and attempts. Suspended tenants cannot read history or start new webhook claims. A disabled webhook retains history but does not dispatch. Current webhook event subscription vocabulary remains delivered, deferred/delivery_delayed, bounced and complained; other Resend event types remain pending." } }, "/v1/webhooks/{webhook_id}/events/{event_id}": { "get": { "operationId": "get__v1_webhooks_webhook_id_events_event_id", "tags": [ "Webhooks" ], "summary": "Retrieve a webhook event", "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "event_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "apiKey": [] }, { "session": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "400": { "description": "Invalid cursor or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or suspended account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Full-access API key or dashboard session. Newest events/attempts first, UUID tie-breaker. Event IDs equal X-AMG-Delivery-Id. Each new claim and outcome are journaled atomically. Interrupted leases have outcome unknown; bounded automatic retries can duplicate endpoint receipt, so deduplicate by delivery ID. No history is fabricated for attempts before recording began: event detail exposes attempt_count, recorded_attempt_count, history_complete and history_started_at. sent_at means attempt start, not proof of receipt. HTTP status is null before a response or when the outcome is unknown. Response bodies are not retained and response is null with response_redacted=true. Endpoint URLs, signing material and raw network errors are not included. Deleting a webhook deletes its events and attempts. Suspended tenants cannot read history or start new webhook claims. A disabled webhook retains history but does not dispatch. Current webhook event subscription vocabulary remains delivered, deferred/delivery_delayed, bounced and complained; other Resend event types remain pending." } }, "/v1/webhooks/{webhook_id}/events/{event_id}/attempts": { "get": { "operationId": "get__v1_webhooks_webhook_id_events_event_id_attempts", "tags": [ "Webhooks" ], "summary": "List webhook delivery attempts", "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "event_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Cursor must belong to this webhook/event. before is not supported." } ], "security": [ { "apiKey": [] }, { "session": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "const": "list" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookAttempt" } } }, "required": [ "object", "has_more", "data" ] } } } }, "400": { "description": "Invalid cursor or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or suspended account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Full-access API key or dashboard session. Newest events/attempts first, UUID tie-breaker. Event IDs equal X-AMG-Delivery-Id. Each new claim and outcome are journaled atomically. Interrupted leases have outcome unknown; bounded automatic retries can duplicate endpoint receipt, so deduplicate by delivery ID. No history is fabricated for attempts before recording began: event detail exposes attempt_count, recorded_attempt_count, history_complete and history_started_at. sent_at means attempt start, not proof of receipt. HTTP status is null before a response or when the outcome is unknown. Response bodies are not retained and response is null with response_redacted=true. Endpoint URLs, signing material and raw network errors are not included. Deleting a webhook deletes its events and attempts. Suspended tenants cannot read history or start new webhook claims. A disabled webhook retains history but does not dispatch. Current webhook event subscription vocabulary remains delivered, deferred/delivery_delayed, bounced and complained; other Resend event types remain pending." } }, "/v1/logs": { "get": { "summary": "List API request logs", "operationId": "request_logs_list", "tags": [ "Request Logs" ], "security": [ { "apiKey": [] }, { "session": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "before", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Recorded metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "const": "list" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApiRequestLogSummary" } }, "coverage": { "type": "object", "properties": { "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "max_age_days": { "const": 7 }, "global_max_records": { "const": 100000 }, "guaranteed_complete": { "const": false } }, "required": [ "started_at", "max_age_days", "global_max_records", "guaranteed_complete" ] } }, "required": [ "object", "has_more", "data", "coverage" ] } } } }, "400": { "description": "Invalid cursor or parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or suspended account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Log not retained in this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Full-access key or active dashboard session required. Actual authenticated HTTP API request metadata only. Response X-Request-Id correlates to log ID; client-supplied IDs are ignored. Records are written after response handling and may appear shortly afterward. Requests rejected before successful authentication, public/auth/MTA/tokenized download/unsubscribe routes, and unrecognized route templates are excluded. Sending-key requests are recorded but sending keys cannot read logs. Endpoint values are templates; user agent, headers, query/path parameters and request/response bodies are never stored. Missing/omitted content remains null with redaction metadata. Up to 100000 metadata records are retained globally in a fixed ring; oldest slots are reused, so a busy account can shorten history for others. Records older than 7 days are hidden and deleted in bounded background batches. Invalid/expired/foreign cursors return 400. Logging checks the production database filesystem capacity and fails independently from API acceptance; coverage is best-effort and is never claimed complete. No prior access logs are imported. Deleting a tenant deletes its request metadata." } }, "/v1/logs/{log_id}": { "get": { "summary": "Retrieve an API request log", "operationId": "request_logs_get", "tags": [ "Request Logs" ], "security": [ { "apiKey": [] }, { "session": [] } ], "parameters": [ { "name": "log_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Recorded metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiRequestLog" } } } }, "400": { "description": "Invalid cursor or parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or suspended account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Log not retained in this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Full-access key or active dashboard session required. Actual authenticated HTTP API request metadata only. Response X-Request-Id correlates to log ID; client-supplied IDs are ignored. Records are written after response handling and may appear shortly afterward. Requests rejected before successful authentication, public/auth/MTA/tokenized download/unsubscribe routes, and unrecognized route templates are excluded. Sending-key requests are recorded but sending keys cannot read logs. Endpoint values are templates; user agent, headers, query/path parameters and request/response bodies are never stored. Missing/omitted content remains null with redaction metadata. Up to 100000 metadata records are retained globally in a fixed ring; oldest slots are reused, so a busy account can shorten history for others. Records older than 7 days are hidden and deleted in bounded background batches. Invalid/expired/foreign cursors return 400. Logging checks the production database filesystem capacity and fails independently from API acceptance; coverage is best-effort and is never claimed complete. No prior access logs are imported. Deleting a tenant deletes its request metadata." } }, "/v1/usage": { "get": { "operationId": "retrieve_usage", "summary": "Retrieve tenant usage and configured limits", "tags": [ "Usage" ], "security": [ { "apiKey": [] }, { "session": [] } ], "responses": { "200": { "description": "Tenant accounting snapshot; Cache-Control: private, no-store.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" } } } }, "400": { "description": "Query parameters are not supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Full-access key or active session required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Use GET.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Mail storage limit configuration is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Full-access key or active dashboard session. A coherent read-only accounting snapshot with UTC calendar-day/month recipient reservations, live resource counts, AI call allowance and retained email payload bytes. This is not Resend rolling-window accounting. sent/received telemetry, automation runs and the general tenant API rate limit are unavailable/null. Null resource count limits mean no cap is configured, not a subscription entitlement. Shared storage and filesystem constraints still apply. No query parameters. The growth object reports actual account/domain allowances separately from the Free for Life roadmap target of 50,000/day, which is planned and unavailable. New self-service accounts start at 100/day and 3,000/month. Existing saved limits are preserved; account and domain ceilings do not reserve shared delivery capacity." } }, "/v1/emails/{id}/share": { "post": { "operationId": "share_email", "summary": "Create an expiring sent-email preview link", "tags": [ "Emails" ], "security": [ { "apiKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "description": "Full-access key or active dashboard session. Shares retained outbound content; received-email sharing is pending inbound support. The opaque URL grants read access until expiry (default/max 48 hours). Preview excludes BCC, private metadata, attachments and provider diagnostics; scripts, forms, styling, links and remote images are disabled. Body preview capped at 250000 characters with a visible notice. Tenant suspension or signing-key rotation invalidates links. No quota charge or content copy. Never log the returned URL.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "expires_in": { "type": "string", "default": "48h", "description": "Duration from1 second to 48 hours, e.g. 10m, 2 hours, 1 day. Supports s/sec/second(s),m/min/minute(s),h/hr/hour(s),d/day(s); decimal fractions up to 3 places." } } } } } }, "responses": { "200": { "description": "Private no-store share capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SharedEmail" } } } }, "400": { "description": "Invalid share options", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Full-access key or permitted session origin required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Email absent from this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Use POST", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Sharing configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/shared/{token}": { "get": { "operationId": "get_shared_email", "summary": "Read an expiring email preview", "tags": [ "Email Sharing" ], "security": [], "description": "Opaque capability authorizes this read; cookies and bearer credentials are ignored. Link invalidation follows expiry, missing record, tenant suspension or signing-key rotation. Strict sandbox/no-network HTML preview; HEAD returns no body. All responses disable caching/referrers/indexing. Public request-body maximum 4 KiB. No query parameters.", "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 700 } } ], "responses": { "200": { "description": "Email preview or HEAD response", "content": { "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "Invalid, expired or unavailable link", "content": { "text/html": { "schema": { "type": "string" } } } }, "405": { "description": "Use GET or HEAD", "content": { "text/html": { "schema": { "type": "string" } } } }, "413": { "description": "Request body too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "head": { "operationId": "head_shared_email", "summary": "Check an expiring email preview", "tags": [ "Email Sharing" ], "security": [], "description": "Opaque capability authorizes this read; cookies and bearer credentials are ignored. Link invalidation follows expiry, missing record, tenant suspension or signing-key rotation. Strict sandbox/no-network HTML preview; HEAD returns no body. All responses disable caching/referrers/indexing. Public request-body maximum 4 KiB. No query parameters.", "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 700 } } ], "responses": { "200": { "description": "Email preview or HEAD response", "content": { "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "Invalid, expired or unavailable link", "content": { "text/html": { "schema": { "type": "string" } } } }, "405": { "description": "Use GET or HEAD", "content": { "text/html": { "schema": { "type": "string" } } } }, "413": { "description": "Request body too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/emails/validate": { "post": { "tags": [ "Emails" ], "operationId": "validateEmail", "summary": "Check a new send without sending or reserving quota", "description": "Emailer API extension for developers and agents. Uses the same payload/template parsing and retained-storage checks as sending, with tenant domain authorization and current recipient quotas. Returns 200 with can_enqueue=false for domain/quota/storage blockers; invalid payloads remain 400. Separately reports recorded delivery configuration and current suppression count. No queue row, send-quota reservation, idempotency reservation or SMTP/network mailbox probe occurs. Authentication last-used metadata and metadata-only request logs may be written. No query parameters or Idempotency-Key are accepted. Validates new transactional sends only; broadcast consent/unsubscribe, idempotent replay, live DNS, warmup/pacing, future availability, deliverability and inbox placement are not evaluated. Conditions can change before sending; all admission/send-time checks run again. Body limit matches POST /v1/emails. HTTP 200 is a validation report, not email acceptance. Production validation also checks the operator-owned pilot approval: tenant, sender domain, all To/Cc/Bcc recipients and expiry. No policy or no matching grant blocks a new send. Admission and immediate pre-SMTP checks enforce the same restrictions. Production requires one To recipient, a reviewed immutable template version with restricted variables, and a fresh unused verified event bound to the exact tenant, recipient and rendered email. Metadata labels and customer-published templates alone do not authorize mail. Cc/Bcc, custom headers, attachments and content overrides are rejected. Marketing subscription preferences do not block required transactional mail; bounce and complaint suppressions still do.", "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendEmailRequest" }, "examples": { "verifiedCode": { "summary": "Use actual IDs from transactional setup and event verification", "value": { "to": "customer@example.com", "template": { "id": "11111111-1111-4111-8111-111111111111", "variables": { "CODE": "123456" } }, "metadata": { "event": "account.verification", "transaction_id": "22222222-2222-4222-8222-222222222222" } } } } } } }, "responses": { "200": { "description": "Point-in-time validation report; inspect checks and limitations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailValidation" } } } }, "400": { "description": "Invalid payload, query or idempotency header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid, revoked or suspended-account API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key is restricted to a different domain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Requested published template does not belong to this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Use POST.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds the send body limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected service failure; no email accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-amg-effects": { "queues_email": false, "reserves_send_quota": false, "reserves_storage": false, "reserves_idempotency_key": false, "contacts_smtp": false, "records_auth_and_request_metadata": true } } }, "/v1/transactional/status": { "get": { "operationId": "transactional_status", "tags": [ "Transactional setup" ], "summary": "Read transactional setup status", "description": "Full-access key or active dashboard session. Reports this account only; never returns application verification secrets. Supply domain_id and event together for an exact-domain launch checklist. The checklist is read-only evidence, not permission to send. No provider request, message, event authorization, quota or budget is created.", "security": [ { "apiKey": [] }, { "session": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionalStatus" } } } }, "400": { "description": "Invalid request or callback destination", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, unverified domain, unapproved content, revoked integration or expired event", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting event content or integration limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Event verification rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Application event source could not be verified", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Domain absent, deleted or owned by another account." } }, "parameters": [ { "in": "query", "name": "domain_id", "schema": { "type": "string", "format": "uuid" }, "description": "An undeleted domain owned by this account. Requires event." }, { "in": "query", "name": "event", "schema": { "$ref": "#/components/schemas/TransactionalKind" }, "description": "Transactional email type. Requires domain_id." } ] } }, "/v1/transactional/templates": { "post": { "operationId": "transactional_templates_create", "tags": [ "Transactional setup" ], "summary": "Install a fixed transactional template", "description": "Full-access key or session. Requires a verified sending domain. Repeated installation returns the existing ID only while its current published version remains catalog-approved. After an edited version is published, reinstalling creates a fresh approved catalog template and preserves the edited original. Publication of a custom template does not approve it.", "security": [ { "apiKey": [] }, { "session": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionalTemplate" } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionalTemplate" } } } }, "400": { "description": "Invalid request or callback destination", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, unverified domain, unapproved content, revoked integration or expired event", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting event content or integration limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Event verification rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Application event source could not be verified", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionalTemplateRequest" } } } } } }, "/v1/transactional/integrations": { "post": { "operationId": "transactional_integrations_create", "tags": [ "Transactional setup" ], "summary": "Register the application event callback", "description": "Full-access key or session. HTTPS callback must use the exact verified domain and resolve exclusively to public addresses. No redirects, credentials or custom ports. At most five active integrations per account. The shared secret is returned once.", "security": [ { "apiKey": [] }, { "session": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionalIntegration" } } } }, "400": { "description": "Invalid request or callback destination", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, unverified domain, unapproved content, revoked integration or expired event", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting event content or integration limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Event verification rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Application event source could not be verified", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionalIntegrationRequest" } } } } }, "get": { "operationId": "transactional_integrations_list", "tags": [ "Transactional setup" ], "summary": "List application integrations", "description": "Full-access key or active dashboard session. Shared secrets are never returned. Stable keyset pagination, newest first with UUID tie-breaker. Use the last item ID as after or the first item ID as before.", "security": [ { "apiKey": [] }, { "session": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionalIntegrationList" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or domain restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid limit or cursor, mutually exclusive cursors, or cursor outside caller scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "in": "query", "name": "after", "required": false, "description": "Next page after the last item UUID. Mutually exclusive with before; must be visible to the caller.", "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "before", "required": false, "description": "Previous page before the first item UUID. Mutually exclusive with after; must be visible to the caller.", "schema": { "type": "string", "format": "uuid" } } ] } }, "/v1/transactional/integrations/{integration_id}": { "delete": { "operationId": "transactional_integrations_remove", "tags": [ "Transactional setup" ], "summary": "Revoke an application integration and its event authorizations", "description": "Full-access key or session. Stops new admission and pre-SMTP authorization for this integration; cannot recall mail already submitted to SMTP.", "security": [ { "apiKey": [] }, { "session": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokedTransactionalIntegration" } } } }, "400": { "description": "Invalid request or callback destination", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, unverified domain, unapproved content, revoked integration or expired event", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting event content or integration limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Event verification rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Application event source could not be verified", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "in": "path", "name": "integration_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/v1/transactional/events": { "post": { "operationId": "transactional_events_create", "tags": [ "Transactional setup" ], "summary": "Verify one customer event for an exact transactional email", "description": "Sending or full-access key. Supply exactly one of integration_id (application callback) or provider_connection_id (Stripe). Payment receipts and paid-order confirmations require Stripe: a live successful positive-value payment, exact provider-record recipient and identifier, event no older than 15 minutes, plus current payment status. PAYMENT must equal the ch_ charge ID; ORDER must equal the cs_ checkout-session ID. No test transactions or free/unpaid sessions. Other event kinds use a domain-bound, nonce-signed application callback and are application attestations. Fixed reviewed template, one recipient, no arbitrary sender/body overrides. Event authorizes one exact message for up to one hour. Provider object IDs deduplicate across connection rotation. 60 verification requests/minute/account. Use the returned id in metadata.transaction_id, validate, then send using a stable idempotency key. No email is sent or send quota reserved by verification.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionalEvent" } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionalEvent" } } } }, "400": { "description": "Invalid request or callback destination", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, unverified domain, unapproved content, revoked integration or expired event", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting event content or integration limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Event verification rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Application event source could not be verified", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionalEventRequest" } } } } }, "get": { "operationId": "transactional_events_list", "tags": [ "Transactional setup" ], "summary": "List event authorizations", "description": "Any valid API key. Domain-scoped sending keys only see authorizations for their domain. Stable keyset pagination, newest first with UUID tie-breaker. Use the last item ID as after or the first item ID as before.", "security": [ { "apiKey": [] } ], "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "in": "query", "name": "after", "required": false, "description": "Next page after the last item UUID. Mutually exclusive with before; must be visible to the caller.", "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "before", "required": false, "description": "Previous page before the first item UUID. Mutually exclusive with after; must be visible to the caller.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionalEventList" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or domain restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid limit or cursor, mutually exclusive cursors, or cursor outside caller scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/auth/email/request": { "post": { "summary": "Request account owner email verification", "operationId": "post__v1_auth_email_request", "security": [ { "session": [] } ], "description": "Owner session and permitted Origin/Referer required. Verify DNS ownership first. Only the fixed account email can receive codes. Codes expire after ten minutes; at most three per day, one per minute, and five guesses per code. No verification code is returned in the response.", "responses": { "202": { "description": "Verification request result", "content": { "application/json": { "schema": { "type": "object", "properties": { "verified": { "type": "boolean" }, "expires_at": { "type": "string", "format": "date-time" } }, "required": [ "verified" ] } } } }, "400": { "description": "Invalid or expired code" }, "401": { "description": "Session required" }, "403": { "description": "Owner, domain verification or Origin required" }, "429": { "description": "Verification rate limit" }, "503": { "description": "Verification sender or delivery capacity unavailable; no customer quota charged" } } } }, "/v1/auth/email/confirm": { "post": { "summary": "Confirm account owner email", "operationId": "post__v1_auth_email_confirm", "security": [ { "session": [] } ], "description": "Owner session and permitted Origin/Referer required. Verify DNS ownership first. Only the fixed account email can receive codes. Codes expire after ten minutes; at most three per day, one per minute, and five guesses per code. No verification code is returned in the response.", "responses": { "200": { "description": "Verification request result", "content": { "application/json": { "schema": { "type": "object", "properties": { "verified": { "type": "boolean" }, "expires_at": { "type": "string", "format": "date-time" } }, "required": [ "verified" ] } } } }, "400": { "description": "Invalid or expired code" }, "401": { "description": "Session required" }, "403": { "description": "Owner, domain verification or Origin required" }, "429": { "description": "Verification rate limit" }, "503": { "description": "Verification sender or delivery capacity unavailable; no customer quota charged" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "code" ], "properties": { "code": { "type": "string", "pattern": "^[0-9]{8}$", "writeOnly": true } } } } } } } }, "/v1/transactional/providers": { "post": { "operationId": "transactional_providers_create", "tags": [ "Transactional setup" ], "summary": "Connect independent Stripe payment verification", "description": "Full-access key or session. Use a restricted rk_live key with read permission for Events, Charges and Checkout Sessions. Encrypted at rest and never returned. Only GET requests to api.stripe.com are made. Test and unrestricted secret keys are rejected. At most five active provider connections; one per verified domain. Successful connection proves API access; verified_at is set only after a live payment is checked.", "security": [ { "apiKey": [] }, { "session": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionalProvider" } } } }, "400": { "description": "Invalid request or callback destination", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, unverified domain, unapproved content, revoked integration or expired event", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting event content or integration limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Event verification rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Application event source could not be verified", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "domain_id", "provider", "restricted_key" ], "properties": { "domain_id": { "type": "string", "format": "uuid" }, "provider": { "type": "string", "enum": [ "stripe" ] }, "restricted_key": { "type": "string", "writeOnly": true, "pattern": "^rk_live_[A-Za-z0-9]{16,250}$" } } } } } } }, "get": { "operationId": "transactional_providers_list", "tags": [ "Transactional setup" ], "summary": "List provider connections", "description": "Full-access key or active dashboard session. Secrets are never returned. Stable keyset pagination, newest first with UUID tie-breaker. Use the last item ID as after or the first item ID as before.", "security": [ { "apiKey": [] }, { "session": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionalProviderList" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or domain restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid limit or cursor, mutually exclusive cursors, or cursor outside caller scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "in": "query", "name": "after", "required": false, "description": "Next page after the last item UUID. Mutually exclusive with before; must be visible to the caller.", "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "before", "required": false, "description": "Previous page before the first item UUID. Mutually exclusive with after; must be visible to the caller.", "schema": { "type": "string", "format": "uuid" } } ] } }, "/v1/transactional/providers/{provider_connection_id}": { "delete": { "operationId": "transactional_providers_remove", "tags": [ "Transactional setup" ], "summary": "Revoke a provider connection and its event authorizations", "description": "Full-access key or session. Stops new admission and pre-SMTP authorization for this integration; cannot recall mail already submitted to SMTP.", "security": [ { "apiKey": [] }, { "session": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "transactional.provider" ] }, "id": { "type": "string", "format": "uuid" }, "revoked": { "type": "boolean" } } } } } }, "400": { "description": "Invalid request or callback destination", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, unverified domain, unapproved content, revoked integration or expired event", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting event content or integration limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Event verification rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Application event source could not be verified", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "in": "path", "name": "provider_connection_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/v1/analytics/settings": { "get": { "operationId": "analytics_settings_get", "tags": [ "Analytics" ], "summary": "Read tracking settings", "security": [ { "apiKey": [] }, { "session": [] } ], "description": "Full-access key or session. Applies to future eligible deliveries. Verification, password reset and security alerts are never instrumented. Click tracking excludes query strings, fragments, non-HTTPS and foreign hosts. Tracking links expire after 30 days. No historical engagement is invented.", "responses": { "200": { "description": "Tracking settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "analytics.settings" ] }, "opens": { "type": "boolean" }, "clicks": { "type": "boolean" }, "enabled": { "type": "boolean" }, "retention_days": { "type": "integer", "enum": [ 30 ] }, "excluded_events": { "type": "array", "items": { "type": "string" } }, "sensitive_links_excluded": { "type": "boolean" } } } } } }, "400": { "description": "Invalid request or callback destination", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, unverified domain, unapproved content, revoked integration or expired event", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "analytics_settings_update", "tags": [ "Analytics" ], "summary": "Update tracking settings for future deliveries", "security": [ { "apiKey": [] }, { "session": [] } ], "description": "Full-access key or session. Applies to future eligible deliveries. Verification, password reset and security alerts are never instrumented. Click tracking excludes query strings, fragments, non-HTTPS and foreign hosts. Tracking links expire after 30 days. No historical engagement is invented.", "responses": { "200": { "description": "Tracking settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "analytics.settings" ] }, "opens": { "type": "boolean" }, "clicks": { "type": "boolean" }, "enabled": { "type": "boolean" }, "retention_days": { "type": "integer", "enum": [ 30 ] }, "excluded_events": { "type": "array", "items": { "type": "string" } }, "sensitive_links_excluded": { "type": "boolean" } } } } } }, "400": { "description": "Invalid request or callback destination", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, unverified domain, unapproved content, revoked integration or expired event", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "opens", "clicks" ], "properties": { "opens": { "type": "boolean" }, "clicks": { "type": "boolean" } } } } } } } }, "/v1/reputation": { "get": { "operationId": "getReputation", "summary": "Get customer provider coverage and dated Gmail history", "tags": [ "Reputation" ], "security": [ { "apiKey": [] }, { "session": [] } ], "description": "Requires a full-access key or dashboard session. Customer scope is enforced server-side.", "responses": { "200": { "description": "Current reporting state; absent provider measurements are unavailable." }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Owned verified domain or active hold not found" }, "429": { "description": "Setup rate limit exceeded" } }, "parameters": [ { "name": "domain_id", "in": "query", "schema": { "type": "string", "format": "uuid" } } ] } }, "/v1/reputation/domains/{id}/gmail": { "post": { "operationId": "updateGmailReporting", "summary": "Update Gmail reporting setup", "tags": [ "Reputation" ], "security": [ { "apiKey": [] }, { "session": [] } ], "description": "Requires a full-access key or dashboard session. Customer scope is enforced server-side.", "responses": { "200": { "description": "Current reporting state; absent provider measurements are unavailable." }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Owned verified domain or active hold not found" }, "429": { "description": "Setup rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "action" ], "properties": { "action": { "type": "string", "enum": [ "connect", "check", "disconnect" ] } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/v1/reputation/domains/{id}/yahoo": { "post": { "operationId": "updateYahooReporting", "summary": "Update Yahoo reporting setup", "tags": [ "Reputation" ], "security": [ { "apiKey": [] }, { "session": [] } ], "description": "Requires a full-access key or dashboard session. Customer scope is enforced server-side.", "responses": { "200": { "description": "Current reporting state; absent provider measurements are unavailable." }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Owned verified domain or active hold not found" }, "429": { "description": "Setup rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "action" ], "properties": { "action": { "type": "string", "enum": [ "connect", "check", "disconnect" ] } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/v1/operator/reputation": { "get": { "operationId": "listReputationOperations", "summary": "Review customer reporting coverage", "tags": [ "Reputation operations" ], "security": [ { "apiKey": [] }, { "session": [] } ], "description": "Requires a verified AMG owner in the server operator allowlist. Customer scope is enforced server-side.", "responses": { "200": { "description": "Current reporting state; absent provider measurements are unavailable." }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Owned verified domain or active hold not found" }, "429": { "description": "Setup rate limit exceeded" } }, "parameters": [ { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "tenant_id", "in": "query", "schema": { "type": "string", "format": "uuid" } } ] } }, "/v1/operator/reputation/domains/{id}/yahoo": { "post": { "operationId": "recordYahooEnrollment", "summary": "Record provider-confirmed Yahoo enrollment evidence", "tags": [ "Reputation operations" ], "security": [ { "apiKey": [] }, { "session": [] } ], "description": "Requires a verified AMG owner in the server operator allowlist. Customer scope is enforced server-side.", "responses": { "200": { "description": "Current reporting state; absent provider measurements are unavailable." }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Owned verified domain or active hold not found" }, "429": { "description": "Setup rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "state", "reason" ], "properties": { "state": { "type": "string", "enum": [ "pending", "dns_required", "connected", "disconnected" ] }, "verification_txt": { "type": "string" }, "reason": { "type": "string", "minLength": 20, "maxLength": 2000 } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/v1/operator/reputation/tenants/{id}/release": { "post": { "operationId": "releaseSendingReview", "summary": "Release a reviewed customer sending hold", "tags": [ "Reputation operations" ], "security": [ { "apiKey": [] }, { "session": [] } ], "description": "Requires a verified AMG owner in the server operator allowlist. Customer scope is enforced server-side.", "responses": { "200": { "description": "Current reporting state; absent provider measurements are unavailable." }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Owned verified domain or active hold not found" }, "429": { "description": "Setup rate limit exceeded" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "reason" ], "properties": { "reason": { "type": "string", "minLength": 20, "maxLength": 2000 } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/v1/transactional/catalog": { "get": { "operationId": "transactional_catalog", "tags": [ "Transactional setup" ], "summary": "Discover transactional event kinds", "description": "Public machine-readable catalog of supported transactional templates. It contains no account data or secrets.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionalCatalog" } } } } } } }, "/v1/transactional/events/{id}": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "transactional_events_get", "tags": [ "Transactional setup" ], "summary": "Inspect an event authorization", "description": "Returns the complete authorization lifecycle without revealing proof secrets. Full-access or sending-only API key; domain restrictions apply.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionalEvent" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or domain restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Malformed event UUID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Event not found or outside caller tenant/domain scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "transactional_events_revoke", "tags": [ "Transactional setup" ], "summary": "Revoke an event authorization", "description": "Any valid API key. Revokes an active, unused authorization and is idempotent for prior revocations. Full-access or sending-only API key; domain restrictions apply. Expired or consumed events are unchanged and return revoked:false. Already revoked events return revoked:true. Does not cancel queued email.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionalEvent" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or domain restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Malformed event UUID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Event not found or outside caller tenant/domain scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "Tenant-scoped API key: `Authorization: Bearer amg_live_...`. Created in the dashboard, displayed once, stored hashed, revocable." }, "session": { "type": "apiKey", "in": "cookie", "name": "amg_session", "description": "HttpOnly dashboard session. Mutating requests require an allowed Origin or Referer." }, "mtaSignature": { "type": "apiKey", "in": "header", "name": "X-AMG-Signature", "description": "Dedicated operator HMAC: t=UNIX_SECONDS,v1=HMAC_SHA256(timestamp.rawBody). Five-minute freshness window." } }, "schemas": { "SendEmailRequest": { "type": "object", "required": [ "to" ], "description": "Provide from, subject and html/text, or a published template ID/alias. Template defaults may supply from, subject and reply_to. template cannot be combined with html/text/react. Sending-only keys may send templates on their permitted verified domain.", "properties": { "from": { "type": "string", "description": "Sender address on a domain verified by this tenant. Accepts `user@domain` or `Name `.", "examples": [ "AMG " ] }, "to": { "oneOf": [ { "type": "string", "format": "email" }, { "type": "array", "description": "Recipient addresses. Each recipient consumes one unit of quota.", "items": { "type": "string", "format": "email" }, "minItems": 1, "maxItems": 50 } ] }, "subject": { "type": "string" }, "html": { "type": "string", "description": "HTML body. Required if `text` is absent." }, "text": { "type": "string", "description": "Plain-text body. Required if `html` is absent." }, "reply_to": { "oneOf": [ { "type": "string", "format": "email" }, { "type": "array", "items": { "type": "string", "format": "email" } } ] }, "cc": { "oneOf": [ { "type": "string", "format": "email" }, { "type": "array", "items": { "type": "string", "format": "email" }, "maxItems": 50 } ] }, "bcc": { "oneOf": [ { "type": "string", "format": "email" }, { "type": "array", "items": { "type": "string", "format": "email" }, "maxItems": 50 } ] }, "scheduled_at": { "type": "string", "format": "date-time", "nullable": false, "description": "ISO 8601 timezone timestamp, strictly in the future and within 30 days. Idempotent retries replay after this time." }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Custom headers, including List-Unsubscribe and List-Unsubscribe-Post. Routing, MIME and authentication headers are reserved. CR/LF are rejected." }, "tags": { "type": "array", "maxItems": 50, "items": { "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,256}$" }, "value": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,256}$" } } } }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 1000 }, "description": "AMG extension: private string metadata, 16 KB total." }, "attachments": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Body bytes plus Base64 attachment content must fit 40 MiB. HTTP request limit is 42 MiB." }, "template": { "type": "object", "required": [ "id" ], "additionalProperties": false, "properties": { "id": { "type": "string", "maxLength": 100, "description": "Published template ID or alias." }, "variables": { "type": "object", "maxProperties": 50, "additionalProperties": {}, "description": "Typed JSON values, validated against template definitions. Missing variables use declared fallbacks or fail. All values <=64 KiB, depth <=8, list length <=100." } } } }, "oneOf": [ { "required": [ "template" ], "not": { "anyOf": [ { "required": [ "html" ] }, { "required": [ "text" ] }, { "required": [ "react" ] } ] } }, { "required": [ "from", "subject" ], "anyOf": [ { "required": [ "html" ] }, { "required": [ "text" ] } ], "not": { "required": [ "template" ] } } ] }, "SendEmailResponse": { "type": "object", "required": [ "id", "status", "createdAt" ], "properties": { "id": { "type": "string", "description": "Message id for status lookups and webhook correlation." }, "status": { "type": "string", "enum": [ "queued", "dispatching", "provider_accepted", "partial", "uncertain", "delivered", "bounced", "complained", "suppressed", "failed", "canceled" ], "description": "New submissions are queued. Idempotent replay returns the current persisted status. Only authenticated delivery events establish delivered." }, "quota": { "$ref": "#/components/schemas/QuotaSnapshot" }, "createdAt": { "type": "string", "format": "date-time" }, "recipients": { "type": "integer", "minimum": 1 }, "scheduled_at": { "type": "string", "format": "date-time", "nullable": true } } }, "Email": { "type": "object", "required": [ "id", "status", "createdAt" ], "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "dispatching", "provider_accepted", "partial", "uncertain", "delivered", "bounced", "complained", "suppressed", "failed", "canceled" ], "description": "New submissions are queued. Idempotent replay returns the current persisted status. Only authenticated delivery events establish delivered." }, "from": { "type": "string" }, "to": { "type": "array", "items": { "type": "string", "format": "email" } }, "subject": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "last_event": { "type": "string", "description": "Current aggregate state. sent means SMTP provider acceptance, not inbox placement." }, "scheduled_at": { "type": "string", "format": "date-time", "nullable": true }, "tags": { "type": "array", "maxItems": 50, "items": { "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,256}$" }, "value": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,256}$" } } } }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 1000 }, "description": "AMG extension: private string metadata, 16 KB total." }, "html": { "type": "string", "nullable": true }, "text": { "type": "string", "nullable": true }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Custom headers, including List-Unsubscribe and List-Unsubscribe-Post. Routing, MIME and authentication headers are reserved. CR/LF are rejected." }, "reply_to": { "type": "array", "items": { "type": "string" } }, "template": { "type": "object", "nullable": true, "required": [ "id", "version_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "version_id": { "type": "string", "format": "uuid" } }, "description": "AMG extension: template and published version used to render the queued email; null for direct sends." } } }, "EmailSummary": { "type": "object", "description": "One message as returned by GET /v1/emails. Field names match the summary projection in services/webhooks.ts.", "required": [ "id", "status", "from", "to", "subject", "recipients", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "description": "Current persisted delivery status. Queued means accepted, not delivered." }, "from": { "type": "string" }, "to": { "type": "array", "items": { "type": "string", "format": "email" } }, "subject": { "type": "string" }, "recipients": { "type": "integer", "minimum": 1, "description": "Recipient count charged against quota for this message." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "providerMessageId": { "type": [ "string", "null" ], "description": "Identifier reported by the sending MTA once it accepts the message; null until then." }, "lastError": { "type": [ "string", "null" ], "description": "Most recent delivery error recorded for this message; null when there has been none." }, "created_at": { "type": "string", "format": "date-time" }, "last_event": { "type": "string", "description": "Current aggregate state. sent means SMTP provider acceptance, not inbox placement." }, "scheduled_at": { "type": "string", "format": "date-time", "nullable": true }, "tags": { "type": "array", "maxItems": 50, "items": { "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,256}$" }, "value": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,256}$" } } } }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 1000 }, "description": "AMG extension: private string metadata, 16 KB total." } } }, "EmailList": { "type": "object", "description": "A page of messages. Mirrors the body returned by the list handler in routes/logs.ts.", "required": [ "object", "data", "has_more" ], "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/EmailSummary" } }, "total": { "type": "integer", "minimum": 0, "description": "Total messages matching the filter for this tenant, ignoring pagination." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Effective limit after clamping." }, "offset": { "type": "integer", "minimum": 0, "description": "Effective offset after clamping." }, "has_more": { "type": "boolean", "description": "True when offset plus the returned rows is still less than total." } } }, "QuotaSnapshot": { "type": "object", "description": "Free-tier usage after this send. Free plan: 9,000/month and 300/day, counted per recipient.", "properties": { "dailyRemaining": { "type": "integer", "minimum": 0 }, "monthlyRemaining": { "type": "integer", "minimum": 0 }, "dayResetsAt": { "type": "string", "format": "date-time" }, "monthResetsAt": { "type": "string", "format": "date-time" } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable error code.", "examples": [ "unauthorized", "domain_not_verified", "quota_exceeded", "idempotency_conflict" ] }, "message": { "type": "string" }, "doc_url": { "type": "string", "format": "uri" } } } } }, "CreateApiKeyRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The API key name.", "minLength": 1, "maxLength": 120 }, "permission": { "type": "string", "enum": [ "full_access", "sending_access" ], "description": "The API key can have full access to Resend\u2019s API or be only restricted to send emails. * full_access - Can create, delete, get, and update any resource. * sending_access - Can only send emails." }, "domain_id": { "type": "string", "description": "Restrict an API key to send emails only from a specific domain. Only used when the permission is sending_access." } } }, "CreateApiKeyResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the API key." }, "token": { "type": "string", "description": "The token of the API key." } } }, "ListApiKeysResponse": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "list" }, "has_more": { "type": "boolean", "description": "Indicates if there are more results available.", "example": false }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } } } }, "ApiKey": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the API key." }, "name": { "type": "string", "description": "The name of the API key." }, "created_at": { "type": "string", "description": "The date and time the API key was created.", "example": "2023-10-06 23:47:56.678+00" }, "last_used_at": { "type": [ "string", "null" ], "description": "The date and time the API key was last used.", "example": "2023-10-06 23:47:56.678+00" }, "permission": { "type": "string", "enum": [ "full_access", "sending_access" ] }, "domain_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "UpdateApiKeyRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The API key name.", "minLength": 1, "maxLength": 120 } } }, "UpdateApiKeyResponse": { "type": "object", "properties": { "object": { "type": "string", "description": "The type of object.", "example": "api_key" }, "id": { "type": "string", "description": "The ID of the API key." } } }, "DeleteApiKeyResponse": { "type": "object", "properties": { "object": { "type": "string", "description": "The type of object.", "example": "api_key" }, "id": { "type": "string", "description": "The ID of the API key." }, "deleted": { "type": "boolean", "description": "Indicates whether the API key was successfully deleted.", "example": true } } }, "CreateSuppressionOptions": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "description": "Email address to suppress.", "example": "steve.wozniak@gmail.com" } } }, "CreateSuppressionResponseSuccess": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "suppression" }, "id": { "type": "string", "description": "Unique identifier for the created suppression.", "example": "e169aa45-1ecf-4183-9955-b1499d5701d3" } } }, "ListSuppressionsResponseSuccess": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "list" }, "has_more": { "type": "boolean", "description": "Indicates if there are more results available." }, "data": { "type": "array", "description": "Array containing suppression information.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the suppression.", "example": "e169aa45-1ecf-4183-9955-b1499d5701d3" }, "email": { "type": "string", "description": "Email address that is suppressed.", "example": "steve.wozniak@gmail.com" }, "origin": { "type": "string", "enum": [ "bounce", "complaint", "manual" ], "description": "Origin of the suppression.", "example": "manual" }, "source_id": { "type": "string", "nullable": true, "description": "Identifier of the event that caused the suppression, such as the email that bounced or complained.", "example": "479e3145-dd38-476b-932c-529ceb705947" }, "created_at": { "type": "string", "description": "Timestamp indicating when the suppression was created.", "example": "2023-10-06 23:47:56.678+00" } } } } } }, "BatchAddSuppressionsOptions": { "type": "object", "required": [ "emails" ], "properties": { "emails": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string" }, "description": "Email addresses to suppress.", "example": [ "steve.wozniak@gmail.com" ] } } }, "BatchAddSuppressionsResponseSuccess": { "type": "object", "properties": { "data": { "type": "array", "description": "Array containing the created suppressions.", "items": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the object.", "example": "suppression" }, "id": { "type": "string", "description": "Unique identifier for the suppression.", "example": "e169aa45-1ecf-4183-9955-b1499d5701d3" } } } } } }, "BatchRemoveSuppressionsOptions": { "type": "object", "description": "Provide either `emails` or `ids`, but not both.", "properties": { "emails": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string" }, "description": "Email addresses to remove from the suppression list.", "example": [ "steve.wozniak@gmail.com" ] }, "ids": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string" }, "description": "Suppression IDs to remove from the suppression list.", "example": [ "e169aa45-1ecf-4183-9955-b1499d5701d3" ] } } }, "BatchRemoveSuppressionsResponseSuccess": { "type": "object", "properties": { "data": { "type": "array", "description": "Array containing the removed suppressions.", "items": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the object.", "example": "suppression" }, "id": { "type": "string", "description": "Unique identifier for the suppression.", "example": "e169aa45-1ecf-4183-9955-b1499d5701d3" }, "deleted": { "type": "boolean", "description": "Indicates whether the suppression was successfully deleted.", "example": true } } } } } }, "GetSuppressionResponseSuccess": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "suppression" }, "id": { "type": "string", "description": "Unique identifier for the suppression.", "example": "e169aa45-1ecf-4183-9955-b1499d5701d3" }, "email": { "type": "string", "description": "Email address that is suppressed.", "example": "steve.wozniak@gmail.com" }, "origin": { "type": "string", "enum": [ "bounce", "complaint", "manual" ], "description": "Origin of the suppression.", "example": "manual" }, "source_id": { "type": "string", "nullable": true, "description": "Identifier of the event that caused the suppression, such as the email that bounced or complained.", "example": "479e3145-dd38-476b-932c-529ceb705947" }, "created_at": { "type": "string", "description": "Timestamp indicating when the suppression was created.", "example": "2023-10-06 23:47:56.678+00" } } }, "RemoveSuppressionResponseSuccess": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "suppression" }, "id": { "type": "string", "description": "Unique identifier for the removed suppression.", "example": "e169aa45-1ecf-4183-9955-b1499d5701d3" }, "deleted": { "type": "boolean", "description": "Indicates whether the suppression was successfully deleted.", "example": true } } }, "PublicKey": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "scope": { "type": "string", "enum": [ "full", "sending" ] }, "domainId": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "lastUsedAt": { "type": [ "string", "null" ] }, "revokedAt": { "type": [ "string", "null" ] } } }, "Domain": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "object": { "type": "string", "enum": [ "domain" ] }, "status": { "type": "string", "enum": [ "pending", "verified", "failed", "disabled" ] }, "records": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "TXT" ] }, "name": { "type": "string" }, "value": { "type": "string" }, "purpose": { "type": "string", "enum": [ "ownership", "spf", "dkim", "dmarc" ] } } } }, "dkimSigning": { "type": "string", "enum": [ "not_provisioned", "provisioned" ] }, "dkimSelector": { "type": [ "string", "null" ] }, "lastCheckedAt": { "type": [ "string", "null" ] }, "verifiedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "sendingReady": { "type": "boolean", "description": "Server-generated signing key and fresh ownership, SPF, exact DKIM and DMARC checks passed. Account eligibility and capacity still apply." } } }, "Webhook": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "endpoint": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] }, "createdAt": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "Attachment": { "type": "object", "required": [ "filename", "content" ], "properties": { "filename": { "type": "string", "maxLength": 255 }, "content": { "type": "string", "format": "byte", "description": "Canonical Base64 file bytes. Remote path attachments are not supported in this release." }, "content_type": { "type": "string", "default": "application/octet-stream" }, "content_id": { "type": "string", "description": "Inline Content-ID for cid: references in HTML." } } }, "RetrievedAttachment": { "type": "object", "properties": { "object": { "type": "string", "description": "The type of object.", "example": "attachment" }, "id": { "type": "string", "format": "uuid", "description": "The ID of the attachment.", "example": "660e8400-e29b-41d4-a716-446655440000" }, "filename": { "type": "string", "nullable": true, "description": "The filename of the attachment.", "example": "document.pdf" }, "content_type": { "type": "string", "description": "The MIME type of the attachment.", "example": "application/pdf" }, "content_id": { "type": "string", "description": "The content ID for inline attachments.", "example": "img001", "nullable": true }, "content_disposition": { "type": "string", "nullable": true, "enum": [ "inline", "attachment" ], "description": "How the attachment should be displayed.", "example": "attachment" }, "download_url": { "type": "string", "description": "Signed URL to download the attachment content.", "example": "https://cloudfront.example.com/path?Signature=..." }, "expires_at": { "type": "string", "format": "date-time", "description": "Timestamp when the download URL expires.", "example": "2024-10-27T18:30:00.000Z" }, "size": { "type": "integer", "description": "Size of the attachment in bytes.", "example": 2048 } } }, "ListAttachmentsResponse": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "list" }, "has_more": { "type": "boolean", "description": "Indicates if there are more results available.", "example": false }, "data": { "type": "array", "description": "Array containing attachment information.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The ID of the attachment.", "example": "660e8400-e29b-41d4-a716-446655440000" }, "filename": { "type": "string", "nullable": true, "description": "The filename of the attachment.", "example": "document.pdf" }, "content_type": { "type": "string", "description": "The MIME type of the attachment.", "example": "application/pdf" }, "content_id": { "type": "string", "description": "The content ID for inline attachments.", "example": "img001", "nullable": true }, "content_disposition": { "type": "string", "nullable": true, "enum": [ "inline", "attachment" ], "description": "How the attachment should be displayed.", "example": "attachment" }, "download_url": { "type": "string", "description": "Signed URL to download the attachment content.", "example": "https://cloudfront.example.com/path?Signature=..." }, "expires_at": { "type": "string", "format": "date-time", "description": "Timestamp when the download URL expires.", "example": "2024-10-27T18:30:00.000Z" }, "size": { "type": "integer", "description": "Size of the attachment in bytes.", "example": 2048 } } } } } }, "CreateTemplateRequest": { "type": "object", "required": [ "name", "html" ], "properties": { "name": { "type": "string", "description": "The name of the template.", "minLength": 1, "maxLength": 256 }, "alias": { "type": "string", "description": "Tenant-scoped alias; UUID-shaped aliases are reserved.", "nullable": true, "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,99}$" }, "from": { "type": "string", "description": "Sender email address. To include a friendly name, use the format \"Your Name \".", "nullable": true }, "subject": { "type": "string", "description": "Email subject.", "nullable": true }, "reply_to": { "type": "array", "items": { "type": "string" }, "description": "Reply-to email addresses.", "nullable": true }, "html": { "type": "string", "description": "The HTML version of the template." }, "text": { "type": "string", "description": "Plain text. Omitted/null generates text from the rendered HTML; empty string disables the plain-text alternative.", "nullable": true }, "variables": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateVariableInput" }, "maxItems": 50 } }, "additionalProperties": false, "description": "HTML and text are limited to 1 MiB each. Supports {{VARIABLE}} (escaped HTML), {{{VARIABLE}}} (raw), and bounded if/unless/each blocks. No helpers, partials, parent paths or executable expressions. Saved edits remain drafts until publication." }, "TemplateVariableInput": { "type": "object", "properties": { "key": { "type": "string", "description": "Unique variable key. Reserved names and prototype property names are rejected.", "pattern": "^[A-Za-z0-9_]{1,50}$" }, "type": { "type": "string", "description": "The type of the variable.", "enum": [ "string", "number", "boolean", "object", "list" ] }, "fallback_value": { "description": "Optional value matching the declared type. Strings <=2000 characters, finite numbers within the safe integer range, lists <=100 items, JSON depth <=8, all variables <=64 KiB.", "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "object" }, { "type": "array", "items": {} } ] } }, "required": [ "key", "type" ], "additionalProperties": false }, "CreateTemplateResponseSuccess": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the template." }, "object": { "type": "string", "description": "The object type of the response.", "example": "template" } } }, "ListTemplatesResponseSuccess": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "list" }, "data": { "type": "array", "description": "Array containing templates information.", "items": { "$ref": "#/components/schemas/TemplateListItem" } }, "has_more": { "type": "boolean", "description": "Indicates if there are more templates to retrieve." } } }, "TemplateListItem": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the template." }, "name": { "type": "string", "description": "The name of the template." }, "status": { "type": "string", "description": "The publication status of the template.", "enum": [ "draft", "published" ] }, "published_at": { "type": "string", "description": "Timestamp indicating when the template was published.", "example": "2023-10-06 23:47:56.678+00", "nullable": true }, "created_at": { "type": "string", "description": "Timestamp indicating when the template was created.", "example": "2023-10-06 23:47:56.678+00" }, "updated_at": { "type": "string", "description": "Timestamp indicating when the template was last updated.", "example": "2023-10-06 23:47:56.678+00" }, "alias": { "type": "string", "description": "The alias of the template.", "nullable": true } } }, "Template": { "type": "object", "properties": { "object": { "type": "string", "description": "The type of object.", "example": "template" }, "id": { "type": "string", "description": "The ID of the template." }, "current_version_id": { "type": "string", "description": "The ID of the current version of the template." }, "name": { "type": "string", "description": "The name of the template." }, "alias": { "type": "string", "description": "The alias of the template.", "nullable": true }, "from": { "type": "string", "description": "Sender email address. To include a friendly name, use the format \"Your Name \".", "nullable": true }, "subject": { "type": "string", "description": "Email subject.", "nullable": true }, "reply_to": { "type": "array", "items": { "type": "string" }, "description": "Reply-to email addresses.", "nullable": true }, "html": { "type": "string", "description": "The HTML version of the template." }, "text": { "type": "string", "description": "The plain text version of the template." }, "variables": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateVariable" } }, "created_at": { "type": "string", "description": "Timestamp indicating when the template was created.", "example": "2023-10-06 23:47:56.678+00" }, "updated_at": { "type": "string", "description": "Timestamp indicating when the template was last updated.", "example": "2023-10-06 23:47:56.678+00" }, "status": { "type": "string", "description": "The publication status of the template.", "enum": [ "draft", "published" ] }, "published_at": { "type": "string", "description": "Timestamp indicating when the template was published.", "example": "2023-10-06 23:47:56.678+00", "nullable": true }, "has_unpublished_versions": { "type": "boolean", "description": "Indicates whether the template has unpublished versions." } } }, "TemplateVariable": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the template variable." }, "key": { "type": "string", "description": "The key of the variable." }, "type": { "type": "string", "description": "The type of the variable.", "enum": [ "string", "number", "boolean", "object", "list" ] }, "fallback_value": { "description": "The fallback value of the variable.", "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "object" }, { "type": "array", "items": {} } ] }, "created_at": { "type": "string", "description": "Timestamp indicating when the variable was created.", "example": "2023-10-06 23:47:56.678+00" }, "updated_at": { "type": "string", "description": "Timestamp indicating when the variable was last updated.", "example": "2023-10-06 23:47:56.678+00" } }, "required": [ "key", "type" ] }, "UpdateTemplateOptions": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the template.", "minLength": 1, "maxLength": 256 }, "alias": { "type": "string", "description": "Tenant-scoped alias; UUID-shaped aliases are reserved.", "nullable": true, "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,99}$" }, "from": { "type": "string", "description": "Sender email address. To include a friendly name, use the format \"Your Name \".", "nullable": true }, "subject": { "type": "string", "description": "Email subject.", "nullable": true }, "reply_to": { "type": "array", "items": { "type": "string" }, "description": "Reply-to email addresses.", "nullable": true }, "html": { "type": "string", "description": "The HTML version of the template." }, "text": { "type": "string", "description": "Plain text. Omitted/null generates text from the rendered HTML; empty string disables the plain-text alternative.", "nullable": true }, "variables": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateVariableInput" }, "maxItems": 50 } }, "additionalProperties": false, "description": "HTML and text are limited to 1 MiB each. Supports {{VARIABLE}} (escaped HTML), {{{VARIABLE}}} (raw), and bounded if/unless/each blocks. No helpers, partials, parent paths or executable expressions. Saved edits remain drafts until publication.", "minProperties": 1 }, "UpdateTemplateResponseSuccess": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the template." }, "object": { "type": "string", "description": "The object type of the response.", "example": "template" } } }, "RemoveTemplateResponseSuccess": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "template" }, "id": { "type": "string", "description": "The ID of the template." }, "deleted": { "type": "boolean", "description": "Indicates whether the template was successfully deleted.", "example": true } } }, "PublishTemplateResponseSuccess": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the template." }, "object": { "type": "string", "description": "The object type of the response.", "example": "template" } } }, "DuplicateTemplateResponseSuccess": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the duplicated template." }, "object": { "type": "string", "description": "The object type of the response.", "example": "template" } } }, "CreateAudienceOptions": { "type": "object", "deprecated": true, "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256 } }, "additionalProperties": false }, "CreateAudienceResponseSuccess": { "type": "object", "deprecated": true, "properties": { "id": { "type": "string", "description": "The ID of the audience.", "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" }, "object": { "type": "string", "description": "The object of the audience.", "example": "audience" }, "name": { "type": "string", "description": "The name of the audience.", "example": "Registered Users" } } }, "ListAudiencesResponseSuccess": { "type": "object", "deprecated": true, "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "list" }, "data": { "type": "array", "description": "Array containing audience information.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the audience.", "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" }, "name": { "type": "string", "description": "Name of the audience.", "example": "Registered Users" }, "created_at": { "type": "string", "description": "Timestamp indicating when the audience was created.", "example": "2023-10-06 22:59:55.977+00" } } } } } }, "RemoveAudienceResponseSuccess": { "type": "object", "deprecated": true, "properties": { "id": { "type": "string", "description": "The ID of the audience.", "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" }, "object": { "type": "string", "description": "The object of the audience.", "example": "audience" }, "deleted": { "type": "boolean", "description": "The deleted attribute indicates that the corresponding audience has been deleted.", "example": true } } }, "GetAudienceResponseSuccess": { "type": "object", "deprecated": true, "properties": { "id": { "type": "string", "description": "The ID of the audience.", "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" }, "object": { "type": "string", "description": "The object of the audience.", "example": "audience" }, "name": { "type": "string", "description": "The name of the audience.", "example": "Registered Users" }, "created_at": { "type": "string", "description": "The date that the object was created.", "example": "2023-10-06 22:59:55.977+00" } } }, "CreateContactOptions": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "description": "Email address of the contact.", "example": "steve.wozniak@gmail.com" }, "first_name": { "type": "string", "description": "First name of the contact.", "example": "Steve", "maxLength": 256, "nullable": true }, "last_name": { "type": "string", "description": "Last name of the contact.", "example": "Wozniak", "maxLength": 256, "nullable": true }, "unsubscribed": { "type": "boolean", "description": "The Contact's global subscription status. If set to true, the contact will be unsubscribed from all Broadcasts.", "example": false }, "properties": { "type": "object", "maxProperties": 50, "additionalProperties": { "oneOf": [ { "type": "string", "maxLength": 2000, "nullable": true }, { "type": "number" }, { "type": "boolean" } ] }, "description": "Only declared property keys are accepted. null clears a value, exposing any configured fallback. Maximum request values 64 KiB." }, "segments": { "type": "array", "items": { "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "object", "required": [ "id" ], "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" } } } ] }, "description": "Array of segment IDs to add the contact to.", "maxItems": 100 }, "topics": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The topic ID." }, "subscription": { "type": "string", "enum": [ "opt_in", "opt_out" ], "description": "The subscription status for this topic." } } }, "description": "Array of topic subscriptions for the contact.", "maxItems": 100 }, "audience_id": { "type": "string", "description": "Unique identifier of the audience to which the contact belongs.", "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf", "deprecated": true } }, "additionalProperties": false }, "CreateContactResponseSuccess": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "contact" }, "id": { "type": "string", "description": "Unique identifier for the created contact.", "example": "479e3145-dd38-476b-932c-529ceb705947" } } }, "ListContactsResponseSuccess": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "list" }, "data": { "type": "array", "description": "Array containing contact information.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the contact.", "example": "e169aa45-1ecf-4183-9955-b1499d5701d3" }, "email": { "type": "string", "description": "Email address of the contact.", "example": "steve.wozniak@gmail.com" }, "first_name": { "type": "string", "description": "First name of the contact.", "example": "Steve", "nullable": true }, "last_name": { "type": "string", "description": "Last name of the contact.", "example": "Wozniak", "nullable": true }, "created_at": { "type": "string", "description": "Timestamp indicating when the contact was created.", "example": "2023-10-06 23:47:56.678+00" }, "unsubscribed": { "type": "boolean", "description": "Indicates if the contact is unsubscribed.", "example": false } } } } } }, "GetContactResponseSuccess": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "contact" }, "id": { "type": "string", "description": "Unique identifier for the contact.", "example": "e169aa45-1ecf-4183-9955-b1499d5701d3" }, "email": { "type": "string", "description": "Email address of the contact.", "example": "steve.wozniak@gmail.com" }, "first_name": { "type": "string", "description": "First name of the contact.", "example": "Steve", "nullable": true }, "last_name": { "type": "string", "description": "Last name of the contact.", "example": "Wozniak", "nullable": true }, "created_at": { "type": "string", "description": "Timestamp indicating when the contact was created.", "example": "2023-10-06 23:47:56.678+00" }, "unsubscribed": { "type": "boolean", "description": "Indicates if the contact is unsubscribed.", "example": false }, "properties": { "type": "object", "additionalProperties": true, "description": "A map of custom property keys and values." } } }, "UpdateContactOptions": { "type": "object", "properties": { "first_name": { "type": "string", "description": "First name of the contact.", "example": "Steve", "maxLength": 256, "nullable": true }, "last_name": { "type": "string", "description": "Last name of the contact.", "example": "Wozniak", "maxLength": 256, "nullable": true }, "unsubscribed": { "type": "boolean", "description": "The Contact's global subscription status. If set to true, the contact will be unsubscribed from all Broadcasts.", "example": false }, "properties": { "type": "object", "maxProperties": 50, "additionalProperties": { "oneOf": [ { "type": "string", "maxLength": 2000, "nullable": true }, { "type": "number" }, { "type": "boolean" } ] }, "description": "Only declared property keys are accepted. null clears a value, exposing any configured fallback. Maximum request values 64 KiB." } }, "additionalProperties": false, "minProperties": 1 }, "UpdateContactResponseSuccess": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "contact" }, "id": { "type": "string", "description": "Unique identifier for the updated contact.", "example": "479e3145-dd38-476b-932c-529ceb705947" } } }, "RemoveContactResponseSuccess": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "contact" }, "id": { "type": "string", "description": "Unique identifier for the removed contact.", "example": "520784e2-887d-4c25-b53c-4ad46ad38100" }, "deleted": { "type": "boolean", "description": "Indicates whether the contact was successfully deleted.", "example": true } } }, "CreateSegmentOptions": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256 } }, "additionalProperties": false }, "CreateSegmentResponseSuccess": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the segment.", "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" }, "object": { "type": "string", "description": "The object type of the response.", "example": "segment" } } }, "ListSegmentsResponseSuccess": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "list" }, "has_more": { "type": "boolean", "description": "Indicates if there are more results available." }, "data": { "type": "array", "description": "Array containing segment information.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the segment." }, "name": { "type": "string", "description": "Name of the segment." }, "audience_id": { "type": "string", "description": "The ID of the audience this segment belongs to.", "deprecated": true }, "created_at": { "type": "string", "description": "Timestamp indicating when the segment was created.", "example": "2023-10-06 23:47:56.678+00" } } } } } }, "GetSegmentResponseSuccess": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the segment.", "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" }, "object": { "type": "string", "description": "The object type.", "example": "segment" }, "name": { "type": "string", "description": "The name of the segment.", "example": "Active Users" }, "audience_id": { "type": "string", "description": "The ID of the audience this segment belongs to.", "deprecated": true }, "filter": { "type": "object", "description": "Filter conditions for the segment." }, "created_at": { "type": "string", "description": "Timestamp indicating when the segment was created.", "example": "2023-10-06 23:47:56.678+00" } } }, "UpdateSegmentOptions": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256 } }, "additionalProperties": false, "minProperties": 1 }, "UpdateSegmentResponseSuccess": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the segment.", "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" }, "object": { "type": "string", "description": "The object type.", "example": "segment" } } }, "RemoveSegmentResponseSuccess": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the segment.", "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" }, "object": { "type": "string", "description": "The object type.", "example": "segment" }, "deleted": { "type": "boolean", "description": "Indicates whether the segment was successfully deleted.", "example": true } } }, "CreateTopicOptions": { "type": "object", "required": [ "name", "default_subscription" ], "properties": { "name": { "type": "string", "description": "The name of the topic. Max 50 characters.", "maxLength": 50, "minLength": 1 }, "default_subscription": { "type": "string", "enum": [ "opt_in", "opt_out" ], "description": "The default subscription status for the topic. Cannot be changed after creation." }, "description": { "type": "string", "description": "A description of the topic. Max 200 characters.", "maxLength": 200 }, "visibility": { "type": "string", "enum": [ "public", "private" ], "default": "private", "description": "The visibility of the topic. Public topics are visible to all contacts on the unsubscribe page. Private topics are only visible to opted-in contacts." } }, "additionalProperties": false }, "CreateTopicResponseSuccess": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the topic.", "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" }, "object": { "type": "string", "description": "The object type of the response.", "example": "topic" } } }, "ListTopicsResponseSuccess": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "list" }, "has_more": { "type": "boolean", "description": "Indicates if there are more results available." }, "data": { "type": "array", "description": "Array containing topic information.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the topic." }, "name": { "type": "string", "description": "Name of the topic." }, "description": { "type": "string", "description": "A description of the topic." }, "default_subscription": { "type": "string", "enum": [ "opt_in", "opt_out" ], "description": "The default subscription status for the topic." }, "visibility": { "type": "string", "enum": [ "public", "private" ], "description": "The visibility of the topic." }, "created_at": { "type": "string", "description": "Timestamp indicating when the topic was created.", "example": "2023-10-06 23:47:56.678+00" } } } } } }, "GetTopicResponseSuccess": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the topic.", "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" }, "object": { "type": "string", "description": "The object type.", "example": "topic" }, "name": { "type": "string", "description": "The name of the topic.", "example": "Newsletter" }, "description": { "type": "string", "description": "A description of the topic." }, "default_subscription": { "type": "string", "enum": [ "opt_in", "opt_out" ], "description": "The default subscription status for the topic." }, "visibility": { "type": "string", "enum": [ "public", "private" ], "description": "The visibility of the topic." }, "created_at": { "type": "string", "description": "Timestamp indicating when the topic was created.", "example": "2023-10-06 23:47:56.678+00" } } }, "UpdateTopicOptions": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the topic. Max 50 characters.", "maxLength": 50, "minLength": 1 }, "description": { "type": "string", "description": "A description of the topic. Max 200 characters.", "maxLength": 200 }, "visibility": { "type": "string", "enum": [ "public", "private" ], "description": "The visibility of the topic." } }, "additionalProperties": false, "minProperties": 1 }, "UpdateTopicResponseSuccess": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the topic.", "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" }, "object": { "type": "string", "description": "The object type.", "example": "topic" } } }, "RemoveTopicResponseSuccess": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the topic.", "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" }, "object": { "type": "string", "description": "The object type.", "example": "topic" }, "deleted": { "type": "boolean", "description": "Indicates whether the topic was successfully deleted.", "example": true } } }, "CreateContactPropertyOptions": { "type": "object", "required": [ "key", "type" ], "properties": { "key": { "type": "string", "description": "The property key. Max length is 50 characters. Only alphanumeric characters and underscores are allowed." }, "type": { "type": "string", "enum": [ "string", "number", "boolean" ], "description": "The property type." }, "fallback_value": { "oneOf": [ { "type": "string", "maxLength": 2000, "nullable": true }, { "type": "number" }, { "type": "boolean" } ], "description": "Must match immutable property type; null clears the fallback." } }, "additionalProperties": false }, "CreateContactPropertyResponseSuccess": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the contact property.", "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" }, "object": { "type": "string", "description": "The object type of the response.", "example": "contact_property" } } }, "ListContactPropertiesResponseSuccess": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "list" }, "has_more": { "type": "boolean", "description": "Indicates if there are more results available." }, "data": { "type": "array", "description": "Array containing contact property information.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the contact property." }, "key": { "type": "string", "description": "The property key." }, "type": { "type": "string", "description": "The property type." }, "fallback_value": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ], "description": "The default value when the property is not set for a contact." }, "created_at": { "type": "string", "description": "Timestamp indicating when the contact property was created.", "example": "2023-10-06 23:47:56.678+00" } } } } } }, "GetContactPropertyResponseSuccess": { "type": "object", "properties": { "object": { "type": "string", "description": "The object type.", "example": "contact_property" }, "id": { "type": "string", "description": "The ID of the contact property.", "example": "b6d24b8e-af0b-4c3c-be0c-359bbd97381e" }, "key": { "type": "string", "description": "The property key.", "example": "company_name" }, "type": { "type": "string", "description": "The property type.", "example": "string" }, "fallback_value": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ], "description": "The default value when the property is not set for a contact.", "example": "Acme Corp" }, "created_at": { "type": "string", "description": "Timestamp indicating when the contact property was created.", "example": "2023-10-06 23:47:56.678+00" } } }, "UpdateContactPropertyOptions": { "type": "object", "properties": { "fallback_value": { "oneOf": [ { "type": "string", "maxLength": 2000, "nullable": true }, { "type": "number" }, { "type": "boolean" } ], "description": "Must match immutable property type; null clears the fallback." } }, "additionalProperties": false, "minProperties": 1 }, "UpdateContactPropertyResponseSuccess": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the contact property.", "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" }, "object": { "type": "string", "description": "The object type.", "example": "contact_property" } } }, "RemoveContactPropertyResponseSuccess": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the contact property.", "example": "78261eea-8f8b-4381-83c6-79fa7120f1cf" }, "object": { "type": "string", "description": "The object type.", "example": "contact_property" }, "deleted": { "type": "boolean", "description": "Indicates whether the contact property was successfully deleted.", "example": true } } }, "ListContactSegmentsResponseSuccess": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "list" }, "has_more": { "type": "boolean", "description": "Indicates if there are more results available." }, "data": { "type": "array", "description": "Array containing segment information for this contact.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the segment." }, "name": { "type": "string", "description": "Name of the segment." }, "created_at": { "type": "string", "description": "Timestamp indicating when the contact was added to the segment.", "example": "2023-10-06 23:47:56.678+00" } } } } } }, "AddContactToSegmentResponseSuccess": { "type": "object", "properties": { "object": { "type": "string", "description": "The object type.", "example": "contact_segment" }, "contact_id": { "type": "string", "description": "The ID of the contact." }, "segment_id": { "type": "string", "description": "The ID of the segment." } } }, "RemoveContactFromSegmentResponseSuccess": { "type": "object", "properties": { "object": { "type": "string", "description": "The object type.", "example": "contact_segment" }, "contact_id": { "type": "string", "description": "The ID of the contact." }, "segment_id": { "type": "string", "description": "The ID of the segment." }, "deleted": { "type": "boolean", "description": "Indicates whether the contact was successfully removed from the segment.", "example": true } } }, "GetContactTopicsResponseSuccess": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of the response object.", "example": "list" }, "has_more": { "type": "boolean", "description": "Indicates if there are more results available." }, "data": { "type": "array", "description": "Array containing topic subscriptions for this contact.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the topic." }, "name": { "type": "string", "description": "Name of the topic." }, "description": { "type": "string", "description": "Description of the topic." }, "subscription": { "type": "string", "enum": [ "opt_in", "opt_out" ], "description": "The subscription status for this topic." } } } } } }, "UpdateContactTopicsOptions": { "type": "object", "required": [ "topics" ], "properties": { "topics": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the topic." }, "subscription": { "type": "string", "enum": [ "opt_in", "opt_out" ], "description": "The subscription status (opt_in or opt_out)." } } } } } }, "UpdateContactTopicsResponseSuccess": { "type": "object", "properties": { "object": { "type": "string", "description": "The object type.", "example": "contact_topics" }, "contact_id": { "type": "string", "description": "The ID of the contact." }, "topics": { "type": "array", "description": "Array of updated topic subscriptions.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the topic." }, "subscription": { "type": "string", "enum": [ "opt_in", "opt_out" ], "description": "The subscription status." } } } } } }, "CreateBroadcastRequest": { "type": "object", "properties": { "segment_id": { "type": "string", "format": "uuid" }, "audience_id": { "type": "string", "format": "uuid", "description": "Deprecated alias for segment_id." }, "topic_id": { "type": [ "string", "null" ], "format": "uuid" }, "name": { "type": "string", "maxLength": 256 }, "from": { "type": "string", "maxLength": 998 }, "subject": { "type": "string", "maxLength": 998 }, "html": { "type": [ "string", "null" ], "description": "Up to 1 MiB. Contact substitutions are HTML escaped, including triple-brace syntax." }, "text": { "type": [ "string", "null" ], "description": "Up to 1 MiB. Omitted/null generates text from HTML; empty string disables it." }, "reply_to": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "send": { "type": "boolean", "default": false }, "scheduled_at": { "type": "string", "format": "date-time", "description": "ISO timestamp, future and within 30 days. Requires send=true." } }, "required": [ "segment_id", "from", "subject" ], "additionalProperties": false }, "UpdateBroadcastRequest": { "type": "object", "properties": { "segment_id": { "type": "string", "format": "uuid" }, "audience_id": { "type": "string", "format": "uuid", "description": "Deprecated alias for segment_id." }, "topic_id": { "type": [ "string", "null" ], "format": "uuid" }, "name": { "type": "string", "maxLength": 256 }, "from": { "type": "string", "maxLength": 998 }, "subject": { "type": "string", "maxLength": 998 }, "html": { "type": [ "string", "null" ], "description": "Up to 1 MiB. Contact substitutions are HTML escaped, including triple-brace syntax." }, "text": { "type": [ "string", "null" ], "description": "Up to 1 MiB. Omitted/null generates text from HTML; empty string disables it." }, "reply_to": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } }, "required": [], "additionalProperties": false, "minProperties": 1 }, "Broadcast": { "type": "object", "properties": { "object": { "const": "broadcast" }, "id": { "type": "string", "format": "uuid" }, "segment_id": { "type": "string", "format": "uuid" }, "audience_id": { "type": "string", "format": "uuid", "description": "Deprecated alias for segment_id." }, "topic_id": { "type": [ "string", "null" ], "format": "uuid" }, "name": { "type": "string", "maxLength": 256 }, "from": { "type": "string", "maxLength": 998 }, "subject": { "type": "string", "maxLength": 998 }, "html": { "type": [ "string", "null" ], "description": "Up to 1 MiB. Contact substitutions are HTML escaped, including triple-brace syntax." }, "text": { "type": [ "string", "null" ], "description": "Up to 1 MiB. Omitted/null generates text from HTML; empty string disables it." }, "reply_to": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "status": { "type": "string", "enum": [ "draft", "queued", "scheduled", "canceled", "sent", "partial", "suppressed", "failed" ] }, "scheduled_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "submitted_at": { "type": [ "string", "null" ], "format": "date-time" }, "sent_at": { "type": "null", "description": "Destination transmission completion timestamp is not measured." }, "recipient_count": { "type": "integer", "minimum": 0 }, "recipient_states": { "type": "object", "additionalProperties": { "type": "integer" } }, "unavailable_metrics": { "type": "array", "items": { "type": "string" } }, "delivery_semantics": { "type": "string" } }, "required": [ "id", "object", "segment_id", "topic_id", "name", "from", "subject", "html", "text", "reply_to", "status", "scheduled_at", "created_at", "updated_at", "submitted_at", "sent_at", "recipient_count", "recipient_states", "unavailable_metrics", "delivery_semantics" ] }, "BroadcastRecipient": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "contact_id": { "type": [ "string", "null" ], "format": "uuid" }, "email": { "type": "string", "format": "email" }, "bounce_type": { "type": "null", "description": "Classification not measured." } }, "required": [ "id", "contact_id", "email" ] }, "ContactImport": { "type": "object", "properties": { "object": { "const": "contact_import" }, "id": { "type": "string", "format": "uuid" }, "filename": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "in_progress", "completed", "failed" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "blocked_reason": { "type": [ "string", "null" ] }, "counts": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0 }, "created": { "type": "integer", "minimum": 0 }, "updated": { "type": "integer", "minimum": 0 }, "skipped": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "total", "created", "updated", "skipped", "failed" ] }, "errors": { "type": "array", "maxItems": 100, "items": { "type": "object", "properties": { "row_number": { "type": "integer", "minimum": 2 }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "row_number", "code", "message" ] } }, "errors_truncated": { "type": "boolean" } }, "required": [ "object", "id", "filename", "status", "created_at", "updated_at", "completed_at", "blocked_reason", "counts", "errors", "errors_truncated" ] }, "CreateContactImportRequest": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "UTF-8 CSV with header, at most 5 MiB and 10000 data rows. Multipart body at most 6 MiB." }, "column_map": { "type": "string", "description": "JSON object mapping email/first_name/last_name/unsubscribed to exact header names; properties maps keys to {column,type}. Types: string/number/boolean. Missing property definitions are created; existing types must match. Omitted mapping auto-detects standard case-insensitive header names. With a partial mapping, omitted email is detected; other standard fields require explicit mappings. Ambiguous inferred headers require an explicit choice for new imports. Existing valid 24-hour idempotency receipts preserve legacy inference." }, "segments": { "type": "string", "description": "JSON array of segment IDs or {id} objects." }, "topics": { "type": "string", "description": "JSON array of {id,subscription:opt_in|opt_out}." }, "on_conflict": { "type": "string", "enum": [ "upsert", "skip" ], "default": "upsert" } }, "required": [ "file" ], "additionalProperties": false }, "WebhookEventSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "pending", "attempting", "success", "failed" ] } }, "required": [ "id", "type", "created_at", "status" ] }, "WebhookEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "pending", "attempting", "success", "failed" ] }, "object": { "const": "webhook_event" }, "payload": { "type": "object" }, "next_attempt_at": { "type": [ "string", "null" ], "format": "date-time" }, "attempt_count": { "type": "integer", "minimum": 0 }, "recorded_attempt_count": { "type": "integer", "minimum": 0 }, "history_complete": { "type": "boolean" }, "history_started_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "type", "created_at", "status", "object", "payload", "next_attempt_at", "attempt_count", "recorded_attempt_count", "history_complete", "history_started_at" ] }, "WebhookAttempt": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "http_status_code": { "type": [ "integer", "null" ], "minimum": 100, "maximum": 599 }, "response": { "type": "null", "description": "Endpoint response bodies are not retained." }, "response_redacted": { "const": true }, "sent_at": { "type": "string", "format": "date-time", "description": "Durable attempt start, before endpoint resolution and HTTP. Does not prove the endpoint received it." }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" }, "number": { "type": "integer", "minimum": 1 }, "outcome": { "type": "string", "enum": [ "in_progress", "success", "failed", "unknown" ] } }, "required": [ "id", "http_status_code", "response", "response_redacted", "sent_at", "finished_at", "number", "outcome" ] }, "ApiRequestLogSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "api_key_id": { "type": [ "string", "null" ], "format": "uuid" }, "auth_kind": { "enum": [ "key", "session" ] }, "method": { "type": "string" }, "endpoint": { "type": "string", "description": "Trusted route template; actual path parameters and query strings are not retained." }, "endpoint_is_template": { "const": true }, "response_status": { "type": [ "integer", "null" ] }, "duration_ms": { "type": "integer", "minimum": 0 }, "response_completed": { "type": "boolean", "description": "Whether the HTTP response had completed at capture; not a delivery or client receipt guarantee." }, "created_at": { "type": "string", "format": "date-time" }, "user_agent": { "type": "null" } }, "required": [ "id", "api_key_id", "auth_kind", "method", "endpoint", "endpoint_is_template", "response_status", "duration_ms", "response_completed", "created_at", "user_agent" ] }, "ApiRequestLog": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "api_key_id": { "type": [ "string", "null" ], "format": "uuid" }, "auth_kind": { "enum": [ "key", "session" ] }, "method": { "type": "string" }, "endpoint": { "type": "string", "description": "Trusted route template; actual path parameters and query strings are not retained." }, "endpoint_is_template": { "const": true }, "response_status": { "type": [ "integer", "null" ] }, "duration_ms": { "type": "integer", "minimum": 0 }, "response_completed": { "type": "boolean", "description": "Whether the HTTP response had completed at capture; not a delivery or client receipt guarantee." }, "created_at": { "type": "string", "format": "date-time" }, "user_agent": { "type": "null" }, "object": { "const": "log" }, "request_body": { "type": "null" }, "response_body": { "type": "null" }, "redacted_fields": { "type": "array", "items": { "type": "string" } }, "coverage": { "type": "object", "properties": { "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "max_age_days": { "const": 7 }, "global_max_records": { "const": 100000 }, "guaranteed_complete": { "const": false } }, "required": [ "started_at", "max_age_days", "global_max_records", "guaranteed_complete" ] } }, "required": [ "id", "api_key_id", "auth_kind", "method", "endpoint", "endpoint_is_template", "response_status", "duration_ms", "response_completed", "created_at", "user_agent", "object", "request_body", "response_body", "redacted_fields", "coverage" ] }, "ApiRequestLogCoverage": { "type": "object", "properties": { "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "max_age_days": { "const": 7 }, "global_max_records": { "const": 100000 }, "guaranteed_complete": { "const": false } }, "required": [ "started_at", "max_age_days", "global_max_records", "guaranteed_complete" ] }, "Usage": { "type": "object", "properties": { "object": { "const": "usage" }, "generated_at": { "type": "string", "format": "date-time" }, "emails": { "type": "object", "properties": { "daily": { "type": "object", "properties": { "used": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "minimum": 0 }, "sent": { "type": "null" }, "received": { "type": "null" }, "outgoing_reserved": { "type": "integer", "minimum": 0 }, "remaining": { "type": "integer", "minimum": 0 }, "resets_at": { "type": "string", "format": "date-time" }, "window": { "const": "calendar_day_utc" } }, "required": [ "used", "limit", "sent", "received", "outgoing_reserved", "remaining", "resets_at", "window" ], "additionalProperties": false }, "monthly": { "type": "object", "properties": { "used": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "minimum": 0 }, "sent": { "type": "null" }, "received": { "type": "null" }, "outgoing_reserved": { "type": "integer", "minimum": 0 }, "remaining": { "type": "integer", "minimum": 0 }, "resets_at": { "type": "string", "format": "date-time" }, "window": { "const": "calendar_month_utc" } }, "required": [ "used", "limit", "sent", "received", "outgoing_reserved", "remaining", "resets_at", "window" ], "additionalProperties": false }, "measurement_unit": { "const": "reserved_outbound_recipient" } }, "required": [ "daily", "monthly", "measurement_unit" ], "additionalProperties": false }, "contacts": { "type": "object", "properties": { "used": { "type": "integer", "minimum": 0 }, "limit": { "type": "null" } }, "required": [ "used", "limit" ], "additionalProperties": false }, "segments": { "type": "object", "properties": { "used": { "type": "integer", "minimum": 0 }, "limit": { "type": "null" } }, "required": [ "used", "limit" ], "additionalProperties": false }, "broadcasts": { "type": "object", "properties": { "used": { "type": "integer", "minimum": 0 }, "limit": { "type": "null" } }, "required": [ "used", "limit" ], "additionalProperties": false }, "domains": { "type": "object", "properties": { "used": { "type": "integer", "minimum": 0 }, "limit": { "type": "null" } }, "required": [ "used", "limit" ], "additionalProperties": false }, "ai_credits": { "type": "object", "properties": { "used": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "minimum": 0 }, "remaining": { "type": "integer", "minimum": 0 }, "next_increase_at": { "type": [ "string", "null" ], "format": "date-time" }, "resets_at": { "type": "string", "format": "date-time" }, "window": { "const": "calendar_month_utc" }, "bucket": { "type": "string", "pattern": "^\\d{4}-\\d{2}$" }, "measurement_unit": { "const": "provider_call" } }, "required": [ "used", "limit", "remaining", "next_increase_at", "resets_at", "window", "bucket", "measurement_unit" ], "additionalProperties": false }, "automation_runs": { "type": "object", "properties": { "used": { "type": "null" }, "limit": { "type": "null" }, "resets_at": { "type": "null" } }, "required": [ "used", "limit", "resets_at" ], "additionalProperties": false }, "rate_limit": { "type": "object", "properties": { "limit": { "type": "null" }, "duration": { "type": "null" } }, "required": [ "limit", "duration" ], "additionalProperties": false }, "storage": { "type": "object", "properties": { "retained_email_bytes": { "type": "integer", "minimum": 0 }, "tenant_limit_bytes": { "type": "integer", "minimum": 0 }, "remaining_bytes": { "type": "integer", "minimum": 0 }, "measurement": { "const": "logical_payload_bytes" }, "includes_all_delivery_states": { "const": true } }, "required": [ "retained_email_bytes", "tenant_limit_bytes", "remaining_bytes", "measurement", "includes_all_delivery_states" ], "additionalProperties": false }, "unavailable": { "type": "array", "items": { "type": "string" } }, "notes": { "type": "array", "items": { "type": "string" } } }, "required": [ "object", "generated_at", "emails", "contacts", "segments", "broadcasts", "domains", "ai_credits", "automation_runs", "rate_limit", "storage", "unavailable", "notes" ], "additionalProperties": false }, "SharedEmail": { "type": "object", "required": [ "object", "id", "url" ], "properties": { "object": { "const": "email" }, "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "EmailValidationCheck": { "type": "object", "required": [ "name", "status", "code", "message" ], "properties": { "name": { "type": "string" }, "status": { "type": "string", "enum": [ "passed", "blocked", "warning" ] }, "code": { "type": "string" }, "message": { "type": "string" } } }, "ValidationQuotaSnapshot": { "type": "object", "description": "Free-tier usage after this send. Free plan: 9,000/month and 300/day, counted per recipient.", "properties": { "dailyRemaining": { "type": "integer", "minimum": 0 }, "monthlyRemaining": { "type": "integer", "minimum": 0 }, "dayResetsAt": { "type": "string", "format": "date-time" }, "monthResetsAt": { "type": "string", "format": "date-time" }, "dailyUsed": { "type": "integer", "minimum": 0 }, "monthlyUsed": { "type": "integer", "minimum": 0 } }, "required": [ "dailyRemaining", "monthlyRemaining", "dayResetsAt", "monthResetsAt", "dailyUsed", "monthlyUsed" ] }, "EmailValidation": { "type": "object", "required": [ "object", "checked_at", "dry_run", "can_enqueue", "checks", "recipients", "payload_storage_bytes", "quota", "delivery", "limitations" ], "properties": { "object": { "type": "string", "enum": [ "email.validation" ] }, "checked_at": { "type": "string", "format": "date-time" }, "dry_run": { "type": "boolean", "enum": [ true ] }, "can_enqueue": { "type": "boolean", "description": "Current new-send payload, domain, quota and storage checks pass. Not an acceptance receipt, reservation or delivery guarantee." }, "checks": { "type": "array", "items": { "$ref": "#/components/schemas/EmailValidationCheck" } }, "recipients": { "type": "integer", "minimum": 1 }, "payload_storage_bytes": { "type": "integer", "minimum": 0 }, "quota": { "$ref": "#/components/schemas/ValidationQuotaSnapshot" }, "delivery": { "type": "object", "required": [ "configuration_ready", "suppressed_recipients", "checks" ], "properties": { "configuration_ready": { "type": "boolean", "description": "Recorded app pool and domain signing configuration only. No network verification, warmup budget or pacing prediction." }, "suppressed_recipients": { "type": "integer", "minimum": 0 }, "checks": { "type": "array", "items": { "$ref": "#/components/schemas/EmailValidationCheck" } } } }, "limitations": { "type": "array", "items": { "type": "string" } } } }, "TransactionalKind": { "type": "string", "enum": [ "account.verification", "password.reset", "security.alert", "order.confirmed", "payment.receipt", "appointment.confirmed" ] }, "TransactionalTemplateRequest": { "type": "object", "properties": { "domain_id": { "type": "string", "format": "uuid" }, "kind": { "$ref": "#/components/schemas/TransactionalKind" } }, "required": [ "domain_id", "kind" ], "additionalProperties": false }, "TransactionalTemplate": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "transactional.template" ] }, "id": { "type": "string", "format": "uuid" }, "version_id": { "type": "string", "format": "uuid" }, "event": { "$ref": "#/components/schemas/TransactionalKind" }, "variables": { "type": "object", "additionalProperties": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "code", "identifier", "number", "date", "url" ] }, "host": { "type": "string" } }, "required": [ "kind" ], "additionalProperties": false } } }, "required": [ "object", "id", "version_id", "event", "variables" ], "additionalProperties": false }, "TransactionalIntegrationRequest": { "type": "object", "properties": { "domain_id": { "type": "string", "format": "uuid" }, "callback_url": { "type": "string", "format": "uri", "maxLength": 2000 } }, "required": [ "domain_id", "callback_url" ], "additionalProperties": false }, "TransactionalIntegration": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "transactional.integration" ] }, "id": { "type": "string", "format": "uuid" }, "shared_secret": { "type": "string", "description": "One-time secret. Store only in the application secret manager." }, "status": { "type": "string", "enum": [ "awaiting_first_verified_event" ] } }, "required": [ "object", "id", "shared_secret", "status" ], "additionalProperties": false }, "TransactionalEventRequest": { "type": "object", "properties": { "integration_id": { "type": "string", "format": "uuid" }, "event_id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,100}$" }, "event": { "$ref": "#/components/schemas/TransactionalKind" }, "email": { "$ref": "#/components/schemas/SendEmailRequest" }, "provider_connection_id": { "type": "string", "format": "uuid" } }, "required": [ "event_id", "event", "email" ], "additionalProperties": false, "oneOf": [ { "required": [ "integration_id" ], "not": { "required": [ "provider_connection_id" ] } }, { "required": [ "provider_connection_id" ], "not": { "required": [ "integration_id" ] } } ] }, "TransactionalEvent": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "transactional.event" ] }, "id": { "type": "string", "format": "uuid" }, "event": { "$ref": "#/components/schemas/TransactionalKind" }, "expires_at": { "type": "string", "format": "date-time" }, "evidence": { "type": "string", "enum": [ "application_attested", "stripe_verified" ], "description": "Returned by event creation/replay when available; omitted from read/list responses." }, "recipient": { "type": "string", "format": "email" }, "source": { "type": "string", "enum": [ "stripe", "verified_application", "account_verification", "commissioning" ] }, "template_id": { "type": "string", "format": "uuid" }, "version_id": { "type": "string", "format": "uuid" }, "occurred_at": { "type": "string", "format": "date-time" }, "verified_at": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "active", "expired", "consumed", "revoked" ] }, "consumed_message_id": { "type": "string", "format": "uuid", "nullable": true }, "revoked": { "type": "boolean" } }, "required": [ "object", "id", "event", "expires_at", "status" ], "additionalProperties": false }, "TransactionalStatus": { "type": "object", "required": [ "object", "email_verified", "domains", "integrations", "templates", "catalog", "evidence" ], "properties": { "object": { "type": "string", "enum": [ "transactional.status" ] }, "email_verified": { "type": "boolean" }, "domains": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "status": { "type": "string" }, "sending_ready": { "type": "boolean" } }, "required": [ "id", "name", "status" ], "additionalProperties": false } }, "integrations": { "type": "array", "items": { "type": "object", "description": "id, domain_id, callback_url, verified_at and revoked_at. No secret is returned." } }, "templates": { "type": "array", "items": { "type": "object", "description": "template_id, version_id, event_type, name, revoked_at, approved_from and current_version. Approved sender and publication state scope the setup display." } }, "catalog": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionalKind" } }, "evidence": { "type": "string" }, "sending_access": { "type": "object", "properties": { "status": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } }, "providers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "domain_id": { "type": "string", "format": "uuid" }, "provider": { "type": "string", "enum": [ "stripe" ] }, "verified_at": { "type": "string", "format": "date-time", "nullable": true }, "revoked_at": { "type": "string", "format": "date-time", "nullable": true } } } }, "checklist": { "anyOf": [ { "$ref": "#/components/schemas/OnboardingChecklist" }, { "type": "null" } ] } } }, "RevokedTransactionalIntegration": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "transactional.integration" ] }, "id": { "type": "string", "format": "uuid" }, "revoked": { "type": "boolean", "enum": [ true ] } }, "required": [ "object", "id", "revoked" ], "additionalProperties": false }, "TransactionalProvider": { "type": "object", "required": [ "object", "id", "provider", "status" ], "properties": { "object": { "type": "string", "enum": [ "transactional.provider" ] }, "id": { "type": "string", "format": "uuid" }, "provider": { "type": "string", "enum": [ "stripe" ] }, "status": { "type": "string", "enum": [ "awaiting_first_verified_payment" ] } } }, "OnboardingStep": { "type": "object", "additionalProperties": false, "required": [ "id", "label", "state", "detail", "href" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "state": { "type": "string", "enum": [ "complete", "pending", "blocked", "unavailable" ] }, "detail": { "type": "string" }, "href": { "type": "string" } } }, "OnboardingChecklist": { "type": "object", "additionalProperties": false, "required": [ "domain_id", "domain", "event", "checked_at", "configuration_complete", "next_step", "steps", "reporting", "delivery", "service", "gmail_measurement_state", "note" ], "properties": { "domain_id": { "type": "string", "format": "uuid" }, "domain": { "type": "string" }, "event": { "$ref": "#/components/schemas/TransactionalKind" }, "checked_at": { "type": "string", "format": "date-time" }, "configuration_complete": { "type": "boolean", "description": "Current account, identity, domain, signing, template, verifier connection and scoped key configuration. Not a send authorization or capacity reservation." }, "next_step": { "anyOf": [ { "$ref": "#/components/schemas/OnboardingStep" }, { "type": "null" } ] }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/OnboardingStep" } }, "reporting": { "type": "array", "items": { "$ref": "#/components/schemas/OnboardingStep" } }, "delivery": { "type": "array", "items": { "$ref": "#/components/schemas/OnboardingStep" } }, "service": { "type": "object", "required": [ "ready", "reason" ], "properties": { "ready": { "type": "boolean" }, "reason": { "type": "string" } } }, "gmail_measurement_state": { "type": "string" }, "note": { "type": "string" } } }, "TransactionalCatalogEntry": { "type": "object", "properties": { "kind": { "$ref": "#/components/schemas/TransactionalKind" }, "subject": { "type": "string" }, "html": { "type": "string" }, "variables": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "code", "identifier", "number", "date", "url" ] } }, "required": [ "name", "kind" ], "additionalProperties": false } }, "requires_independent_provider": { "type": "boolean" } }, "required": [ "kind", "subject", "html", "variables", "requires_independent_provider" ], "additionalProperties": false }, "TransactionalCatalog": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "transactional.catalog" ] }, "version": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionalCatalogEntry" } } }, "required": [ "object", "version", "data" ], "additionalProperties": false }, "TransactionalEventList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionalEvent" } }, "has_more": { "type": "boolean" } }, "required": [ "object", "data", "has_more" ], "additionalProperties": false }, "TransactionalConnectionList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object" } }, "has_more": { "type": "boolean" } }, "required": [ "object", "data", "has_more" ], "additionalProperties": false }, "TransactionalProviderConnection": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "transactional.provider" ] }, "id": { "type": "string", "format": "uuid" }, "domain_id": { "type": "string", "format": "uuid" }, "provider": { "type": "string", "enum": [ "stripe" ] }, "verified_at": { "type": "string", "format": "date-time", "nullable": true }, "revoked_at": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "object", "id", "domain_id", "provider", "verified_at", "revoked_at" ], "additionalProperties": false }, "TransactionalProviderList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionalProviderConnection" } }, "has_more": { "type": "boolean" } }, "required": [ "object", "data", "has_more" ], "additionalProperties": false }, "TransactionalIntegrationConnection": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "transactional.integration" ] }, "id": { "type": "string", "format": "uuid" }, "domain_id": { "type": "string", "format": "uuid" }, "callback_url": { "type": "string", "format": "uri" }, "verified_at": { "type": "string", "format": "date-time", "nullable": true }, "revoked_at": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "object", "id", "domain_id", "callback_url", "verified_at", "revoked_at" ], "additionalProperties": false }, "TransactionalIntegrationList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionalIntegrationConnection" } }, "has_more": { "type": "boolean" } }, "required": [ "object", "data", "has_more" ], "additionalProperties": false } }, "parameters": { "PaginationLimit": { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Number of items to return." }, "PaginationAfter": { "in": "query", "name": "after", "required": false, "schema": { "type": "string" }, "description": "Return items after this cursor." }, "PaginationBefore": { "in": "query", "name": "before", "required": false, "schema": { "type": "string" }, "description": "Return items before this cursor." } } } }