{ "openapi": "3.1.0", "info": { "title": "Omailo API", "version": "1.8.0", "description": "Single-endpoint API. API keys never replace an inbox's private token. Save request keys before writes and inspect partial bulk results. Sending requires admin-configured, verified SMTP and cron." }, "servers": [ { "url": "https://omailo.net", "description": "Replace with your installation's HTTPS base URL." } ], "paths": { "/api/v1/index.php": { "get": { "operationId": "omailoGet", "summary": "Dispatch an Omailo API action", "description": "See x-actions for each action's scope, input and response data. Domain restrictions and site access rules apply. Authentication is optional ONLY for GET capabilities. This API is intended for same-origin UI or server-side clients; cross-origin browser access is not enabled.", "parameters": [ { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "capabilities", "domains", "inbox", "inbox_controls", "messages", "message", "verification_code", "outbox" ] } }, { "name": "X-Inbox-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for owned-inbox actions. Never put private credentials in the URL." }, { "name": "X-Inbox-Token", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for owned-inbox actions. Never put private credentials in the URL." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200, "description": "Literal text search in sender, subject and stored text/HTML body; maximum 200 UTF-8 bytes." } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 320, "description": "Literal sender text; maximum 320 UTF-8 bytes." } }, { "name": "read", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "read", "unread" ], "default": "all" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Opaque next_cursor from the previous page; retain the same filters." } }, { "name": "message_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "security": [ {}, { "ApiKey": [] }, { "BearerKey": [] } ], "responses": { "200": { "description": "Success or recovered inbox", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID; retain for support." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true }, "data": { "anyOf": [ { "type": "object", "properties": { "api_version": { "type": "string" }, "service_version": { "type": "string" }, "actions": { "type": "object" }, "limits": { "type": "object" } } }, { "type": "object", "description": "Access context including domains and permitted lifetime_options." }, { "type": "object", "properties": { "inbox": { "$ref": "#/components/schemas/Inbox" } } }, { "$ref": "#/components/schemas/InboxControls" }, { "type": "object", "properties": { "inbox": { "$ref": "#/components/schemas/Inbox" }, "recovered": { "type": "boolean" } } }, { "$ref": "#/components/schemas/BulkResult" }, { "$ref": "#/components/schemas/BulkResult" }, { "$ref": "#/components/schemas/MessageList" }, { "type": "object", "properties": { "message": { "$ref": "#/components/schemas/Message" } } }, { "type": "object", "properties": { "updated": { "type": "integer" } } }, { "type": "object", "properties": { "found": { "type": "boolean" }, "code": { "type": [ "string", "null" ] }, "confidence": { "type": "number" }, "message": { "type": [ "object", "null" ] }, "checked": { "type": "integer" }, "scan_limit": { "type": "integer", "enum": [ 25 ] }, "fetch": { "$ref": "#/components/schemas/Fetch" } } }, { "type": "object", "properties": { "deleted": { "type": "boolean" } } }, { "type": "object", "properties": { "deleted": { "type": "boolean" } } }, { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/Outgoing" } } }, { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Outgoing" }, "maxItems": 100 } } }, { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/Outgoing" } } } ] } }, "required": [ "ok", "data" ] } } } }, "201": { "description": "New inbox or bulk creation results", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID; retain for support." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true }, "data": { "anyOf": [ { "type": "object", "properties": { "api_version": { "type": "string" }, "service_version": { "type": "string" }, "actions": { "type": "object" }, "limits": { "type": "object" } } }, { "type": "object", "description": "Access context including domains and permitted lifetime_options." }, { "type": "object", "properties": { "inbox": { "$ref": "#/components/schemas/Inbox" } } }, { "$ref": "#/components/schemas/InboxControls" }, { "type": "object", "properties": { "inbox": { "$ref": "#/components/schemas/Inbox" }, "recovered": { "type": "boolean" } } }, { "$ref": "#/components/schemas/BulkResult" }, { "$ref": "#/components/schemas/BulkResult" }, { "$ref": "#/components/schemas/MessageList" }, { "type": "object", "properties": { "message": { "$ref": "#/components/schemas/Message" } } }, { "type": "object", "properties": { "updated": { "type": "integer" } } }, { "type": "object", "properties": { "found": { "type": "boolean" }, "code": { "type": [ "string", "null" ] }, "confidence": { "type": "number" }, "message": { "type": [ "object", "null" ] }, "checked": { "type": "integer" }, "scan_limit": { "type": "integer", "enum": [ 25 ] }, "fetch": { "$ref": "#/components/schemas/Fetch" } } }, { "type": "object", "properties": { "deleted": { "type": "boolean" } } }, { "type": "object", "properties": { "deleted": { "type": "boolean" } } }, { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/Outgoing" } } }, { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Outgoing" }, "maxItems": 100 } } }, { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/Outgoing" } } } ] } }, "required": [ "ok", "data" ] } } } }, "202": { "description": "Outgoing message durably queued", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID; retain for support." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true }, "data": { "anyOf": [ { "type": "object", "properties": { "api_version": { "type": "string" }, "service_version": { "type": "string" }, "actions": { "type": "object" }, "limits": { "type": "object" } } }, { "type": "object", "description": "Access context including domains and permitted lifetime_options." }, { "type": "object", "properties": { "inbox": { "$ref": "#/components/schemas/Inbox" } } }, { "$ref": "#/components/schemas/InboxControls" }, { "type": "object", "properties": { "inbox": { "$ref": "#/components/schemas/Inbox" }, "recovered": { "type": "boolean" } } }, { "$ref": "#/components/schemas/BulkResult" }, { "$ref": "#/components/schemas/BulkResult" }, { "$ref": "#/components/schemas/MessageList" }, { "type": "object", "properties": { "message": { "$ref": "#/components/schemas/Message" } } }, { "type": "object", "properties": { "updated": { "type": "integer" } } }, { "type": "object", "properties": { "found": { "type": "boolean" }, "code": { "type": [ "string", "null" ] }, "confidence": { "type": "number" }, "message": { "type": [ "object", "null" ] }, "checked": { "type": "integer" }, "scan_limit": { "type": "integer", "enum": [ 25 ] }, "fetch": { "$ref": "#/components/schemas/Fetch" } } }, { "type": "object", "properties": { "deleted": { "type": "boolean" } } }, { "type": "object", "properties": { "deleted": { "type": "boolean" } } }, { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/Outgoing" } } }, { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Outgoing" }, "maxItems": 100 } } }, { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/Outgoing" } } } ] } }, "required": [ "ok", "data" ] } } } }, "400": { "description": "Request rejected; inspect error.code and error.message.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID; retain for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected; inspect error.code and error.message.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID; retain for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected; inspect error.code and error.message.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID; retain for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected; inspect error.code and error.message.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID; retain for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Request rejected; inspect error.code and error.message.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID; retain for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected; inspect error.code and error.message.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID; retain for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Request rejected; inspect error.code and error.message.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID; retain for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected; inspect error.code and error.message.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID; retain for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected; inspect error.code and error.message.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID; retain for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected; inspect error.code and error.message.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID; retain for support." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Wait this many seconds before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected; inspect error.code and error.message.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID; retain for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected; inspect error.code and error.message.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID; retain for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "omailoPost", "summary": "Dispatch an Omailo API action", "description": "See x-actions for each action's scope, input and response data. Domain restrictions and site access rules apply. Authentication is optional ONLY for GET capabilities. This API is intended for same-origin UI or server-side clients; cross-origin browser access is not enabled.", "parameters": [ { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "domains", "inbox_controls", "create_inbox", "bulk_preview", "bulk_create", "messages", "message", "mark_messages", "verification_code", "delete_inbox", "delete_message", "send", "cancel_send" ] } }, { "name": "X-Inbox-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for owned-inbox actions. Never put private credentials in the URL." }, { "name": "X-Inbox-Token", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for owned-inbox actions. Never put private credentials in the URL." } ], "security": [ { "ApiKey": [] }, { "BearerKey": [] } ], "responses": { "200": { "description": "Success or recovered inbox", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID; retain for support." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true }, "data": { "anyOf": [ { "type": "object", "properties": { "api_version": { "type": "string" }, "service_version": { "type": "string" }, "actions": { "type": "object" }, "limits": { "type": "object" } } }, { "type": "object", "description": "Access context including domains and permitted lifetime_options." }, { "type": "object", "properties": { "inbox": { "$ref": "#/components/schemas/Inbox" } } }, { "$ref": "#/components/schemas/InboxControls" }, { "type": "object", "properties": { "inbox": { "$ref": "#/components/schemas/Inbox" }, "recovered": { "type": "boolean" } } }, { "$ref": "#/components/schemas/BulkResult" }, { "$ref": "#/components/schemas/BulkResult" }, { "$ref": "#/components/schemas/MessageList" }, { "type": "object", "properties": { "message": { "$ref": "#/components/schemas/Message" } } }, { "type": "object", "properties": { "updated": { "type": "integer" } } }, { "type": "object", "properties": { "found": { "type": "boolean" }, "code": { "type": [ "string", "null" ] }, "confidence": { "type": "number" }, "message": { "type": [ "object", "null" ] }, "checked": { "type": "integer" }, "scan_limit": { "type": "integer", "enum": [ 25 ] }, "fetch": { "$ref": "#/components/schemas/Fetch" } } }, { "type": "object", "properties": { "deleted": { "type": "boolean" } } }, { "type": "object", "properties": { "deleted": { "type": "boolean" } } }, { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/Outgoing" } } }, { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Outgoing" }, "maxItems": 100 } } }, { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/Outgoing" } } } ] } }, "required": [ "ok", "data" ] } } } }, "201": { "description": "New inbox or bulk creation results", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID; retain for support." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true }, "data": { "anyOf": [ { "type": "object", "properties": { "api_version": { "type": "string" }, "service_version": { "type": "string" }, "actions": { "type": "object" }, "limits": { "type": "object" } } }, { "type": "object", "description": "Access context including domains and permitted lifetime_options." }, { "type": "object", "properties": { "inbox": { "$ref": "#/components/schemas/Inbox" } } }, { "$ref": "#/components/schemas/InboxControls" }, { "type": "object", "properties": { "inbox": { "$ref": "#/components/schemas/Inbox" }, "recovered": { "type": "boolean" } } }, { "$ref": "#/components/schemas/BulkResult" }, { "$ref": "#/components/schemas/BulkResult" }, { "$ref": "#/components/schemas/MessageList" }, { "type": "object", "properties": { "message": { "$ref": "#/components/schemas/Message" } } }, { "type": "object", "properties": { "updated": { "type": "integer" } } }, { "type": "object", "properties": { "found": { "type": "boolean" }, "code": { "type": [ "string", "null" ] }, "confidence": { "type": "number" }, "message": { "type": [ "object", "null" ] }, "checked": { "type": "integer" }, "scan_limit": { "type": "integer", "enum": [ 25 ] }, "fetch": { "$ref": "#/components/schemas/Fetch" } } }, { "type": "object", "properties": { "deleted": { "type": "boolean" } } }, { "type": "object", "properties": { "deleted": { "type": "boolean" } } }, { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/Outgoing" } } }, { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Outgoing" }, "maxItems": 100 } } }, { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/Outgoing" } } } ] } }, "required": [ "ok", "data" ] } } } }, "202": { "description": "Outgoing message durably queued", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID; retain for support." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true }, "data": { "anyOf": [ { "type": "object", "properties": { "api_version": { "type": "string" }, "service_version": { "type": "string" }, "actions": { "type": "object" }, "limits": { "type": "object" } } }, { "type": "object", "description": "Access context including domains and permitted lifetime_options." }, { "type": "object", "properties": { "inbox": { "$ref": "#/components/schemas/Inbox" } } }, { "$ref": "#/components/schemas/InboxControls" }, { "type": "object", "properties": { "inbox": { "$ref": "#/components/schemas/Inbox" }, "recovered": { "type": "boolean" } } }, { "$ref": "#/components/schemas/BulkResult" }, { "$ref": "#/components/schemas/BulkResult" }, { "$ref": "#/components/schemas/MessageList" }, { "type": "object", "properties": { "message": { "$ref": "#/components/schemas/Message" } } }, { "type": "object", "properties": { "updated": { "type": "integer" } } }, { "type": "object", "properties": { "found": { "type": "boolean" }, "code": { "type": [ "string", "null" ] }, "confidence": { "type": "number" }, "message": { "type": [ "object", "null" ] }, "checked": { "type": "integer" }, "scan_limit": { "type": "integer", "enum": [ 25 ] }, "fetch": { "$ref": "#/components/schemas/Fetch" } } }, { "type": "object", "properties": { "deleted": { "type": "boolean" } } }, { "type": "object", "properties": { "deleted": { "type": "boolean" } } }, { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/Outgoing" } } }, { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Outgoing" }, "maxItems": 100 } } }, { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/Outgoing" } } } ] } }, "required": [ "ok", "data" ] } } } }, "400": { "description": "Request rejected; inspect error.code and error.message.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID; retain for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected; inspect error.code and error.message.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID; retain for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected; inspect error.code and error.message.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID; retain for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected; inspect error.code and error.message.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID; retain for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Request rejected; inspect error.code and error.message.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID; retain for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected; inspect error.code and error.message.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID; retain for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Request rejected; inspect error.code and error.message.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID; retain for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected; inspect error.code and error.message.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID; retain for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected; inspect error.code and error.message.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID; retain for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected; inspect error.code and error.message.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID; retain for support." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Wait this many seconds before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected; inspect error.code and error.message.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID; retain for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected; inspect error.code and error.message.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Request correlation ID; retain for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "description": "JSON object: send accepts at most 8 MiB; all other actions accept at most 256 KiB. Attachments together are limited to 5 MiB decoded. Query action selects the schema; body action must match.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/DomainsRequest" }, { "$ref": "#/components/schemas/InboxControlsUpdate" }, { "$ref": "#/components/schemas/CreateInbox" }, { "$ref": "#/components/schemas/BulkPreview" }, { "$ref": "#/components/schemas/BulkCreate" }, { "$ref": "#/components/schemas/QueryMessages" }, { "$ref": "#/components/schemas/QueryMessage" }, { "$ref": "#/components/schemas/MarkMessages" }, { "$ref": "#/components/schemas/DeleteInbox" }, { "$ref": "#/components/schemas/DeleteMessage" }, { "$ref": "#/components/schemas/Send" }, { "$ref": "#/components/schemas/CancelSend" } ] } } } } } } }, "components": { "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "header", "name": "X-Omailo-Api-Key" }, "BearerKey": { "type": "http", "scheme": "bearer" } }, "schemas": { "InboxControlsUpdate": { "type": "object", "properties": { "action": { "const": "inbox_controls" }, "revision": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Latest revision from GET inbox_controls. Refresh and review after a 409; do not blindly retry an old form." }, "lifetime_seconds": { "type": "integer", "enum": [ 0, 3600, 86400, 259200, 604800, 2592000 ], "description": "Set remaining time from the moment of saving. Use only a value currently returned in expiry.allowed_lifetimes." }, "web_sending_enabled": { "type": "boolean" } }, "required": [ "revision" ], "additionalProperties": false, "anyOf": [ { "required": [ "lifetime_seconds" ] }, { "required": [ "web_sending_enabled" ] } ] }, "InboxControls": { "type": "object", "properties": { "inbox": { "$ref": "#/components/schemas/Inbox" }, "revision": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "expiry": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "can_change": { "type": "boolean" }, "can_extend": { "type": "boolean" }, "allowed_lifetimes": { "type": "array", "items": { "type": "object", "properties": { "seconds": { "type": "integer", "minimum": 0 }, "label": { "type": "string" } }, "required": [ "seconds", "label" ] } }, "max_seconds": { "type": "integer" }, "allow_unlimited": { "type": "boolean" }, "reason": { "type": "string" } } }, "sending": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "sender": { "type": "string" }, "requires_api_key": { "type": "boolean" }, "web_sending_enabled": { "type": "boolean" }, "owner_sending_available": { "type": "boolean" }, "reason": { "type": "string" }, "migration_required": { "type": "boolean" }, "owner_sending_migration_required": { "type": "boolean" }, "supports_html": { "type": "boolean" }, "supports_attachments": { "type": "boolean" }, "rich_migration_required": { "type": "boolean" }, "max_html_bytes": { "type": "integer" }, "max_attachments": { "type": "integer" }, "max_attachment_total_bytes": { "type": "integer" }, "inline_image_types": { "type": "array", "items": { "type": "string" } }, "plan_sending_allowed": { "type": "boolean" }, "permission_migration_required": { "type": "boolean" } } }, "changed": { "type": "boolean" }, "cancelled_outgoing": { "type": "integer", "minimum": 0 } }, "required": [ "inbox", "revision", "expiry", "sending" ] }, "Inbox": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "address": { "type": "string", "format": "email" }, "token": { "type": "string", "description": "Returned on creation/recovery only. Store privately." }, "expires_at": { "type": "string", "format": "date-time" }, "message_count": { "type": "integer" }, "web_sending_enabled": { "type": "boolean" }, "remaining_seconds": { "type": [ "integer", "null" ] }, "ttl_seconds": { "type": "integer" }, "lifetime_seconds": { "type": "integer" }, "recovered": { "type": "boolean" } }, "required": [ "id", "address", "expires_at" ] }, "PreviewItem": { "type": "object", "properties": { "index": { "type": "integer" }, "input": { "type": "string" }, "address": { "type": "string" }, "status": { "type": "string" }, "reason": { "type": "string" }, "proof": { "type": "string" }, "error_code": { "type": "string" }, "inbox": { "$ref": "#/components/schemas/Inbox" } } }, "GenerationOptions": { "type": "object", "properties": { "name_pool": { "type": "string", "enum": [ "all", "english", "international", "arabic" ], "default": "all" }, "styles": { "type": "array", "items": { "type": "string", "enum": [ "first", "first_last", "initial_last", "first_last_initial", "last_first" ] }, "minItems": 1, "maxItems": 20, "default": [ "first", "first_last" ] }, "separators": { "type": "array", "items": { "type": "string", "enum": [ "", ".", "-", "_" ] }, "minItems": 1, "maxItems": 20, "default": [ "", ".", "-", "_" ], "description": "An empty string means no separator. Only these three punctuation characters are supported; an empty array is invalid." }, "digit_lengths": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 4 }, "minItems": 1, "maxItems": 20, "default": [ 0, 1, 2, 3 ] }, "digit_position": { "type": "string", "enum": [ "end", "start", "mixed" ], "default": "end" }, "avoid_ambiguous_digits": { "type": "boolean", "default": false, "description": "Exclude 0 and 1 from generated digits. Does not alter names or custom affixes." }, "prefix": { "type": "string", "pattern": "^[A-Za-z0-9]{0,8}$", "default": "" }, "suffix": { "type": "string", "pattern": "^[A-Za-z0-9]{0,8}$", "default": "" }, "max_length": { "type": "integer", "minimum": 3, "maximum": 32, "default": 32 }, "custom_first_names": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z]{2,20}$" }, "maxItems": 200, "default": [] }, "custom_last_names": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z]{2,20}$" }, "maxItems": 200, "default": [] }, "domain_distribution": { "type": "string", "enum": [ "random", "balanced" ], "default": "random" } }, "additionalProperties": false, "description": "Optional generation controls for mode=generate. Missing fields use defaults. ASCII names/affixes are trimmed and lowercased. Each nonempty custom list replaces that side of the selected pool; custom names and affixes require custom-alias permission. A chosen separator joins affixes and name components; digits attach directly at the start or end and may include leading zeros. Feasible combinations honor max_length without truncation. Balanced distribution aims for equal counts per selected domain; constrained or unavailable choices may produce a partial result." }, "NamePoolStats": { "type": "object", "properties": { "name_pool": { "type": "string", "enum": [ "all", "english", "international", "arabic" ] }, "first_count": { "type": "integer", "minimum": 0 }, "last_count": { "type": "integer", "minimum": 0 }, "custom_first_count": { "type": "integer", "minimum": 0 }, "custom_last_count": { "type": "integer", "minimum": 0 } } }, "BulkResult": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PreviewItem" } }, "summary": { "type": "object", "additionalProperties": { "type": "integer" } }, "create_chunk_size": { "type": "integer", "enum": [ 20 ] }, "max_batch_size": { "type": "integer", "enum": [ 500 ] }, "generation": { "$ref": "#/components/schemas/GenerationOptions" }, "name_pool_stats": { "$ref": "#/components/schemas/NamePoolStats" } } }, "Message": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "from_name": { "type": "string" }, "from_email": { "type": "string" }, "subject": { "type": "string" }, "preview": { "type": "string" }, "received_at": { "type": "string", "format": "date-time" }, "is_read": { "type": "boolean" }, "verification_code": { "type": [ "string", "null" ] }, "text_body": { "type": "string" }, "html_body": { "type": "string" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "mime_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "content_id": { "type": [ "string", "null" ], "description": "Embedded raster image Content-ID; fetch its attachment using the same private inbox headers." } } } } }, "required": [ "id", "subject", "is_read" ] }, "MessageList": { "type": "object", "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } }, "inbox": { "$ref": "#/components/schemas/Inbox" }, "pagination": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" }, "total": { "type": "integer" } }, "required": [ "next_cursor", "has_more", "total" ] }, "unread_count": { "type": "integer", "description": "Unread count within the current filters." }, "fetch": { "$ref": "#/components/schemas/Fetch" } }, "required": [ "messages", "pagination" ] }, "Fetch": { "type": "object", "properties": { "attempted": { "type": "boolean" }, "skipped": { "type": "boolean" }, "locked": { "type": "boolean" }, "failed": { "type": "boolean" } } }, "Outgoing": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "to": { "type": "string" }, "from": { "type": "string" }, "reply_to": { "type": "string" }, "subject": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "sending", "sent", "failed", "uncertain", "cancelled" ], "description": "sent means SMTP accepted the message, not confirmed delivery. uncertain is never automatically retried." }, "attempts": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "accepted_at": { "type": [ "string", "null" ], "format": "date-time" }, "next_attempt_at": { "type": [ "string", "null" ], "format": "date-time" }, "error": { "type": [ "string", "null" ] }, "has_html": { "type": "boolean" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "filename": { "type": "string" }, "content_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "disposition": { "enum": [ "attachment", "inline" ] }, "content_id": { "type": [ "string", "null" ] } } } } }, "required": [ "id", "status" ] }, "Error": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "properties": { "request_id": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "ok", "error" ] }, "CreateInbox": { "type": "object", "properties": { "action": { "const": "create_inbox" }, "alias": { "type": "string", "maxLength": 32 }, "domain": { "type": "string" }, "request_key": { "type": "string", "pattern": "^[a-f0-9]{64}$", "writeOnly": true, "description": "Generate 32 random bytes as lowercase hex, save before creation and reuse for interrupted requests. Keep private." }, "proof": { "type": "string" }, "access_password": { "type": "string", "maxLength": 1024, "writeOnly": true }, "lifetime_seconds": { "type": "integer", "enum": [ 0, 3600, 86400, 259200, 604800, 2592000 ], "description": "Choose a value returned by domains.lifetime_options; 0 requests unlimited when permitted. The access plan and site limits apply." } }, "required": [ "alias", "domain", "request_key" ] }, "BulkPreview": { "type": "object", "properties": { "action": { "const": "bulk_preview" }, "mode": { "enum": [ "generate", "import" ], "default": "import" }, "entries": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 500 }, "count": { "type": "integer", "minimum": 1, "maximum": 500 }, "domains": { "type": "array", "items": { "type": "string" }, "maxItems": 500 }, "generation": { "$ref": "#/components/schemas/GenerationOptions" }, "access_password": { "type": "string", "maxLength": 1024, "writeOnly": true }, "lifetime_seconds": { "type": "integer", "enum": [ 0, 3600, 86400, 259200, 604800, 2592000 ], "description": "Choose a value returned by domains.lifetime_options; 0 requests unlimited when permitted. The access plan and site limits apply." } } }, "BulkCreate": { "type": "object", "properties": { "action": { "const": "bulk_create" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PreviewItem" }, "minItems": 1, "maxItems": 20 }, "request_key": { "type": "string", "pattern": "^[a-f0-9]{64}$", "writeOnly": true, "description": "Generate 32 random bytes as lowercase hex, save before creation and reuse for interrupted requests. Keep private." }, "access_password": { "type": "string", "maxLength": 1024, "writeOnly": true }, "lifetime_seconds": { "type": "integer", "enum": [ 0, 3600, 86400, 259200, 604800, 2592000 ], "description": "Choose a value returned by domains.lifetime_options; 0 requests unlimited when permitted. The access plan and site limits apply." } }, "required": [ "items", "request_key" ] }, "QueryMessages": { "type": "object", "properties": { "action": { "enum": [ "messages", "verification_code" ] }, "q": { "type": "string", "maxLength": 200, "description": "Literal text search in sender, subject and stored text/HTML body; maximum 200 UTF-8 bytes." }, "from": { "type": "string", "maxLength": 320, "description": "Literal sender text; maximum 320 UTF-8 bytes." }, "read": { "type": "string", "enum": [ "all", "read", "unread" ], "default": "all" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "cursor": { "type": "string", "description": "Opaque next_cursor from the previous page; retain the same filters." }, "fetch": { "type": "boolean" } } }, "QueryMessage": { "type": "object", "properties": { "action": { "const": "message" }, "message_id": { "type": "string", "format": "uuid" }, "mark_read": { "type": "boolean" } }, "required": [ "message_id" ] }, "MarkMessages": { "type": "object", "properties": { "action": { "const": "mark_messages" }, "message_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 100 }, "is_read": { "type": "boolean" } }, "required": [ "message_ids", "is_read" ] }, "Send": { "type": "object", "properties": { "action": { "const": "send" }, "to": { "type": "string", "format": "email", "maxLength": 254 }, "subject": { "type": "string", "minLength": 1, "maxLength": 200 }, "text": { "type": "string", "minLength": 1, "description": "Required plain-text alternative, at most 50,000 UTF-8 bytes." }, "request_key": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,128}$", "description": "Save before sending. Reuse with exactly the same message on retry. idempotency_key or Idempotency-Key header are aliases." }, "html": { "type": "string", "description": "Optional UTF-8 HTML, maximum 200,000 bytes before and after server sanitization. Supply text as its plain alternative." }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/OutgoingAttachment" }, "maxItems": 5, "description": "Up to five files, including inline images, with a combined decoded limit of 5 MiB." } }, "required": [ "to", "subject", "text", "request_key" ] }, "CancelSend": { "type": "object", "properties": { "action": { "const": "cancel_send" }, "id": { "type": "string", "format": "uuid" } }, "required": [ "id" ] }, "DeleteMessage": { "type": "object", "properties": { "action": { "const": "delete_message" }, "message_id": { "type": "string", "format": "uuid" } }, "required": [ "message_id" ] }, "DeleteInbox": { "type": "object", "properties": { "action": { "const": "delete_inbox" } } }, "DomainsRequest": { "type": "object", "properties": { "action": { "const": "domains" }, "access_password": { "type": "string", "maxLength": 1024, "writeOnly": true } } }, "OutgoingAttachment": { "type": "object", "properties": { "filename": { "type": "string", "minLength": 1, "maxLength": 255, "description": "At most 255 UTF-8 bytes; no control characters or path separators." }, "content_type": { "type": "string", "description": "Declared MIME type; image bytes are independently checked." }, "content_base64": { "type": "string", "contentEncoding": "base64", "description": "Standard base64 bytes, no data URL prefix. At most 5 MiB decoded across all files." }, "disposition": { "type": "string", "enum": [ "attachment", "inline" ], "default": "attachment" }, "content_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}@omailo$", "description": "Required for inline PNG/JPEG/GIF/WebP images. Reference in html as cid:." } }, "required": [ "filename", "content_type", "content_base64" ], "additionalProperties": false } } }, "x-actions": { "capabilities": { "methods": [ "GET" ], "scope": null, "inbox_credentials_required": false, "response_data": { "type": "object", "properties": { "api_version": { "type": "string" }, "service_version": { "type": "string" }, "actions": { "type": "object" }, "limits": { "type": "object" } } } }, "domains": { "methods": [ "GET", "POST" ], "scope": "inboxes:create", "inbox_credentials_required": false, "response_data": { "type": "object", "description": "Access context including domains and permitted lifetime_options." }, "request_schema": { "$ref": "#/components/schemas/DomainsRequest" } }, "inbox": { "methods": [ "GET" ], "scope": "inboxes:read", "inbox_credentials_required": true, "response_data": { "type": "object", "properties": { "inbox": { "$ref": "#/components/schemas/Inbox" } } } }, "inbox_controls": { "methods": [ "GET", "POST" ], "scope": "inboxes:read", "inbox_credentials_required": true, "response_data": { "$ref": "#/components/schemas/InboxControls" }, "request_schema": { "$ref": "#/components/schemas/InboxControlsUpdate" }, "scope_by_method": { "GET": "inboxes:read", "POST": "inboxes:write" }, "note": "POST requires inboxes:write plus private inbox credentials. Expiry follows the original access plan and admin limits. Enabling browser SMTP requires verified admin permission; API-key sending retains its independent messages:send scope." }, "create_inbox": { "methods": [ "POST" ], "scope": "inboxes:create", "inbox_credentials_required": false, "response_data": { "type": "object", "properties": { "inbox": { "$ref": "#/components/schemas/Inbox" }, "recovered": { "type": "boolean" } } }, "request_schema": { "$ref": "#/components/schemas/CreateInbox" } }, "bulk_preview": { "methods": [ "POST" ], "scope": "inboxes:create", "inbox_credentials_required": false, "response_data": { "$ref": "#/components/schemas/BulkResult" }, "request_schema": { "$ref": "#/components/schemas/BulkPreview" }, "note": "Inspect every row status; preview does not reserve addresses. Generated proofs expire after 30 minutes." }, "bulk_create": { "methods": [ "POST" ], "scope": "inboxes:create", "inbox_credentials_required": false, "response_data": { "$ref": "#/components/schemas/BulkResult" }, "request_schema": { "$ref": "#/components/schemas/BulkCreate" }, "note": "Inspect every row status; preview does not reserve addresses. Generated proofs expire after 30 minutes." }, "messages": { "methods": [ "GET", "POST" ], "scope": "messages:read", "inbox_credentials_required": true, "response_data": { "$ref": "#/components/schemas/MessageList" }, "request_schema": { "$ref": "#/components/schemas/QueryMessages" } }, "message": { "methods": [ "GET", "POST" ], "scope": "messages:read", "inbox_credentials_required": true, "response_data": { "type": "object", "properties": { "message": { "$ref": "#/components/schemas/Message" } } }, "request_schema": { "$ref": "#/components/schemas/QueryMessage" }, "note": "POST mark_read:true additionally requires messages:write; reads otherwise do not mark mail." }, "mark_messages": { "methods": [ "POST" ], "scope": "messages:write", "inbox_credentials_required": true, "response_data": { "type": "object", "properties": { "updated": { "type": "integer" } } }, "request_schema": { "$ref": "#/components/schemas/MarkMessages" } }, "verification_code": { "methods": [ "GET", "POST" ], "scope": "messages:read", "inbox_credentials_required": true, "response_data": { "type": "object", "properties": { "found": { "type": "boolean" }, "code": { "type": [ "string", "null" ] }, "confidence": { "type": "number" }, "message": { "type": [ "object", "null" ] }, "checked": { "type": "integer" }, "scan_limit": { "type": "integer", "enum": [ 25 ] }, "fetch": { "$ref": "#/components/schemas/Fetch" } } }, "request_schema": { "$ref": "#/components/schemas/QueryMessages" } }, "delete_inbox": { "methods": [ "POST" ], "scope": "inboxes:delete", "inbox_credentials_required": true, "response_data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } }, "request_schema": { "$ref": "#/components/schemas/DeleteInbox" } }, "delete_message": { "methods": [ "POST" ], "scope": "messages:write", "inbox_credentials_required": true, "response_data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } }, "request_schema": { "$ref": "#/components/schemas/DeleteMessage" } }, "send": { "methods": [ "POST" ], "scope": "messages:send", "inbox_credentials_required": true, "response_data": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/Outgoing" } } }, "request_schema": { "$ref": "#/components/schemas/Send" }, "note": "Requires verified SMTP, messages:send, private inbox credentials and the original access-password SMTP permission. A developer key does not bypass a denied plan. Save the request key and reuse the complete exact payload after an uncertain request." }, "outbox": { "methods": [ "GET" ], "scope": "messages:send", "inbox_credentials_required": true, "response_data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Outgoing" }, "maxItems": 100 } } } }, "cancel_send": { "methods": [ "POST" ], "scope": "messages:send", "inbox_credentials_required": true, "response_data": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/Outgoing" } } }, "request_schema": { "$ref": "#/components/schemas/CancelSend" } } } }