{ "openapi": "3.0.0", "info": { "title": "Sendpit API", "description": "Email testing platform REST API for programmatic email management, search, wait, and webhooks.", "contact": { "email": "support@sendpit.com" }, "version": "1.0.0" }, "servers": [ { "url": "https://sendpit.com/api/v1", "description": "Production" } ], "paths": { "/messages/{messageId}/attachments/{index}": { "get": { "tags": [ "Messages" ], "summary": "Download attachment", "description": "Download a message attachment by index. Extracts from raw MIME stored in GridFS.", "operationId": "downloadAttachment", "parameters": [ { "name": "messageId", "in": "path", "description": "Message ID", "required": true, "schema": { "type": "string" } }, { "name": "index", "in": "path", "description": "Zero-based attachment index", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Attachment file content" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan does not include API access (`plan_required`), or the mailbox is disabled (`mailbox_disabled`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Message or attachment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/messages": { "get": { "tags": [ "Messages" ], "summary": "List messages", "description": "List messages for the authenticated mailbox with optional filters and cursor or offset pagination.", "operationId": "listMessages", "parameters": [ { "name": "after", "in": "query", "description": "Cursor for forward pagination", "schema": { "type": "string" } }, { "name": "before", "in": "query", "description": "Cursor for backward pagination", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of results (cursor mode, default 25)", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "description": "Page number (deprecated offset mode)", "schema": { "type": "integer", "deprecated": true } }, { "name": "per_page", "in": "query", "description": "Results per page (deprecated offset mode)", "schema": { "type": "integer", "deprecated": true } }, { "name": "from", "in": "query", "description": "Filter by sender address", "schema": { "type": "string" } }, { "name": "to", "in": "query", "description": "Filter by recipient address", "schema": { "type": "string" } }, { "name": "match", "in": "query", "description": "Address filter matching mode for from/to. contains (default) = substring; exact = full address match. Subject always substring.", "schema": { "type": "string", "enum": [ "contains", "exact" ] } }, { "name": "subject", "in": "query", "description": "Filter by subject (partial match)", "schema": { "type": "string" } }, { "name": "since", "in": "query", "description": "Messages received after this ISO 8601 datetime", "schema": { "type": "string", "format": "date-time" } }, { "name": "until", "in": "query", "description": "Messages received before this ISO 8601 datetime", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Paginated message list", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MessageCompact" } }, "meta": { "$ref": "#/components/schemas/CursorMeta" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan does not include API access (`plan_required`), or the mailbox is disabled (`mailbox_disabled`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "basicAuth": [] } ] }, "post": { "tags": [ "Messages" ], "summary": "Submit a message", "description": "Submit an email into the authenticated mailbox over HTTP as an alternative to SMTP. The message is captured into the fake inbox with real-time, webhook, and inspection behaviour. Send an X-Idempotency-Key header to make retries safe.", "operationId": "submitMessage", "requestBody": { "description": "At least one of `html` or `text` is required. Custom `headers` may not set reserved/structural names (From, To, Cc, Bcc, Reply-To, Subject, Date, Message-ID, MIME-Version, Content-*, DKIM-*). Recipient lists and headers are capped at 100 entries each; up to 20 attachments with per-attachment and combined decoded-size limits (see config/sendpit.php).", "required": true, "content": { "application/json": { "schema": { "required": [ "from", "to" ], "properties": { "from": { "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "example": "app@acme.test" }, "name": { "type": "string", "example": "Acme App" } }, "type": "object" }, "to": { "type": "array", "items": { "type": "string", "format": "email" }, "example": [ "customer@example.com" ], "maxItems": 100 }, "cc": { "type": "array", "items": { "type": "string", "format": "email" }, "maxItems": 100 }, "bcc": { "type": "array", "items": { "type": "string", "format": "email" }, "maxItems": 100 }, "reply_to": { "type": "array", "items": { "type": "string", "format": "email" }, "maxItems": 100 }, "subject": { "type": "string", "example": "Reset your password", "maxLength": 998 }, "html": { "description": "HTML body. Required when `text` is absent.", "type": "string", "example": "

Hello

", "maxLength": 5242880 }, "text": { "description": "Plain-text body. Required when `html` is absent.", "type": "string", "example": "Hello", "maxLength": 5242880 }, "headers": { "description": "Custom headers (max 100). Reserved/structural names are rejected.", "type": "object" }, "attachments": { "type": "array", "items": { "required": [ "filename", "content_type", "content" ], "properties": { "filename": { "type": "string" }, "content_type": { "description": "MIME type/subtype, e.g. application/pdf", "type": "string" }, "content": { "description": "base64-encoded bytes", "type": "string" } }, "type": "object" }, "maxItems": 20 } }, "type": "object" } } } }, "responses": { "201": { "description": "Message submitted", "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "id": { "type": "string" }, "message_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan does not include API access (`plan_required`), the mailbox is disabled (`mailbox_disabled`), or the organization is at its stored email capacity (`plan_limit`). Capacity is shared across all mailboxes in the organization by SMTP and API submissions alike; deleting stored messages or retention cleanup frees it. Idempotent retries of an already-stored message still return their original 201.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency conflict or still in progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Idempotency protection is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "basicAuth": [] } ] }, "delete": { "tags": [ "Messages" ], "summary": "Clear all messages", "description": "Delete all messages from the authenticated mailbox.", "operationId": "clearMessages", "responses": { "204": { "description": "All messages deleted" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan does not include API access (`plan_required`), or the mailbox is disabled (`mailbox_disabled`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/messages/{messageId}": { "get": { "tags": [ "Messages" ], "summary": "Get message detail", "description": "Retrieve full details of a single message including body, headers, and metadata.", "operationId": "showMessage", "parameters": [ { "name": "messageId", "in": "path", "description": "Message ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Message detail" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan does not include API access (`plan_required`), or the mailbox is disabled (`mailbox_disabled`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Message not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "basicAuth": [] } ] }, "delete": { "tags": [ "Messages" ], "summary": "Delete a message", "description": "Permanently delete a single message from the mailbox.", "operationId": "deleteMessage", "parameters": [ { "name": "messageId", "in": "path", "description": "Message ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Message deleted" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan does not include API access (`plan_required`), or the mailbox is disabled (`mailbox_disabled`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Message not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/messages/{messageId}/raw": { "get": { "tags": [ "Inspection" ], "summary": "Download raw EML", "description": "Download the raw RFC 2822 .eml file for a message.", "operationId": "getMessageRaw", "parameters": [ { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Raw EML file", "content": { "message/rfc822": {} } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan does not include API access (`plan_required`), or the mailbox is disabled (`mailbox_disabled`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Message not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/messages/{messageId}/headers": { "get": { "tags": [ "Inspection" ], "summary": "Get parsed headers", "description": "Returns all parsed email headers as a JSON object.", "operationId": "getMessageHeaders", "parameters": [ { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Parsed headers", "content": { "application/json": { "schema": { "properties": { "data": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan does not include API access (`plan_required`), or the mailbox is disabled (`mailbox_disabled`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Message not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/messages/{messageId}/body/text": { "get": { "tags": [ "Inspection" ], "summary": "Get plain text body", "description": "Returns the plain text body of the message.", "operationId": "getMessageBodyText", "parameters": [ { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Plain text body", "content": { "text/plain": {} } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan does not include API access (`plan_required`), or the mailbox is disabled (`mailbox_disabled`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Message not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/messages/{messageId}/body/html": { "get": { "tags": [ "Inspection" ], "summary": "Get HTML body", "description": "Returns the HTML body wrapped in JSON to prevent XSS.", "operationId": "getMessageBodyHtml", "parameters": [ { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTML body", "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "html": { "type": "string" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan does not include API access (`plan_required`), or the mailbox is disabled (`mailbox_disabled`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Message not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/messages/{messageId}/attachments": { "get": { "tags": [ "Inspection" ], "summary": "List attachments", "description": "Returns attachment metadata and download URLs for a message.", "operationId": "listMessageAttachments", "parameters": [ { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Attachment list", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "properties": { "index": { "type": "integer" }, "filename": { "type": "string", "nullable": true }, "content_type": { "type": "string", "nullable": true }, "size_bytes": { "type": "integer", "nullable": true }, "disposition": { "type": "string", "nullable": true }, "content_id": { "type": "string", "nullable": true }, "download_url": { "type": "string" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan does not include API access (`plan_required`), or the mailbox is disabled (`mailbox_disabled`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Message not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/messages/{messageId}/extractions": { "get": { "tags": [ "Inspection" ], "summary": "Get extracted codes and links", "description": "Returns OTP codes, verification links, and other extracted content from the message.", "operationId": "getMessageExtractions", "parameters": [ { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Extracted content", "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "codes": { "type": "array", "items": { "type": "object" } }, "links": { "type": "array", "items": { "type": "object" } }, "content_extracted_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan does not include API access (`plan_required`), or the mailbox is disabled (`mailbox_disabled`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Message not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/messages/{messageId}/inspection": { "get": { "tags": [ "Inspection" ], "summary": "Get spam analysis and metadata", "description": "Returns spam analysis results and message metadata including size, hash, and message-id.", "operationId": "getMessageInspection", "parameters": [ { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Inspection data", "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "spam": { "properties": { "score": { "type": "number", "nullable": true }, "threshold": { "type": "number", "nullable": true }, "is_spam": { "type": "boolean", "nullable": true }, "is_analyzed": { "type": "boolean" }, "status": { "type": "string" }, "analyzed_at": { "type": "string", "format": "date-time", "nullable": true }, "analysis_duration_ms": { "type": "integer", "nullable": true } }, "type": "object" }, "metadata": { "properties": { "size_bytes": { "type": "integer", "nullable": true }, "text_size_bytes": { "type": "integer", "nullable": true }, "html_size_bytes": { "type": "integer", "nullable": true }, "content_hash": { "type": "string", "nullable": true }, "message_id": { "type": "string", "nullable": true }, "in_reply_to": { "type": "string", "nullable": true } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan does not include API access (`plan_required`), or the mailbox is disabled (`mailbox_disabled`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Message not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/messages/{messageId}/timeline": { "get": { "tags": [ "Inspection" ], "summary": "Get processing timeline", "description": "Returns the processing timeline of a message with events like received, spam_analyzed, content_extracted.", "operationId": "getMessageTimeline", "parameters": [ { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Timeline events", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "properties": { "event": { "type": "string" }, "at": { "type": "string", "format": "date-time" }, "duration_ms": { "type": "integer", "nullable": true } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan does not include API access (`plan_required`), or the mailbox is disabled (`mailbox_disabled`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Message not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/rate-limit": { "get": { "tags": [ "Observability" ], "summary": "Get rate limit status", "description": "Returns current rate limit quota, remaining requests, and reset time. The quota is shared by every mailbox in the authenticated mailbox's organization.", "operationId": "getRateLimit", "responses": { "200": { "description": "Rate limit status", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/RateLimit" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan does not include API access (`plan_required`), or the mailbox is disabled (`mailbox_disabled`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/messages/search": { "post": { "tags": [ "Search" ], "summary": "Search messages", "description": "Structured search with full filter set and cursor pagination.", "operationId": "searchMessages", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "filters": { "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "cc": { "type": "string" }, "bcc": { "type": "string" }, "match": { "description": "Address filter matching mode for from/to/cc/bcc. contains (default) = substring; exact = full address match. Subject/body always substring.", "type": "string", "enum": [ "contains", "exact" ] }, "subject": { "type": "string" }, "body": { "type": "string" }, "headers": { "description": "Header name (canonical case) to value regex-match pairs, max 10", "type": "object" }, "received_after": { "type": "string", "format": "date-time" }, "received_before": { "type": "string", "format": "date-time" }, "has_attachments": { "type": "boolean" }, "unread": { "type": "boolean" }, "has_codes": { "type": "boolean" }, "has_links": { "type": "boolean" }, "spam_score_min": { "type": "number" }, "spam_score_max": { "type": "number" } }, "type": "object" }, "limit": { "type": "integer", "example": 25 }, "after": { "description": "Cursor for next page", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MessageCompact" } }, "meta": { "$ref": "#/components/schemas/CursorMeta" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan does not include API access (`plan_required`), or the mailbox is disabled (`mailbox_disabled`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/messages/wait": { "post": { "tags": [ "Wait" ], "summary": "Wait for messages", "description": "Long-poll wait for messages matching filters. Returns 200 when matches are found or 204 on timeout.", "operationId": "waitForMessages", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "filters": { "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "cc": { "type": "string" }, "match": { "description": "Address filter matching mode for from/to/cc. contains (default) = substring; exact = full address match. Subject/body always substring.", "type": "string", "enum": [ "contains", "exact" ] }, "subject": { "type": "string" }, "body": { "type": "string" }, "headers": { "description": "Header name (canonical case) to value regex-match pairs, max 10", "type": "object" }, "received_after": { "type": "string", "format": "date-time" }, "received_before": { "type": "string", "format": "date-time" }, "has_attachments": { "type": "boolean" }, "unread": { "type": "boolean" } }, "type": "object" }, "timeout": { "description": "Max seconds to wait (default 15, max 30)", "type": "integer", "example": 15 }, "max_results": { "description": "Max messages to return (default 10)", "type": "integer", "example": 10 }, "after_cursor": { "description": "Cursor for pagination", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Matching messages found", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MessageCompact" } }, "meta": { "$ref": "#/components/schemas/CursorMeta" } }, "type": "object" } } } }, "204": { "description": "Timeout with no matches" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan does not include API access, or does not include the wait endpoint (`plan_required`), or the mailbox is disabled (`mailbox_disabled`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Multiple matches with max_results=1", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Wait backend unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "List webhooks", "description": "List all webhooks configured for the authenticated mailbox.", "operationId": "listWebhooks", "responses": { "200": { "description": "Webhook list", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan does not include API access (`plan_required`), or the mailbox is disabled (`mailbox_disabled`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "basicAuth": [] } ] }, "post": { "tags": [ "Webhooks" ], "summary": "Create a webhook", "description": "Create a new webhook endpoint for the authenticated mailbox.", "operationId": "createWebhook", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "endpoint_url" ], "properties": { "endpoint_url": { "type": "string", "format": "url" }, "secret": { "description": "Signing secret (auto-generated if omitted)", "type": "string" }, "description": { "type": "string", "nullable": true }, "event_types": { "description": "message.deleted and messages.cleared require payload_version=2", "type": "array", "items": { "type": "string", "enum": [ "message.received", "message.deleted", "messages.cleared" ] } }, "payload_version": { "description": "V1 only supports message.received; V2 supports all event types", "type": "integer", "enum": [ 1, 2 ] } }, "type": "object" } } } }, "responses": { "201": { "description": "Webhook created", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Webhook" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan does not include API access (`plan_required`), the mailbox is disabled (`mailbox_disabled`), or the plan does not support webhooks or the mailbox is at its webhook limit (`plan_limit`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/webhooks/{id}": { "get": { "tags": [ "Webhooks" ], "summary": "Get a webhook", "description": "Retrieve details of a single webhook.", "operationId": "showWebhook", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Webhook detail", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Webhook" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan does not include API access (`plan_required`), or the mailbox is disabled (`mailbox_disabled`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Webhook not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "basicAuth": [] } ] }, "put": { "tags": [ "Webhooks" ], "summary": "Update a webhook", "description": "Update an existing webhook configuration.", "operationId": "updateWebhook", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "endpoint_url": { "type": "string", "format": "url" }, "secret": { "type": "string" }, "is_active": { "type": "boolean" }, "description": { "type": "string", "nullable": true }, "event_types": { "description": "message.deleted and messages.cleared require payload_version=2", "type": "array", "items": { "type": "string", "enum": [ "message.received", "message.deleted", "messages.cleared" ] } }, "payload_version": { "description": "V1 only supports message.received; V2 supports all event types", "type": "integer", "enum": [ 1, 2 ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Webhook updated", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Webhook" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan does not include API access (`plan_required`), or the mailbox is disabled (`mailbox_disabled`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Webhook not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "basicAuth": [] } ] }, "delete": { "tags": [ "Webhooks" ], "summary": "Delete a webhook", "description": "Permanently delete a webhook.", "operationId": "deleteWebhook", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Webhook deleted" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan does not include API access (`plan_required`), or the mailbox is disabled (`mailbox_disabled`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Webhook not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/webhooks/{id}/deliveries": { "get": { "tags": [ "Webhooks" ], "summary": "List webhook deliveries", "description": "List delivery log entries for a webhook, paginated.", "operationId": "listWebhookDeliveries", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "description": "Results per page (default 25)", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Delivery log list" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan does not include API access (`plan_required`), or the mailbox is disabled (`mailbox_disabled`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Webhook not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "basicAuth": [] } ] } } }, "components": { "schemas": { "Error": { "properties": { "error": { "properties": { "code": { "type": "string", "example": "not_found" }, "message": { "type": "string", "example": "The requested item was not found." }, "details": { "type": "array", "items": { "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "nullable": true } }, "type": "object" } }, "type": "object" }, "CursorMeta": { "properties": { "next_cursor": { "type": "string", "nullable": true }, "has_more": { "type": "boolean" }, "limit": { "type": "integer" }, "count": { "type": "integer" } }, "type": "object" }, "MessageCompact": { "properties": { "id": { "type": "string" }, "message_id": { "type": "string", "nullable": true }, "from": { "properties": { "address": { "type": "string" }, "name": { "type": "string", "nullable": true } }, "type": "object" }, "to": { "type": "array", "items": { "properties": { "address": { "type": "string" }, "name": { "type": "string", "nullable": true } }, "type": "object" } }, "cc": { "type": "array", "items": { "type": "object" } }, "subject": { "type": "string" }, "received_at": { "type": "string", "format": "date-time" }, "size_bytes": { "type": "integer", "nullable": true }, "is_read": { "type": "boolean" }, "has_attachments": { "type": "boolean" }, "attachment_count": { "type": "integer" }, "has_codes": { "type": "boolean" }, "has_links": { "type": "boolean" }, "spam_score": { "type": "number", "nullable": true }, "spam_threshold": { "type": "number", "nullable": true }, "is_spam": { "type": "boolean", "nullable": true }, "spam_status": { "type": "string", "enum": [ "not_analyzed", "pending", "estimated", "clean", "spam", "failed", "skipped" ] } }, "type": "object" }, "Webhook": { "properties": { "id": { "type": "integer" }, "mailbox_id": { "type": "integer" }, "endpoint_url": { "type": "string" }, "is_active": { "type": "boolean" }, "description": { "type": "string", "nullable": true }, "event_types": { "type": "array", "items": { "type": "string" } }, "payload_version": { "type": "integer" }, "last_triggered_at": { "type": "string", "format": "date-time", "nullable": true }, "last_success_at": { "type": "string", "format": "date-time", "nullable": true }, "last_failure_at": { "type": "string", "format": "date-time", "nullable": true }, "consecutive_failures": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "RateLimit": { "properties": { "limit": { "type": "integer" }, "remaining": { "type": "integer" }, "resets_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "securitySchemes": { "basicAuth": { "type": "http", "description": "A mailbox's SMTP username and password.", "scheme": "basic" } } }, "tags": [ { "name": "Messages", "description": "Messages" }, { "name": "Inspection", "description": "Inspection" }, { "name": "Observability", "description": "Observability" }, { "name": "Search", "description": "Search" }, { "name": "Wait", "description": "Wait" }, { "name": "Webhooks", "description": "Webhooks" } ] }