{ "openapi": "3.0.3", "info": { "title": "Teamander Mail API", "version": "1.0.0", "description": "Deliverability-first transactional email API. All endpoints require an API key via `Authorization: Bearer tmk_...` and are served under `/v1`." }, "servers": [ { "url": "https://mail.teamander.com/v1", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Authenticate with an API key: `Authorization: Bearer tmk_...`. Keys are scope-gated — each endpoint notes the scope it requires." } }, "schemas": {}, "parameters": {} }, "paths": { "/emails/send": { "post": { "tags": [ "Emails" ], "summary": "Send an email", "description": "Queues a transactional email for one or up to 50 recipients. Provide **one** of `template_id`, `html`, or `text`. Pass an `Idempotency-Key` header to make retries safe — a repeated key returns the original result with `idempotent_replay: true` and never sends twice. Custom `headers` values are stripped of CR/LF to prevent header injection.", "parameters": [ { "schema": { "type": "string", "maxLength": 255, "description": "Unique key to make the send idempotent across retries", "example": "order-1234-receipt" }, "required": false, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "anyOf": [ { "type": "string", "format": "email" }, { "type": "array", "items": { "type": "string", "format": "email" }, "minItems": 1, "maxItems": 50 } ] }, "from": { "type": "string", "format": "email" }, "subject": { "type": "string" }, "template_id": { "type": "string", "minLength": 1, "maxLength": 50 }, "data": { "type": "object", "additionalProperties": { "nullable": true } }, "html": { "type": "string" }, "text": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "nullable": true } }, "headers": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "to" ] }, "example": { "to": "jane@example.com", "from": "billing@yourdomain.com", "subject": "Your receipt", "template_id": "receipt", "data": { "name": "Jane", "amount": "$42.00" } } } } }, "responses": { "200": { "description": "Idempotent replay of a previous send", "content": { "application/json": { "schema": { "type": "object", "properties": { "queued": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "recipient": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "recipient", "status" ] } }, "suppressed": { "type": "array", "items": { "type": "string" } }, "idempotent_replay": { "type": "boolean" } }, "required": [ "queued" ] }, "example": { "queued": [ { "id": "a1b2c3d4-...", "recipient": "jane@example.com", "status": "sent" } ], "idempotent_replay": true } } } }, "201": { "description": "Queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "queued": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "recipient": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "recipient", "status" ] } }, "suppressed": { "type": "array", "items": { "type": "string" } }, "idempotent_replay": { "type": "boolean" } }, "required": [ "queued" ] }, "example": { "queued": [ { "id": "a1b2c3d4-...", "recipient": "jane@example.com", "status": "queued" } ] } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "nullable": true } } }, "required": [ "error" ] }, "example": { "error": "Validation failed", "details": {} } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Invalid API key" } } } }, "429": { "description": "Rate limit or monthly quota exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Monthly email limit exceeded" } } } } } } }, "/emails/{id}": { "get": { "tags": [ "Emails" ], "summary": "Get an email log", "parameters": [ { "schema": { "type": "string", "description": "Resource identifier", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The email log", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "recipient_email": { "type": "string" }, "sender_email": { "type": "string" }, "template_id": { "type": "string", "nullable": true }, "subject": { "type": "string" }, "status": { "type": "string" }, "smtp_provider": { "type": "string" }, "smtp_response": { "type": "string", "nullable": true }, "error_message": { "type": "string", "nullable": true }, "attempts": { "type": "integer" }, "sent_at": { "type": "string", "nullable": true }, "created_at": { "type": "string" } }, "required": [ "id", "recipient_email", "sender_email", "template_id", "subject", "status", "smtp_provider", "smtp_response", "error_message", "attempts", "sent_at", "created_at" ] } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Invalid API key" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "not_found" } } } } } } }, "/emails": { "get": { "tags": [ "Emails" ], "summary": "List email logs", "parameters": [ { "schema": { "type": "string", "description": "Page size (1–100, default 50)", "example": "50" }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Rows to skip (default 0)", "example": "0" }, "required": false, "name": "offset", "in": "query" }, { "schema": { "type": "string", "description": "Filter by status", "example": "delivered" }, "required": false, "name": "status", "in": "query" } ], "responses": { "200": { "description": "Paginated email logs", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "recipient_email": { "type": "string" }, "sender_email": { "type": "string" }, "subject": { "type": "string" }, "status": { "type": "string" }, "sent_at": { "type": "string", "nullable": true }, "created_at": { "type": "string" } }, "required": [ "id", "recipient_email", "sender_email", "subject", "status", "sent_at", "created_at" ] } }, "limit": { "type": "integer" }, "offset": { "type": "integer" } }, "required": [ "data", "limit", "offset" ] } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Invalid API key" } } } } } } }, "/api-keys": { "post": { "tags": [ "API keys" ], "summary": "Create an API key", "description": "Mints a new key and returns the raw value **once** — store it immediately. Requested scopes are clamped to the caller's own. Valid scopes: email:send, email:read, template:read, template:manage, domain:read, domain:write, smtp:read, smtp:write, suppression:read, suppression:write, webhook:read, webhook:write, apikey:manage.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "email:send", "email:read", "template:read", "template:manage", "domain:read", "domain:write", "smtp:read", "smtp:write", "suppression:read", "suppression:write", "webhook:read", "webhook:write", "apikey:manage" ] } }, "rate_limit": { "type": "integer", "minimum": 1, "maximum": 10000 } }, "required": [ "name" ] }, "example": { "name": "Production server", "scopes": [ "email:send", "email:read" ], "rate_limit": 120 } } } }, "responses": { "201": { "description": "Key created (raw key shown once)", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string" }, "prefix": { "type": "string" }, "name": { "type": "string" }, "warning": { "type": "string" } }, "required": [ "key", "prefix", "name", "warning" ] }, "example": { "key": "tmk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "prefix": "tmk_xxxxxxx...", "name": "Production server", "warning": "Save this key now. It will not be shown again." } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "nullable": true } } }, "required": [ "error" ] }, "example": { "error": "Validation failed", "details": {} } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Invalid API key" } } } } } }, "get": { "tags": [ "API keys" ], "summary": "List API keys", "description": "Returns key metadata and prefixes only — never the full key.", "responses": { "200": { "description": "API keys", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "key_prefix": { "type": "string" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "rate_limit": { "type": "integer" }, "active": { "type": "boolean" }, "last_used_at": { "type": "string", "nullable": true }, "created_at": { "type": "string" } }, "required": [ "id", "key_prefix", "name", "scopes", "rate_limit", "active", "last_used_at", "created_at" ] } } }, "required": [ "data" ] } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Invalid API key" } } } } } } }, "/api-keys/{id}": { "delete": { "tags": [ "API keys" ], "summary": "Revoke an API key", "description": "Soft-revoke: the key is marked inactive (`active = false`).", "parameters": [ { "schema": { "type": "string", "description": "Resource identifier", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "revoked" ] } }, "required": [ "id", "status" ] }, "example": { "id": "42", "status": "revoked" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Invalid API key" } } } } } } }, "/webhook-endpoints": { "post": { "tags": [ "Webhook endpoints" ], "summary": "Register a webhook endpoint", "description": "Subscribes a URL to delivery events. Returns a `whsec_...` signing secret **once** — use it to verify the `X-Teamander-Signature` header on incoming events. Max 10 endpoints per tenant.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "email.sent", "email.delivered", "email.deferred", "email.bounced", "email.complained", "email.failed", "email.opened", "email.clicked", "email.unsubscribed" ] }, "minItems": 1, "maxItems": 9 } }, "required": [ "url", "events" ] }, "example": { "url": "https://example.com/webhooks/teamander", "events": [ "email.delivered", "email.bounced", "email.complained" ] } } } }, "responses": { "201": { "description": "Endpoint created (secret shown once)", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "active": { "type": "boolean" }, "secret": { "type": "string" }, "warning": { "type": "string" } }, "required": [ "id", "url", "events", "active", "secret", "warning" ] }, "example": { "id": 1, "url": "https://example.com/webhooks/teamander", "events": [ "email.delivered", "email.bounced" ], "active": true, "secret": "whsec_xxxxxxxxxxxxxxxxxxxxxxxx", "warning": "Save this signing secret now. It will not be shown again." } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "nullable": true } } }, "required": [ "error" ] }, "example": { "error": "Validation failed", "details": {} } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Invalid API key" } } } } } }, "get": { "tags": [ "Webhook endpoints" ], "summary": "List webhook endpoints", "responses": { "200": { "description": "Endpoints (secret never returned)", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "active": { "type": "boolean" }, "created_at": { "type": "string" } }, "required": [ "id", "url", "events", "active", "created_at" ] } } }, "required": [ "data" ] } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Invalid API key" } } } } } } }, "/webhook-endpoints/{id}": { "patch": { "tags": [ "Webhook endpoints" ], "summary": "Update a webhook endpoint", "description": "Change the URL, subscribed events, or toggle `active`.", "parameters": [ { "schema": { "type": "string", "description": "Resource identifier", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "email.sent", "email.delivered", "email.deferred", "email.bounced", "email.complained", "email.failed", "email.opened", "email.clicked", "email.unsubscribed" ] }, "minItems": 1, "maxItems": 9 }, "active": { "type": "boolean" } } }, "example": { "active": false } } } }, "responses": { "200": { "description": "Updated endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "active": { "type": "boolean" }, "created_at": { "type": "string" } }, "required": [ "id", "url", "events", "active", "created_at" ] } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "nullable": true } } }, "required": [ "error" ] }, "example": { "error": "Validation failed", "details": {} } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Invalid API key" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "not_found" } } } } } }, "delete": { "tags": [ "Webhook endpoints" ], "summary": "Delete a webhook endpoint", "parameters": [ { "schema": { "type": "string", "description": "Resource identifier", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string", "enum": [ "deleted" ] } }, "required": [ "id", "status" ] }, "example": { "id": 1, "status": "deleted" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Invalid API key" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "not_found" } } } } } } }, "/templates": { "post": { "tags": [ "Templates" ], "summary": "Create a template", "description": "Provide `mjml_source` (compiled to HTML at save time) or raw `html`.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 50, "pattern": "^[a-z0-9_-]+$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "subject_template": { "type": "string", "minLength": 1 }, "mjml_source": { "type": "string" }, "design_json": { "type": "object", "properties": { "schema_version": { "type": "integer", "minimum": 1, "maximum": 1 }, "theme": { "type": "object", "properties": { "backgroundColor": { "type": "string", "maxLength": 64 }, "contentBackgroundColor": { "type": "string", "maxLength": 64 }, "fontFamily": { "type": "string", "maxLength": 200 }, "linkColor": { "type": "string", "maxLength": 64 }, "width": { "type": "string", "maxLength": 16 } }, "default": { "backgroundColor": "#f3f4f6", "contentBackgroundColor": "#ffffff", "fontFamily": "Helvetica, Arial, sans-serif", "linkColor": "#4f46e5", "width": "600px" }, "required": [ "backgroundColor", "contentBackgroundColor", "fontFamily", "linkColor", "width" ] }, "blocks": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "heading" ] }, "text": { "type": "string", "maxLength": 500 }, "level": { "anyOf": [ { "type": "number", "enum": [ 1 ] }, { "type": "number", "enum": [ 2 ] }, { "type": "number", "enum": [ 3 ] } ] }, "align": { "type": "string", "enum": [ "left", "center", "right" ] }, "color": { "type": "string", "maxLength": 64 } }, "required": [ "id", "type", "text", "level", "align" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "text" ] }, "html": { "type": "string", "maxLength": 20000 }, "align": { "type": "string", "enum": [ "left", "center", "right" ] }, "color": { "type": "string", "maxLength": 64 } }, "required": [ "id", "type", "html", "align" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "button" ] }, "label": { "type": "string", "maxLength": 200 }, "href": { "type": "string", "maxLength": 2048 }, "align": { "type": "string", "enum": [ "left", "center", "right" ] }, "backgroundColor": { "type": "string", "maxLength": 64 }, "color": { "type": "string", "maxLength": 64 } }, "required": [ "id", "type", "label", "href", "align" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "image" ] }, "src": { "type": "string", "maxLength": 2048 }, "alt": { "type": "string", "maxLength": 500 }, "href": { "type": "string", "maxLength": 2048 }, "width": { "type": "string", "maxLength": 16 }, "align": { "type": "string", "enum": [ "left", "center", "right" ] } }, "required": [ "id", "type", "src", "alt", "align" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "divider" ] }, "color": { "type": "string", "maxLength": 64 } }, "required": [ "id", "type" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "spacer" ] }, "height": { "type": "integer", "minimum": 1, "maximum": 200 } }, "required": [ "id", "type", "height" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "social" ] }, "align": { "type": "string", "enum": [ "left", "center", "right" ] }, "networks": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 50 }, "href": { "type": "string", "maxLength": 2048 } }, "required": [ "name", "href" ] }, "maxItems": 10 } }, "required": [ "id", "type", "align", "networks" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "footer" ] }, "html": { "type": "string", "maxLength": 5000 }, "unsubscribeUrl": { "type": "string", "maxLength": 2048 } }, "required": [ "id", "type", "html" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "columns" ] }, "columns": { "type": "array", "items": { "type": "object", "properties": { "blocks": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "heading" ] }, "text": { "type": "string", "maxLength": 500 }, "level": { "anyOf": [ { "type": "number", "enum": [ 1 ] }, { "type": "number", "enum": [ 2 ] }, { "type": "number", "enum": [ 3 ] } ] }, "align": { "type": "string", "enum": [ "left", "center", "right" ] }, "color": { "type": "string", "maxLength": 64 } }, "required": [ "id", "type", "text", "level", "align" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "text" ] }, "html": { "type": "string", "maxLength": 20000 }, "align": { "type": "string", "enum": [ "left", "center", "right" ] }, "color": { "type": "string", "maxLength": 64 } }, "required": [ "id", "type", "html", "align" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "button" ] }, "label": { "type": "string", "maxLength": 200 }, "href": { "type": "string", "maxLength": 2048 }, "align": { "type": "string", "enum": [ "left", "center", "right" ] }, "backgroundColor": { "type": "string", "maxLength": 64 }, "color": { "type": "string", "maxLength": 64 } }, "required": [ "id", "type", "label", "href", "align" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "image" ] }, "src": { "type": "string", "maxLength": 2048 }, "alt": { "type": "string", "maxLength": 500 }, "href": { "type": "string", "maxLength": 2048 }, "width": { "type": "string", "maxLength": 16 }, "align": { "type": "string", "enum": [ "left", "center", "right" ] } }, "required": [ "id", "type", "src", "alt", "align" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "divider" ] }, "color": { "type": "string", "maxLength": 64 } }, "required": [ "id", "type" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "spacer" ] }, "height": { "type": "integer", "minimum": 1, "maximum": 200 } }, "required": [ "id", "type", "height" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "social" ] }, "align": { "type": "string", "enum": [ "left", "center", "right" ] }, "networks": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 50 }, "href": { "type": "string", "maxLength": 2048 } }, "required": [ "name", "href" ] }, "maxItems": 10 } }, "required": [ "id", "type", "align", "networks" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "footer" ] }, "html": { "type": "string", "maxLength": 5000 }, "unsubscribeUrl": { "type": "string", "maxLength": 2048 } }, "required": [ "id", "type", "html" ] } ] }, "maxItems": 50 } }, "required": [ "blocks" ] }, "minItems": 1, "maxItems": 4 } }, "required": [ "id", "type", "columns" ] } ] }, "maxItems": 200 } }, "required": [ "schema_version", "blocks" ] }, "html": { "type": "string" }, "text_body": { "type": "string" }, "variables": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "id", "name", "subject_template" ] }, "example": { "id": "receipt", "name": "Receipt", "subject_template": "Your receipt from {{company}}", "mjml_source": "Hi {{name}}" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "created" ] }, "warnings": { "type": "array", "items": { "type": "string" } }, "variables": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "id", "status" ] }, "example": { "id": "receipt", "status": "created" } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "nullable": true } } }, "required": [ "error" ] }, "example": { "error": "Validation failed", "details": {} } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Invalid API key" } } } } } }, "get": { "tags": [ "Templates" ], "summary": "List templates", "responses": { "200": { "description": "Templates", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "subject_template": { "type": "string" }, "active": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "subject_template", "active", "created_at", "updated_at" ] } } }, "required": [ "data" ] } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Invalid API key" } } } } } } }, "/templates/starters": { "get": { "tags": [ "Templates" ], "summary": "List starter templates", "description": "Curated starting points for the template editor, each rendered with your brand settings applied. `thumbnail_html` is the compiled email, suitable for a scaled gallery preview.", "responses": { "200": { "description": "Starters", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string" }, "description": { "type": "string" }, "subject_template": { "type": "string" }, "thumbnail_html": { "type": "string" } }, "required": [ "slug", "name", "category", "description", "subject_template", "thumbnail_html" ] } } }, "required": [ "data" ] } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Invalid API key" } } } } } } }, "/templates/starters/{slug}": { "get": { "tags": [ "Templates" ], "summary": "Get a starter template", "description": "Returns MJML with your brand settings already substituted, ready to save as a new template. Brand tokens are resolved here, so only genuine send-time merge tags remain.", "parameters": [ { "schema": { "type": "string", "description": "Starter slug", "example": "welcome" }, "required": true, "name": "slug", "in": "path" } ], "responses": { "200": { "description": "Starter detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string" }, "description": { "type": "string" }, "subject_template": { "type": "string" }, "mjml_source": { "type": "string" }, "variables": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "slug", "name", "category", "description", "subject_template", "mjml_source", "variables" ] } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Invalid API key" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "not_found" } } } } } } }, "/templates/preview": { "post": { "tags": [ "Templates" ], "summary": "Preview a template", "description": "Compiles MJML and interpolates `data` without saving anything. MJML and Handlebars problems come back in `errors` rather than as a failed request, so a partially written template still renders.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "mjml_source": { "type": "string" }, "design_json": { "type": "object", "properties": { "schema_version": { "type": "integer", "minimum": 1, "maximum": 1 }, "theme": { "type": "object", "properties": { "backgroundColor": { "type": "string", "maxLength": 64 }, "contentBackgroundColor": { "type": "string", "maxLength": 64 }, "fontFamily": { "type": "string", "maxLength": 200 }, "linkColor": { "type": "string", "maxLength": 64 }, "width": { "type": "string", "maxLength": 16 } }, "default": { "backgroundColor": "#f3f4f6", "contentBackgroundColor": "#ffffff", "fontFamily": "Helvetica, Arial, sans-serif", "linkColor": "#4f46e5", "width": "600px" }, "required": [ "backgroundColor", "contentBackgroundColor", "fontFamily", "linkColor", "width" ] }, "blocks": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "heading" ] }, "text": { "type": "string", "maxLength": 500 }, "level": { "anyOf": [ { "type": "number", "enum": [ 1 ] }, { "type": "number", "enum": [ 2 ] }, { "type": "number", "enum": [ 3 ] } ] }, "align": { "type": "string", "enum": [ "left", "center", "right" ] }, "color": { "type": "string", "maxLength": 64 } }, "required": [ "id", "type", "text", "level", "align" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "text" ] }, "html": { "type": "string", "maxLength": 20000 }, "align": { "type": "string", "enum": [ "left", "center", "right" ] }, "color": { "type": "string", "maxLength": 64 } }, "required": [ "id", "type", "html", "align" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "button" ] }, "label": { "type": "string", "maxLength": 200 }, "href": { "type": "string", "maxLength": 2048 }, "align": { "type": "string", "enum": [ "left", "center", "right" ] }, "backgroundColor": { "type": "string", "maxLength": 64 }, "color": { "type": "string", "maxLength": 64 } }, "required": [ "id", "type", "label", "href", "align" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "image" ] }, "src": { "type": "string", "maxLength": 2048 }, "alt": { "type": "string", "maxLength": 500 }, "href": { "type": "string", "maxLength": 2048 }, "width": { "type": "string", "maxLength": 16 }, "align": { "type": "string", "enum": [ "left", "center", "right" ] } }, "required": [ "id", "type", "src", "alt", "align" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "divider" ] }, "color": { "type": "string", "maxLength": 64 } }, "required": [ "id", "type" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "spacer" ] }, "height": { "type": "integer", "minimum": 1, "maximum": 200 } }, "required": [ "id", "type", "height" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "social" ] }, "align": { "type": "string", "enum": [ "left", "center", "right" ] }, "networks": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 50 }, "href": { "type": "string", "maxLength": 2048 } }, "required": [ "name", "href" ] }, "maxItems": 10 } }, "required": [ "id", "type", "align", "networks" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "footer" ] }, "html": { "type": "string", "maxLength": 5000 }, "unsubscribeUrl": { "type": "string", "maxLength": 2048 } }, "required": [ "id", "type", "html" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "columns" ] }, "columns": { "type": "array", "items": { "type": "object", "properties": { "blocks": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "heading" ] }, "text": { "type": "string", "maxLength": 500 }, "level": { "anyOf": [ { "type": "number", "enum": [ 1 ] }, { "type": "number", "enum": [ 2 ] }, { "type": "number", "enum": [ 3 ] } ] }, "align": { "type": "string", "enum": [ "left", "center", "right" ] }, "color": { "type": "string", "maxLength": 64 } }, "required": [ "id", "type", "text", "level", "align" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "text" ] }, "html": { "type": "string", "maxLength": 20000 }, "align": { "type": "string", "enum": [ "left", "center", "right" ] }, "color": { "type": "string", "maxLength": 64 } }, "required": [ "id", "type", "html", "align" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "button" ] }, "label": { "type": "string", "maxLength": 200 }, "href": { "type": "string", "maxLength": 2048 }, "align": { "type": "string", "enum": [ "left", "center", "right" ] }, "backgroundColor": { "type": "string", "maxLength": 64 }, "color": { "type": "string", "maxLength": 64 } }, "required": [ "id", "type", "label", "href", "align" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "image" ] }, "src": { "type": "string", "maxLength": 2048 }, "alt": { "type": "string", "maxLength": 500 }, "href": { "type": "string", "maxLength": 2048 }, "width": { "type": "string", "maxLength": 16 }, "align": { "type": "string", "enum": [ "left", "center", "right" ] } }, "required": [ "id", "type", "src", "alt", "align" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "divider" ] }, "color": { "type": "string", "maxLength": 64 } }, "required": [ "id", "type" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "spacer" ] }, "height": { "type": "integer", "minimum": 1, "maximum": 200 } }, "required": [ "id", "type", "height" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "social" ] }, "align": { "type": "string", "enum": [ "left", "center", "right" ] }, "networks": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 50 }, "href": { "type": "string", "maxLength": 2048 } }, "required": [ "name", "href" ] }, "maxItems": 10 } }, "required": [ "id", "type", "align", "networks" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "footer" ] }, "html": { "type": "string", "maxLength": 5000 }, "unsubscribeUrl": { "type": "string", "maxLength": 2048 } }, "required": [ "id", "type", "html" ] } ] }, "maxItems": 50 } }, "required": [ "blocks" ] }, "minItems": 1, "maxItems": 4 } }, "required": [ "id", "type", "columns" ] } ] }, "maxItems": 200 } }, "required": [ "schema_version", "blocks" ] }, "html": { "type": "string" }, "subject_template": { "type": "string" }, "text_body": { "type": "string" }, "data": { "type": "object", "additionalProperties": { "nullable": true } } } }, "example": { "mjml_source": "Hi {{name}}", "subject_template": "Welcome, {{name}}!", "data": { "name": "Jane" } } } } }, "responses": { "200": { "description": "Rendered preview", "content": { "application/json": { "schema": { "type": "object", "properties": { "html": { "type": "string" }, "subject": { "type": "string" }, "text": { "type": "string" }, "mjml_source": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" } }, "variables": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "html", "subject", "text", "mjml_source", "errors", "variables" ] }, "example": { "html": "…", "subject": "Welcome, Jane!", "text": "Hi Jane", "mjml_source": "…", "errors": [], "variables": { "name": "string" } } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "nullable": true } } }, "required": [ "error" ] }, "example": { "error": "Validation failed", "details": {} } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Invalid API key" } } } } } } }, "/templates/{id}": { "get": { "tags": [ "Templates" ], "summary": "Get a template", "parameters": [ { "schema": { "type": "string", "description": "Resource identifier", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Template detail", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "nullable": true } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Invalid API key" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "not_found" } } } } } }, "put": { "tags": [ "Templates" ], "summary": "Update a template", "description": "Partial update; each save creates a new template version.", "parameters": [ { "schema": { "type": "string", "description": "Resource identifier", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "subject_template": { "type": "string", "minLength": 1 }, "mjml_source": { "type": "string" }, "design_json": { "type": "object", "properties": { "schema_version": { "type": "integer", "minimum": 1, "maximum": 1 }, "theme": { "type": "object", "properties": { "backgroundColor": { "type": "string", "maxLength": 64 }, "contentBackgroundColor": { "type": "string", "maxLength": 64 }, "fontFamily": { "type": "string", "maxLength": 200 }, "linkColor": { "type": "string", "maxLength": 64 }, "width": { "type": "string", "maxLength": 16 } }, "default": { "backgroundColor": "#f3f4f6", "contentBackgroundColor": "#ffffff", "fontFamily": "Helvetica, Arial, sans-serif", "linkColor": "#4f46e5", "width": "600px" }, "required": [ "backgroundColor", "contentBackgroundColor", "fontFamily", "linkColor", "width" ] }, "blocks": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "heading" ] }, "text": { "type": "string", "maxLength": 500 }, "level": { "anyOf": [ { "type": "number", "enum": [ 1 ] }, { "type": "number", "enum": [ 2 ] }, { "type": "number", "enum": [ 3 ] } ] }, "align": { "type": "string", "enum": [ "left", "center", "right" ] }, "color": { "type": "string", "maxLength": 64 } }, "required": [ "id", "type", "text", "level", "align" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "text" ] }, "html": { "type": "string", "maxLength": 20000 }, "align": { "type": "string", "enum": [ "left", "center", "right" ] }, "color": { "type": "string", "maxLength": 64 } }, "required": [ "id", "type", "html", "align" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "button" ] }, "label": { "type": "string", "maxLength": 200 }, "href": { "type": "string", "maxLength": 2048 }, "align": { "type": "string", "enum": [ "left", "center", "right" ] }, "backgroundColor": { "type": "string", "maxLength": 64 }, "color": { "type": "string", "maxLength": 64 } }, "required": [ "id", "type", "label", "href", "align" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "image" ] }, "src": { "type": "string", "maxLength": 2048 }, "alt": { "type": "string", "maxLength": 500 }, "href": { "type": "string", "maxLength": 2048 }, "width": { "type": "string", "maxLength": 16 }, "align": { "type": "string", "enum": [ "left", "center", "right" ] } }, "required": [ "id", "type", "src", "alt", "align" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "divider" ] }, "color": { "type": "string", "maxLength": 64 } }, "required": [ "id", "type" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "spacer" ] }, "height": { "type": "integer", "minimum": 1, "maximum": 200 } }, "required": [ "id", "type", "height" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "social" ] }, "align": { "type": "string", "enum": [ "left", "center", "right" ] }, "networks": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 50 }, "href": { "type": "string", "maxLength": 2048 } }, "required": [ "name", "href" ] }, "maxItems": 10 } }, "required": [ "id", "type", "align", "networks" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "footer" ] }, "html": { "type": "string", "maxLength": 5000 }, "unsubscribeUrl": { "type": "string", "maxLength": 2048 } }, "required": [ "id", "type", "html" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "columns" ] }, "columns": { "type": "array", "items": { "type": "object", "properties": { "blocks": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "heading" ] }, "text": { "type": "string", "maxLength": 500 }, "level": { "anyOf": [ { "type": "number", "enum": [ 1 ] }, { "type": "number", "enum": [ 2 ] }, { "type": "number", "enum": [ 3 ] } ] }, "align": { "type": "string", "enum": [ "left", "center", "right" ] }, "color": { "type": "string", "maxLength": 64 } }, "required": [ "id", "type", "text", "level", "align" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "text" ] }, "html": { "type": "string", "maxLength": 20000 }, "align": { "type": "string", "enum": [ "left", "center", "right" ] }, "color": { "type": "string", "maxLength": 64 } }, "required": [ "id", "type", "html", "align" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "button" ] }, "label": { "type": "string", "maxLength": 200 }, "href": { "type": "string", "maxLength": 2048 }, "align": { "type": "string", "enum": [ "left", "center", "right" ] }, "backgroundColor": { "type": "string", "maxLength": 64 }, "color": { "type": "string", "maxLength": 64 } }, "required": [ "id", "type", "label", "href", "align" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "image" ] }, "src": { "type": "string", "maxLength": 2048 }, "alt": { "type": "string", "maxLength": 500 }, "href": { "type": "string", "maxLength": 2048 }, "width": { "type": "string", "maxLength": 16 }, "align": { "type": "string", "enum": [ "left", "center", "right" ] } }, "required": [ "id", "type", "src", "alt", "align" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "divider" ] }, "color": { "type": "string", "maxLength": 64 } }, "required": [ "id", "type" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "spacer" ] }, "height": { "type": "integer", "minimum": 1, "maximum": 200 } }, "required": [ "id", "type", "height" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "social" ] }, "align": { "type": "string", "enum": [ "left", "center", "right" ] }, "networks": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 50 }, "href": { "type": "string", "maxLength": 2048 } }, "required": [ "name", "href" ] }, "maxItems": 10 } }, "required": [ "id", "type", "align", "networks" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "footer" ] }, "html": { "type": "string", "maxLength": 5000 }, "unsubscribeUrl": { "type": "string", "maxLength": 2048 } }, "required": [ "id", "type", "html" ] } ] }, "maxItems": 50 } }, "required": [ "blocks" ] }, "minItems": 1, "maxItems": 4 } }, "required": [ "id", "type", "columns" ] } ] }, "maxItems": 200 } }, "required": [ "schema_version", "blocks" ] }, "html": { "type": "string" }, "text_body": { "type": "string" }, "variables": { "type": "object", "additionalProperties": { "type": "string" } } } }, "example": { "subject_template": "Updated subject {{company}}" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "version": { "type": "integer" }, "status": { "type": "string", "enum": [ "updated" ] }, "compiled_html": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "string" } }, "variables": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "id", "version", "status" ] }, "example": { "id": "receipt", "version": 2, "status": "updated" } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "nullable": true } } }, "required": [ "error" ] }, "example": { "error": "Validation failed", "details": {} } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Invalid API key" } } } } } }, "delete": { "tags": [ "Templates" ], "summary": "Deactivate a template", "description": "Soft delete: the template is marked inactive.", "parameters": [ { "schema": { "type": "string", "description": "Resource identifier", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Deactivated", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "deactivated" ] } }, "required": [ "id", "status" ] }, "example": { "id": "receipt", "status": "deactivated" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Invalid API key" } } } } } } }, "/suppressions": { "get": { "tags": [ "Suppressions" ], "summary": "List suppressed addresses", "parameters": [ { "schema": { "type": "string", "description": "Page size (1–100, default 50)", "example": "50" }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Rows to skip (default 0)", "example": "0" }, "required": false, "name": "offset", "in": "query" } ], "responses": { "200": { "description": "Suppressed addresses", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "email_address": { "type": "string" }, "reason": { "type": "string" }, "added_at": { "type": "string" } }, "required": [ "email_address", "reason", "added_at" ] } }, "limit": { "type": "integer" }, "offset": { "type": "integer" } }, "required": [ "data", "limit", "offset" ] } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Invalid API key" } } } } } }, "post": { "tags": [ "Suppressions" ], "summary": "Suppress an address", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email_address": { "type": "string", "format": "email" }, "reason": { "type": "string", "enum": [ "manual", "bounce", "complaint", "unsubscribe" ], "default": "manual" } }, "required": [ "email_address" ] }, "example": { "email_address": "bounced@example.com", "reason": "manual" } } } }, "responses": { "201": { "description": "Suppressed", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "suppressed" ] } }, "required": [ "status" ] }, "example": { "status": "suppressed" } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "nullable": true } } }, "required": [ "error" ] }, "example": { "error": "Validation failed", "details": {} } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Invalid API key" } } } } } } }, "/suppressions/{email}": { "delete": { "tags": [ "Suppressions" ], "summary": "Remove a suppression", "parameters": [ { "schema": { "type": "string", "description": "Email address", "example": "jane@example.com" }, "required": true, "name": "email", "in": "path" } ], "responses": { "200": { "description": "Removed", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "removed" ] } }, "required": [ "status" ] }, "example": { "status": "removed" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Invalid API key" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "not_found" } } } } } } }, "/suppressions/check/{email}": { "get": { "tags": [ "Suppressions" ], "summary": "Check if an address is suppressed", "parameters": [ { "schema": { "type": "string", "description": "Email address", "example": "jane@example.com" }, "required": true, "name": "email", "in": "path" } ], "responses": { "200": { "description": "Suppression status", "content": { "application/json": { "schema": { "type": "object", "properties": { "suppressed": { "type": "boolean" }, "reason": { "type": "string", "nullable": true }, "since": { "type": "string", "nullable": true } }, "required": [ "suppressed", "reason", "since" ] }, "example": { "suppressed": true, "reason": "bounce", "since": "2026-07-01T12:00:00.000Z" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Invalid API key" } } } } } } }, "/domains": { "post": { "tags": [ "Domains" ], "summary": "Add a sending domain", "description": "Returns the DNS records (SPF, DKIM, DMARC) to add, then call verify.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "minLength": 3, "maxLength": 255, "pattern": "^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?(\\.[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?)*\\.[a-zA-Z]{2,}$" } }, "required": [ "domain" ] }, "example": { "domain": "mail.yourdomain.com" } } } }, "responses": { "201": { "description": "Domain added with DNS records to publish", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string" }, "dns_records": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "host": { "type": "string" }, "value": { "type": "string" } }, "required": [ "type", "host", "value" ] } }, "message": { "type": "string" } }, "required": [ "domain", "dns_records", "message" ] } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "nullable": true } } }, "required": [ "error" ] }, "example": { "error": "Validation failed", "details": {} } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Invalid API key" } } } }, "409": { "description": "Domain already added", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "domain_exists" } } } } } }, "get": { "tags": [ "Domains" ], "summary": "List sending domains", "responses": { "200": { "description": "Domains", "content": { "application/json": { "schema": { "type": "object", "properties": { "domains": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "dkim_selector": { "type": "string" }, "spf_verified": { "type": "boolean" }, "dkim_verified": { "type": "boolean" }, "dmarc_verified": { "type": "boolean" }, "dns_records": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "host": { "type": "string" }, "value": { "type": "string" } }, "required": [ "type", "host", "value" ] } }, "verified_at": { "type": "string", "nullable": true }, "created_at": { "type": "string" } }, "required": [ "domain", "dkim_selector", "spf_verified", "dkim_verified", "dmarc_verified", "dns_records", "verified_at", "created_at" ] } } }, "required": [ "domains" ] } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Invalid API key" } } } } } } }, "/domains/{domain}": { "get": { "tags": [ "Domains" ], "summary": "Get a domain", "parameters": [ { "schema": { "type": "string", "description": "Sending domain", "example": "mail.yourdomain.com" }, "required": true, "name": "domain", "in": "path" } ], "responses": { "200": { "description": "Domain detail", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "nullable": true } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Invalid API key" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "not_found" } } } } } }, "delete": { "tags": [ "Domains" ], "summary": "Remove a sending domain", "parameters": [ { "schema": { "type": "string", "description": "Sending domain", "example": "mail.yourdomain.com" }, "required": true, "name": "domain", "in": "path" } ], "responses": { "200": { "description": "Removed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success" ] }, "example": { "success": true } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Invalid API key" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "not_found" } } } } } } }, "/domains/{domain}/verify": { "post": { "tags": [ "Domains" ], "summary": "Verify domain DNS", "description": "Performs live DNS lookups for SPF/DKIM/DMARC and updates verification state.", "parameters": [ { "schema": { "type": "string", "description": "Sending domain", "example": "mail.yourdomain.com" }, "required": true, "name": "domain", "in": "path" } ], "responses": { "200": { "description": "Verification result", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string" }, "verification": { "type": "object", "additionalProperties": { "nullable": true } }, "ready_to_send": { "type": "boolean" } }, "required": [ "domain", "verification", "ready_to_send" ] } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Invalid API key" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "not_found" } } } } } } }, "/smtp-config": { "post": { "tags": [ "SMTP config" ], "summary": "Set BYOS SMTP credentials", "description": "Stores and verifies your own SMTP provider. The connection is tested before saving.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "ses", "mailgun", "sendgrid", "custom" ] }, "host": { "type": "string", "minLength": 1, "maxLength": 255 }, "port": { "type": "integer", "minimum": 1, "maximum": 65535 }, "username": { "type": "string", "minLength": 1, "maxLength": 255 }, "password": { "type": "string", "minLength": 1, "maxLength": 512 }, "tls_required": { "type": "boolean", "default": true }, "from_email": { "type": "string", "format": "email" }, "from_name": { "type": "string", "maxLength": 128 } }, "required": [ "provider", "host", "port", "username", "password" ] }, "example": { "provider": "ses", "host": "email-smtp.us-east-1.amazonaws.com", "port": 587, "username": "AKIA...", "password": "secret", "from_email": "noreply@yourdomain.com" } } } }, "responses": { "200": { "description": "Saved and verified", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "provider": { "type": "string" } }, "required": [ "success", "provider" ] }, "example": { "success": true, "provider": "ses" } } } }, "400": { "description": "Invalid host or connection failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "smtp_connection_failed" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Invalid API key" } } } } } }, "get": { "tags": [ "SMTP config" ], "summary": "Get BYOS SMTP config", "description": "Returns the stored config without the password.", "responses": { "200": { "description": "SMTP config", "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "type": "string" }, "host": { "type": "string" }, "port": { "type": "integer" }, "username": { "type": "string" }, "tls_required": { "type": "boolean" }, "from_email": { "type": "string", "nullable": true }, "from_name": { "type": "string", "nullable": true }, "verified": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "provider", "host", "port", "username", "tls_required", "from_email", "from_name", "verified", "created_at", "updated_at" ] } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Invalid API key" } } } }, "404": { "description": "No SMTP config", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "no_smtp_config" } } } } } }, "delete": { "tags": [ "SMTP config" ], "summary": "Remove BYOS SMTP config", "description": "Reverts the tenant to platform delivery.", "responses": { "200": { "description": "Removed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "smtp_provider": { "type": "string", "enum": [ "platform" ] } }, "required": [ "success", "smtp_provider" ] }, "example": { "success": true, "smtp_provider": "platform" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Invalid API key" } } } } } } }, "/smtp-config/verify": { "post": { "tags": [ "SMTP config" ], "summary": "Re-verify stored SMTP config", "responses": { "200": { "description": "Verified", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ] }, "example": { "success": true } } } }, "400": { "description": "Verification failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "string" } }, "required": [ "success" ] } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Invalid API key" } } } }, "404": { "description": "No SMTP config", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "no_smtp_config" } } } } } } }, "/analytics/summary": { "get": { "tags": [ "Analytics" ], "summary": "Delivery analytics summary", "parameters": [ { "schema": { "type": "string", "enum": [ "24h", "7d", "30d", "90d" ], "description": "Reporting window (default 30d)", "example": "30d" }, "required": false, "name": "period", "in": "query" } ], "responses": { "200": { "description": "Summary metrics", "content": { "application/json": { "schema": { "type": "object", "properties": { "period": { "type": "string" }, "total_sent": { "type": "integer" }, "delivered": { "type": "integer" }, "bounced": { "type": "integer" }, "failed": { "type": "integer" }, "complaint_rate": { "type": "number" }, "statuses": { "type": "object", "additionalProperties": { "type": "integer" } }, "monthly_usage": { "type": "array", "items": { "type": "object", "additionalProperties": { "nullable": true } } } }, "required": [ "period", "total_sent", "delivered", "bounced", "failed", "complaint_rate", "statuses", "monthly_usage" ] }, "example": { "period": "30d", "total_sent": 1280, "delivered": 1240, "bounced": 30, "failed": 10, "complaint_rate": 0.0016, "statuses": { "queued": 0, "sending": 0, "sent": 1240, "failed": 10, "bounced": 30, "complained": 2, "delivered": 0, "deferred": 0 }, "monthly_usage": [] } } } }, "400": { "description": "Invalid period", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Invalid period — must be one of: 24h, 7d, 30d, 90d" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "Invalid API key" } } } } } } } } }