{ "openapi": "3.1.0", "info": { "title": "Outbox Stack API", "version": "1.0.0", "license": { "name": "Proprietary", "url": "https://outboxstack.app/terms" }, "description": "Transactional email API. Authenticate with `Authorization: Bearer `. Errors return `{error, code, request_id}`: branch on `code`, show `error`, quote `request_id` to support. Unknown fields are rejected." }, "servers": [ { "url": "https://outboxstack.app" } ], "security": [ { "apiKey": [] } ], "paths": { "/v1/messages": { "post": { "operationId": "sendMessage", "summary": "Send a message", "description": "Accepted means queued, not delivered. Multiple recipients return one id per recipient in `recipients`; `id` is the first.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Repeating a key returns the original result with HTTP 200 instead of sending again." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMessage" } } } }, "responses": { "202": { "description": "Queued.", "headers": { "X-Request-Id": { "description": "Unique id for this request; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendResult" } } } }, "200": { "description": "Duplicate of an earlier request with the same Idempotency-Key.", "headers": { "X-Request-Id": { "description": "Unique id for this request; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendResult" } } } }, "400": { "description": "Invalid request (`invalid_request`, `invalid_address`, `invalid_header`, `invalid_attachment`, `too_many_recipients`, ...).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly allowance and credits exhausted (`quota_exceeded`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks access (`forbidden`, `sender_domain_not_allowed`) or the account is restricted (`account_restricted`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body or attachments too large (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Cannot send as requested (`domain_not_verified`, `sending_not_configured`, `missing_template_data`, `unsupported_by_provider`, ...).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or sandbox limit (`rate_limited`, `sandbox_limit_reached`). Retry with backoff and the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable (`unavailable`). Retry with backoff and the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "listMessages", "summary": "List recent messages", "parameters": [ { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/MessageStatus" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "Most recent first.", "headers": { "X-Request-Id": { "description": "Unique id for this request; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "messages" ], "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/MessageSummary" } } } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks access (`forbidden`, `sender_domain_not_allowed`) or the account is restricted (`account_restricted`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/messages/batch": { "post": { "operationId": "sendBatch", "summary": "Send up to 100 messages", "description": "Items succeed or fail independently; the response is 202 even when some items fail.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "messages" ], "additionalProperties": false, "properties": { "messages": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/BatchMessage" } } } } } } }, "responses": { "202": { "description": "Per-item results.", "headers": { "X-Request-Id": { "description": "Unique id for this request; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchResult" } } } }, "400": { "description": "Invalid request (`invalid_request`, `invalid_address`, `invalid_header`, `invalid_attachment`, `too_many_recipients`, ...).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks access (`forbidden`, `sender_domain_not_allowed`) or the account is restricted (`account_restricted`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body or attachments too large (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/messages/{id}": { "get": { "operationId": "getMessage", "summary": "Get a message", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The message.", "headers": { "X-Request-Id": { "description": "Unique id for this request; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageDetail" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such message in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "webhooks": { "message.sent": { "post": { "operationId": "on_message_sent", "summary": "message.sent", "description": "Signed with Standard Webhooks: headers `webhook-id`, `webhook-timestamp`, `webhook-signature` (`v1,` + base64 HMAC-SHA256 of `id.timestamp.body` keyed with the base64-decoded `whsec_` secret). Reject timestamps older than 5 minutes. Respond 2xx; failures are retried for about an hour.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Acknowledged." } } } }, "message.delivered": { "post": { "operationId": "on_message_delivered", "summary": "message.delivered", "description": "Signed with Standard Webhooks: headers `webhook-id`, `webhook-timestamp`, `webhook-signature` (`v1,` + base64 HMAC-SHA256 of `id.timestamp.body` keyed with the base64-decoded `whsec_` secret). Reject timestamps older than 5 minutes. Respond 2xx; failures are retried for about an hour.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Acknowledged." } } } }, "message.bounced": { "post": { "operationId": "on_message_bounced", "summary": "message.bounced", "description": "Signed with Standard Webhooks: headers `webhook-id`, `webhook-timestamp`, `webhook-signature` (`v1,` + base64 HMAC-SHA256 of `id.timestamp.body` keyed with the base64-decoded `whsec_` secret). Reject timestamps older than 5 minutes. Respond 2xx; failures are retried for about an hour.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Acknowledged." } } } }, "message.complained": { "post": { "operationId": "on_message_complained", "summary": "message.complained", "description": "Signed with Standard Webhooks: headers `webhook-id`, `webhook-timestamp`, `webhook-signature` (`v1,` + base64 HMAC-SHA256 of `id.timestamp.body` keyed with the base64-decoded `whsec_` secret). Reject timestamps older than 5 minutes. Respond 2xx; failures are retried for about an hour.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Acknowledged." } } } }, "message.failed": { "post": { "operationId": "on_message_failed", "summary": "message.failed", "description": "Signed with Standard Webhooks: headers `webhook-id`, `webhook-timestamp`, `webhook-signature` (`v1,` + base64 HMAC-SHA256 of `id.timestamp.body` keyed with the base64-decoded `whsec_` secret). Reject timestamps older than 5 minutes. Respond 2xx; failures are retried for about an hour.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Acknowledged." } } } }, "message.opened": { "post": { "operationId": "on_message_opened", "summary": "message.opened", "description": "Signed with Standard Webhooks: headers `webhook-id`, `webhook-timestamp`, `webhook-signature` (`v1,` + base64 HMAC-SHA256 of `id.timestamp.body` keyed with the base64-decoded `whsec_` secret). Reject timestamps older than 5 minutes. Respond 2xx; failures are retried for about an hour.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Acknowledged." } } } }, "message.clicked": { "post": { "operationId": "on_message_clicked", "summary": "message.clicked", "description": "Signed with Standard Webhooks: headers `webhook-id`, `webhook-timestamp`, `webhook-signature` (`v1,` + base64 HMAC-SHA256 of `id.timestamp.body` keyed with the base64-decoded `whsec_` secret). Reject timestamps older than 5 minutes. Respond 2xx; failures are retried for about an hour.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Acknowledged." } } } }, "contact.subscribed": { "post": { "operationId": "on_contact_subscribed", "summary": "contact.subscribed", "description": "Signed with Standard Webhooks: headers `webhook-id`, `webhook-timestamp`, `webhook-signature` (`v1,` + base64 HMAC-SHA256 of `id.timestamp.body` keyed with the base64-decoded `whsec_` secret). Reject timestamps older than 5 minutes. Respond 2xx; failures are retried for about an hour.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Acknowledged." } } } }, "contact.unsubscribed": { "post": { "operationId": "on_contact_unsubscribed", "summary": "contact.unsubscribed", "description": "Signed with Standard Webhooks: headers `webhook-id`, `webhook-timestamp`, `webhook-signature` (`v1,` + base64 HMAC-SHA256 of `id.timestamp.body` keyed with the base64-decoded `whsec_` secret). Reject timestamps older than 5 minutes. Respond 2xx; failures are retried for about an hour.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Acknowledged." } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "Workspace API key (`mk_...`). Sending keys reach only /v1/messages and may be locked to one sender domain." } }, "schemas": { "SendMessage": { "type": "object", "required": [ "from", "to" ], "additionalProperties": false, "properties": { "from": { "type": "string", "format": "email", "description": "Sender address on a verified domain." }, "fromName": { "type": "string", "maxLength": 200 }, "to": { "oneOf": [ { "type": "string", "description": "`email@example.com` or `Display Name `.", "examples": [ "Ada Obi " ] }, { "type": "array", "items": { "type": "string", "description": "`email@example.com` or `Display Name `.", "examples": [ "Ada Obi " ] }, "minItems": 1 } ], "description": "One address or a list. Each address in to, cc and bcc becomes its own message; together at most 50." }, "toName": { "type": "string", "maxLength": 200, "description": "Display name when `to` is a single bare address." }, "cc": { "oneOf": [ { "type": "string", "description": "`email@example.com` or `Display Name `.", "examples": [ "Ada Obi " ] }, { "type": "array", "items": { "type": "string", "description": "`email@example.com` or `Display Name `.", "examples": [ "Ada Obi " ] }, "minItems": 1 } ] }, "bcc": { "oneOf": [ { "type": "string", "description": "`email@example.com` or `Display Name `.", "examples": [ "Ada Obi " ] }, { "type": "array", "items": { "type": "string", "description": "`email@example.com` or `Display Name `.", "examples": [ "Ada Obi " ] }, "minItems": 1 } ], "description": "Never shown in any copy's headers." }, "replyTo": { "type": "string", "format": "email" }, "subject": { "type": "string", "maxLength": 998 }, "html": { "type": "string" }, "text": { "type": "string", "description": "Generated from html when omitted." }, "template": { "type": "string", "description": "Template id or slug, in place of subject/html/text." }, "data": { "type": "object", "additionalProperties": true, "description": "Template variables." }, "headers": { "type": "object", "maxProperties": 20, "additionalProperties": { "type": "string", "maxLength": 998 }, "description": "Custom headers. Routing, authentication and provider-control headers (From, To, Subject, Message-ID, DKIM-Signature, X-SES-*, X-Amz*, ...) are refused." }, "attachments": { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "At most 10 MB decoded in total. Executable types are refused." }, "metadata": { "type": "object", "maxProperties": 10, "propertyNames": { "pattern": "^[A-Za-z0-9_.-]{1,40}$" }, "additionalProperties": { "type": "string", "maxLength": 256 }, "description": "Your own references, returned by GET and in webhooks." } }, "description": "Provide `template` (with `data`), or `subject` with `html` and/or `text`." }, "BatchMessage": { "type": "object", "required": [ "from", "to" ], "additionalProperties": false, "properties": { "from": { "type": "string", "format": "email", "description": "Sender address on a verified domain." }, "fromName": { "type": "string", "maxLength": 200 }, "to": { "oneOf": [ { "type": "string", "description": "`email@example.com` or `Display Name `.", "examples": [ "Ada Obi " ] }, { "type": "array", "items": { "type": "string", "description": "`email@example.com` or `Display Name `.", "examples": [ "Ada Obi " ] }, "minItems": 1 } ], "description": "One address or a list. Each address in to, cc and bcc becomes its own message; together at most 50." }, "toName": { "type": "string", "maxLength": 200, "description": "Display name when `to` is a single bare address." }, "cc": { "oneOf": [ { "type": "string", "description": "`email@example.com` or `Display Name `.", "examples": [ "Ada Obi " ] }, { "type": "array", "items": { "type": "string", "description": "`email@example.com` or `Display Name `.", "examples": [ "Ada Obi " ] }, "minItems": 1 } ] }, "bcc": { "oneOf": [ { "type": "string", "description": "`email@example.com` or `Display Name `.", "examples": [ "Ada Obi " ] }, { "type": "array", "items": { "type": "string", "description": "`email@example.com` or `Display Name `.", "examples": [ "Ada Obi " ] }, "minItems": 1 } ], "description": "Never shown in any copy's headers." }, "replyTo": { "type": "string", "format": "email" }, "subject": { "type": "string", "maxLength": 998 }, "html": { "type": "string" }, "text": { "type": "string", "description": "Generated from html when omitted." }, "template": { "type": "string", "description": "Template id or slug, in place of subject/html/text." }, "data": { "type": "object", "additionalProperties": true, "description": "Template variables." }, "headers": { "type": "object", "maxProperties": 20, "additionalProperties": { "type": "string", "maxLength": 998 }, "description": "Custom headers. Routing, authentication and provider-control headers (From, To, Subject, Message-ID, DKIM-Signature, X-SES-*, X-Amz*, ...) are refused." }, "attachments": { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "At most 10 MB decoded in total. Executable types are refused." }, "metadata": { "type": "object", "maxProperties": 10, "propertyNames": { "pattern": "^[A-Za-z0-9_.-]{1,40}$" }, "additionalProperties": { "type": "string", "maxLength": 256 }, "description": "Your own references, returned by GET and in webhooks." }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 200 } } }, "Attachment": { "type": "object", "required": [ "filename", "content" ], "additionalProperties": false, "properties": { "filename": { "type": "string", "maxLength": 255 }, "content": { "type": "string", "contentEncoding": "base64" }, "contentType": { "type": "string", "description": "Inferred from the filename when omitted." }, "contentId": { "type": "string", "pattern": "^[A-Za-z0-9._@-]{1,100}$", "description": "Makes the file inline; reference it in html as `cid:`." } } }, "MessageStatus": { "type": "string", "enum": [ "queued", "sending", "sent", "delivered", "bounced", "complained", "failed", "suppressed", "cancelled" ] }, "SendResult": { "type": "object", "required": [ "id", "status", "duplicate" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "$ref": "#/components/schemas/MessageStatus" }, "duplicate": { "type": "boolean", "description": "True when the Idempotency-Key matched an earlier send (HTTP 200)." }, "recipients": { "type": "array", "items": { "$ref": "#/components/schemas/RecipientResult" }, "description": "Present when the send had more than one recipient." } } }, "RecipientResult": { "type": "object", "required": [ "email", "id", "status", "duplicate" ], "properties": { "email": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "status": { "$ref": "#/components/schemas/MessageStatus" }, "duplicate": { "type": "boolean" } } }, "BatchResult": { "type": "object", "required": [ "accepted", "failed", "results" ], "properties": { "accepted": { "type": "integer" }, "failed": { "type": "integer" }, "results": { "type": "array", "items": { "oneOf": [ { "type": "object", "required": [ "index", "id", "status", "duplicate" ], "properties": { "index": { "type": "integer" }, "id": { "type": "string", "format": "uuid" }, "status": { "$ref": "#/components/schemas/MessageStatus" }, "duplicate": { "type": "boolean" }, "recipients": { "type": "array", "items": { "$ref": "#/components/schemas/RecipientResult" } } } }, { "type": "object", "required": [ "index", "error", "code" ], "properties": { "index": { "type": "integer" }, "error": { "type": "string" }, "code": { "$ref": "#/components/schemas/ErrorCode" } } } ] } } } }, "MessageSummary": { "type": "object", "required": [ "id", "stream", "to_email", "subject", "status", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "stream": { "type": "string", "enum": [ "transactional", "marketing" ] }, "to_email": { "type": "string" }, "subject": { "type": "string" }, "status": { "$ref": "#/components/schemas/MessageStatus" }, "created_at": { "type": "string", "format": "date-time" } } }, "MessageDetail": { "allOf": [ { "$ref": "#/components/schemas/MessageSummary" }, { "type": "object", "properties": { "from_email": { "type": "string" }, "from_name": { "type": [ "string", "null" ] }, "to_name": { "type": [ "string", "null" ] }, "reply_to": { "type": [ "string", "null" ] }, "html": { "type": [ "string", "null" ] }, "text": { "type": [ "string", "null" ] }, "attempts": { "type": "integer" }, "last_error": { "type": [ "string", "null" ] }, "idempotency_key": { "type": [ "string", "null" ] }, "provider_message_id": { "type": [ "string", "null" ] }, "template_id": { "type": [ "string", "null" ] }, "extras": { "type": [ "object", "null" ], "description": "Shared To/Cc display lists, custom headers and attachment descriptions of a multi-recipient or rich send." }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } }, "events": { "type": "array", "description": "Delivery history, oldest first.", "items": { "type": "object", "required": [ "type", "at" ], "properties": { "type": { "type": "string", "examples": [ "sent", "delivered", "bounced", "opened", "clicked" ] }, "at": { "type": "string", "format": "date-time" } } } }, "updated_at": { "type": "string", "format": "date-time" }, "sent_at": { "type": [ "string", "null" ], "format": "date-time" } } } ] }, "ErrorCode": { "anyOf": [ { "type": "string", "enum": [ "invalid_request", "invalid_address", "missing_content", "invalid_header", "invalid_metadata", "invalid_attachment", "too_many_recipients", "unauthorized", "forbidden", "sender_domain_not_allowed", "account_restricted", "payment_required", "quota_exceeded", "not_found", "template_not_found", "conflict", "payload_too_large", "unprocessable", "domain_not_verified", "invalid_sender", "missing_template_data", "sending_not_configured", "sending_unavailable", "sandbox_recipient_not_allowed", "unsupported_by_provider", "rate_limited", "sandbox_limit_reached", "internal_error", "unavailable", "method_not_allowed", "gone", "unsupported_media_type", "bad_gateway", "error" ] }, { "type": "string" } ], "description": "Stable machine-readable code. New codes may be added; treat unknown codes by HTTP status." }, "Error": { "type": "object", "required": [ "error", "code" ], "properties": { "error": { "type": "string", "description": "Human-readable; wording may change." }, "code": { "$ref": "#/components/schemas/ErrorCode" }, "request_id": { "type": "string" } } }, "WebhookEvent": { "type": "object", "required": [ "type", "created_at", "data" ], "properties": { "type": { "type": "string", "enum": [ "message.sent", "message.delivered", "message.bounced", "message.complained", "message.failed", "message.opened", "message.clicked", "contact.subscribed", "contact.unsubscribed" ] }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "description": "message.* events: message_id, to, subject, stream, campaign_id, metadata, plus provider_message_id (sent) or recipients and occurred_at (feedback). contact.* events: contact_id, email, list_id.", "additionalProperties": true } } } } } }