{ "openapi": "3.1.0", "info": { "title": "ims \u2014 Incoming mail server", "version": "0.2.1", "description": "SMTP receive-only mailboxes for developers and agents. All authenticated tokens share the mailbox pool. Agent tokens cannot mutate domains. Original messages are stored durably before SMTP 250. The server does not send or relay mail." }, "servers": [ { "url": "https://ims.d1cloud.io" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/api/v1/me": { "get": { "operationId": "get_me", "summary": "Inspect token capabilities", "description": "Inspect token capabilities", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Identity" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Duplicate, nonempty resource or quota below usage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/domains": { "get": { "operationId": "get_domains", "summary": "List configured domains", "description": "List configured domains", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Domain" } } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Duplicate, nonempty resource or quota below usage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post_domains", "summary": "Create a domain", "description": "Create a domain Requires an operator token.", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Duplicate, nonempty resource or quota below usage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Content-Type must be application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "example": { "name": "example.org" } } } } } }, "/api/v1/domains/{domain}": { "get": { "operationId": "get_domains_domain", "summary": "Get a domain", "description": "Get a domain", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Duplicate, nonempty resource or quota below usage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "Name or ID", "schema": { "type": "string" } } ] }, "patch": { "operationId": "patch_domains_domain", "summary": "Update a domain", "description": "Rename or enable/disable a domain. Renaming changes mailbox addresses and does not alter DNS. Requires an operator token.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Duplicate, nonempty resource or quota below usage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Content-Type must be application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "Name or ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "enabled": { "type": "boolean" } }, "additionalProperties": false }, "example": { "enabled": false } } } } }, "delete": { "operationId": "delete_domains_domain", "summary": "Delete a domain", "description": "Delete a domain Requires an operator token. All path references must be immutable UUIDs v4; names and addresses are rejected.", "responses": { "204": { "description": "Deleted" }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Duplicate, nonempty resource or quota below usage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "Immutable UUID v4 (required for deletion)", "schema": { "type": "string", "format": "uuid" } }, { "name": "cascade", "in": "query", "description": "Also delete all mailboxes and messages. Required for nonempty domains.", "schema": { "type": "boolean", "default": false } } ] } }, "/api/v1/mailboxes": { "get": { "operationId": "get_mailboxes", "summary": "List mailboxes", "description": "List mailboxes", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Mailbox" } } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Duplicate, nonempty resource or quota below usage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "domain", "in": "query", "description": "Filter by domain name or ID", "schema": { "type": "string" } } ] }, "post": { "operationId": "post_mailboxes", "summary": "Create a mailbox", "description": "Create on a configured domain. Local parts are case-insensitive ASCII dot-atoms. Default quota is 512 MiB; limit must not exceed the server storage cap. For backward-compatible defaulting, zero is treated as omitted when creating.", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Mailbox" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Duplicate, nonempty resource or quota below usage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Content-Type must be application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string" }, "local_part": { "type": "string", "maxLength": 64 }, "name": { "type": "string", "maxLength": 200 }, "quota_bytes": { "type": "integer", "minimum": 1, "default": 536870912 } }, "required": [ "domain", "local_part" ], "additionalProperties": false }, "example": { "domain": "opolo.de", "local_part": "signup-42", "quota_bytes": 536870912 } } } } } }, "/api/v1/mailboxes/{mailbox}": { "get": { "operationId": "get_mailboxes_mailbox", "summary": "Get a mailbox and quota usage", "description": "Get a mailbox and quota usage", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Mailbox" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Duplicate, nonempty resource or quota below usage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "mailbox", "in": "path", "required": true, "description": "Email address or ID", "schema": { "type": "string" } } ] }, "patch": { "operationId": "patch_mailboxes_mailbox", "summary": "Update a mailbox", "description": "Change local part, description, enabled state or byte quota. Quota cannot be lower than current usage; original messages remain after rename.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Mailbox" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Duplicate, nonempty resource or quota below usage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Content-Type must be application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "mailbox", "in": "path", "required": true, "description": "Email address or ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "local_part": { "type": "string", "maxLength": 64 }, "name": { "type": "string", "maxLength": 200 }, "enabled": { "type": "boolean" }, "quota_bytes": { "type": "integer", "minimum": 1 } }, "additionalProperties": false }, "example": { "quota_bytes": 1073741824 } } } } }, "delete": { "operationId": "delete_mailboxes_mailbox", "summary": "Delete mailbox and all messages", "description": "Delete mailbox and all messages All path references must be immutable UUIDs v4; names and addresses are rejected.", "responses": { "204": { "description": "Deleted" }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Duplicate, nonempty resource or quota below usage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "mailbox", "in": "path", "required": true, "description": "Immutable UUID v4 (required for deletion)", "schema": { "type": "string", "format": "uuid" } } ] } }, "/api/v1/mailboxes/{mailbox}/messages": { "get": { "operationId": "get_mailboxes_mailbox_messages", "summary": "List messages", "description": "Newest first, then ID descending. Listings are not a snapshot; new arrivals may shift offsets. GET does not change read state.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageList" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Duplicate, nonempty resource or quota below usage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "mailbox", "in": "path", "required": true, "description": "Email address or ID", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "description": "Offset into newest-first results", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "unread", "in": "query", "description": "Only unread messages", "schema": { "type": "boolean", "default": false } }, { "name": "since", "in": "query", "description": "Inclusive lower bound on received_at", "schema": { "type": "string", "format": "date-time" } }, { "name": "subject", "in": "query", "description": "Case-insensitive substring in decoded subject", "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "Case-insensitive substring in decoded From header", "schema": { "type": "string" } } ] }, "delete": { "operationId": "delete_mailboxes_mailbox_messages", "summary": "Purge all mailbox messages", "description": "Purge all mailbox messages All path references must be immutable UUIDs v4; names and addresses are rejected.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "integer" } }, "required": [ "deleted" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Duplicate, nonempty resource or quota below usage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "mailbox", "in": "path", "required": true, "description": "Immutable UUID v4 (required for deletion)", "schema": { "type": "string", "format": "uuid" } } ] } }, "/api/v1/mailboxes/{mailbox}/messages/{message}": { "get": { "operationId": "get_mailboxes_mailbox_messages_message", "summary": "Read a message", "description": "Decode text, HTML, headers and attachment metadata. Does not mark read. HTML is untrusted text, not a rendered document. A parse_warning preserves access to malformed original mail.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageDetail" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Duplicate, nonempty resource or quota below usage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "mailbox", "in": "path", "required": true, "description": "Email address or ID", "schema": { "type": "string" } }, { "name": "message", "in": "path", "required": true, "description": "Message ID", "schema": { "type": "string" } } ] }, "patch": { "operationId": "patch_mailboxes_mailbox_messages_message", "summary": "Mark read or unread", "description": "Set read state explicitly. Repeated mark-read preserves the first read_at timestamp. Mark-unread clears read_at. Not an exclusive work claim.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Duplicate, nonempty resource or quota below usage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Content-Type must be application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "mailbox", "in": "path", "required": true, "description": "Email address or ID", "schema": { "type": "string" } }, { "name": "message", "in": "path", "required": true, "description": "Message ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "read": { "type": "boolean" } }, "required": [ "read" ], "additionalProperties": false }, "example": { "read": true } } } } }, "delete": { "operationId": "delete_mailboxes_mailbox_messages_message", "summary": "Delete one message", "description": "Delete one message All path references must be immutable UUIDs v4; names and addresses are rejected.", "responses": { "204": { "description": "Deleted" }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Duplicate, nonempty resource or quota below usage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "mailbox", "in": "path", "required": true, "description": "Immutable UUID v4 (required for deletion)", "schema": { "type": "string", "format": "uuid" } }, { "name": "message", "in": "path", "required": true, "description": "Immutable UUID v4 (required for deletion)", "schema": { "type": "string", "format": "uuid" } } ] } }, "/api/v1/mailboxes/{mailbox}/messages/{message}/raw": { "get": { "operationId": "get_mailboxes_mailbox_messages_message_raw", "summary": "Download original .eml", "description": "Download original .eml", "responses": { "200": { "description": "Success", "content": { "message/rfc822": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Duplicate, nonempty resource or quota below usage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "mailbox", "in": "path", "required": true, "description": "Email address or ID", "schema": { "type": "string" } }, { "name": "message", "in": "path", "required": true, "description": "Message ID", "schema": { "type": "string" } } ] } }, "/api/v1/mailboxes/{mailbox}/messages/{message}/attachments/{index}": { "get": { "operationId": "get_mailboxes_mailbox_messages_message_attachments_index", "summary": "Download attachment", "description": "Download attachment", "responses": { "200": { "description": "Success", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Duplicate, nonempty resource or quota below usage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "mailbox", "in": "path", "required": true, "description": "Email address or ID", "schema": { "type": "string" } }, { "name": "message", "in": "path", "required": true, "description": "Message ID", "schema": { "type": "string" } }, { "name": "index", "in": "path", "required": true, "description": "Zero-based attachment index", "schema": { "type": "integer", "minimum": 0 } } ] } }, "/api/v1/operator/overview": { "get": { "operationId": "get_operator_overview", "summary": "Operator installation overview", "description": "Operator installation overview Requires an operator token.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Overview" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Duplicate, nonempty resource or quota below usage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/audit-logs": { "get": { "operationId": "get_audit-logs", "summary": "List AuditLog entries", "description": "Operator-only persistent history, limited to 100,000 entries and 30 days per log. Deleted resource UUIDs remain in history. Audit entries omit request bodies, query strings and bearer tokens. Successful operator log/overview polling is not audited. Email log covers backend recipient rejection and DATA completion; protocol errors before the backend are excluded. No historical backfill. Requires an operator token.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AuditLog" } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "has_more": { "type": "boolean" } }, "required": [ "data", "total", "limit", "offset", "has_more" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Duplicate, nonempty resource or quota below usage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "limit", "in": "query", "description": "Page size", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "description": "Newest-first offset", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "since", "in": "query", "description": "RFC 3339 lower bound", "schema": { "type": "string", "format": "date-time" } }, { "name": "search", "in": "query", "description": "Case-insensitive substring search", "schema": { "type": "string", "maxLength": 200 } }, { "name": "role", "in": "query", "description": "Filter role", "schema": { "type": "string", "enum": [ "agent", "operator", "unauthenticated" ] } } ] } }, "/api/v1/email-logs": { "get": { "operationId": "get_email-logs", "summary": "List EmailLog entries", "description": "Operator-only persistent history, limited to 100,000 entries and 30 days per log. Deleted resource UUIDs remain in history. Audit entries omit request bodies, query strings and bearer tokens. Successful operator log/overview polling is not audited. Email log covers backend recipient rejection and DATA completion; protocol errors before the backend are excluded. No historical backfill. Requires an operator token.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EmailLog" } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "has_more": { "type": "boolean" } }, "required": [ "data", "total", "limit", "offset", "has_more" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Duplicate, nonempty resource or quota below usage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "limit", "in": "query", "description": "Page size", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "description": "Newest-first offset", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "since", "in": "query", "description": "RFC 3339 lower bound", "schema": { "type": "string", "format": "date-time" } }, { "name": "search", "in": "query", "description": "Case-insensitive substring search", "schema": { "type": "string", "maxLength": 200 } }, { "name": "outcome", "in": "query", "description": "Filter SMTP outcome", "schema": { "type": "string", "enum": [ "accepted", "rejected", "deferred" ] } } ] } }, "/healthz": { "get": { "operationId": "health", "summary": "Public service health", "security": [], "responses": { "200": { "description": "SMTP ready and database reachable", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "version": { "type": "string" }, "smtp": { "type": "string" }, "database": { "type": "string" } }, "additionalProperties": false } } } }, "503": { "description": "Service unavailable" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } }, "schemas": { "Domain": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "created_at": { "type": "string" } }, "required": [ "id", "name", "enabled", "created_at" ], "additionalProperties": false }, "Mailbox": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "domain_id": { "type": "string", "format": "uuid" }, "address": { "type": "string" }, "local_part": { "type": "string" }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "created_at": { "type": "string" }, "quota_bytes": { "type": "integer" }, "used_bytes": { "type": "integer" }, "message_count": { "type": "integer" } }, "required": [ "id", "domain_id", "address", "local_part", "name", "enabled", "created_at", "quota_bytes", "used_bytes", "message_count" ], "additionalProperties": false }, "Message": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "mailbox_id": { "type": "string", "format": "uuid" }, "envelope_from": { "type": "string" }, "envelope_to": { "type": "string" }, "subject": { "type": "string" }, "from": { "type": "string" }, "received_at": { "type": "string" }, "size": { "type": "integer" }, "is_read": { "type": "boolean" }, "read_at": { "type": "string" } }, "required": [ "id", "mailbox_id", "envelope_from", "envelope_to", "subject", "from", "received_at", "size", "is_read" ], "additionalProperties": false }, "Attachment": { "type": "object", "properties": { "index": { "type": "integer" }, "filename": { "type": "string" }, "content_type": { "type": "string" }, "size": { "type": "integer" } }, "required": [ "index", "filename", "content_type", "size" ], "additionalProperties": false }, "MessageDetail": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "mailbox_id": { "type": "string", "format": "uuid" }, "envelope_from": { "type": "string" }, "envelope_to": { "type": "string" }, "subject": { "type": "string" }, "from": { "type": "string" }, "received_at": { "type": "string" }, "size": { "type": "integer" }, "is_read": { "type": "boolean" }, "read_at": { "type": "string" }, "text": { "type": "string" }, "html": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/Attachment" } }, "parse_warning": { "type": "string" } }, "required": [ "id", "mailbox_id", "envelope_from", "envelope_to", "subject", "from", "received_at", "size", "is_read", "text", "html", "headers", "attachments" ], "additionalProperties": false }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false }, "Identity": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "agent", "operator" ] }, "capabilities": { "type": "array", "items": { "type": "string" } } }, "required": [ "role", "capabilities" ], "additionalProperties": false }, "MessageList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "has_more": { "type": "boolean" } }, "required": [ "data", "total", "limit", "offset", "has_more" ], "additionalProperties": false }, "AuditLog": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "role": { "type": "string" }, "token_id": { "type": "string" }, "method": { "type": "string" }, "path": { "type": "string" }, "status": { "type": "integer" }, "resource_id": { "type": "string" }, "user_agent": { "type": "string" }, "duration_ms": { "type": "integer" } }, "additionalProperties": false, "required": [ "id", "created_at", "role", "token_id", "method", "path", "status", "resource_id", "user_agent", "duration_ms" ] }, "EmailLog": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "outcome": { "type": "string" }, "stage": { "type": "string" }, "smtp_code": { "type": "integer" }, "reason": { "type": "string" }, "envelope_from": { "type": "string" }, "envelope_to": { "type": "string" }, "mailbox_id": { "type": "string" }, "message_id": { "type": "string" }, "size": { "type": "integer" }, "remote_ip": { "type": "string" }, "tls": { "type": "boolean" } }, "additionalProperties": false, "required": [ "id", "created_at", "outcome", "stage", "smtp_code", "reason", "envelope_from", "envelope_to", "mailbox_id", "message_id", "size", "remote_ip", "tls" ] }, "Overview": { "type": "object", "properties": { "max_storage_bytes": { "type": "integer" }, "log_retention_days": { "type": "integer" }, "log_max_entries": { "type": "integer" }, "domains": { "type": "integer" }, "mailboxes": { "type": "integer" }, "messages": { "type": "integer" }, "unread": { "type": "integer" }, "used_bytes": { "type": "integer" }, "smtp_accepted_24h": { "type": "integer" }, "smtp_rejected_24h": { "type": "integer" }, "smtp_deferred_24h": { "type": "integer" }, "version": { "type": "string" } }, "additionalProperties": false } } } }