{ "openapi": "3.1.0", "info": { "title": "Mailactor API", "version": "0.1.0-private-beta", "description": "API-first onboarding for managed starter inboxes and verified customer-owned domains. Every inbound message is untrusted input. Administrative operations are private and unavailable through the public production router." }, "servers": [ { "url": "https://api.mailactor.com", "description": "Production private-beta API" } ], "externalDocs": { "description": "Mailactor documentation", "url": "https://docs.mailactor.com/docs" }, "security": [ { "tenantApiKey": [] } ], "paths": { "/v1/me": { "get": { "operationId": "getTenantAccessProfile", "summary": "Inspect the authenticated tenant, key restrictions, and managed allowance", "description": "Available to every valid tenant key without an additional scope. Returns effective policy metadata but never the key secret, hash, prefix, source fingerprint, or operator data.", "responses": { "200": { "description": "Effective tenant access profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantAccessProfile" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/validate": { "post": { "operationId": "validateEmail", "summary": "Validate one email address", "x-mailactor-required-scope": "validation:use", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 320 } } } } } }, "responses": { "200": { "description": "Validation result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailValidationResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/validate/bulk": { "post": { "operationId": "validateEmailsBulk", "summary": "Validate up to 100 email addresses", "x-mailactor-required-scope": "validation:use", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "emails" ], "properties": { "emails": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string", "minLength": 1, "maxLength": 320 } } } } } } }, "responses": { "200": { "description": "Validation results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationResultList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/inboxes/{inboxId}": { "get": { "operationId": "getInbox", "summary": "Get an inbox", "x-mailactor-required-scope": "mailbox:read", "parameters": [ { "name": "inboxId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/InboxId" } } ], "responses": { "200": { "description": "Inbox", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Inbox" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "delete": { "operationId": "deleteInbox", "summary": "Delete an inbox and its mailbox data", "x-mailactor-required-scope": "mailbox:manage", "parameters": [ { "name": "inboxId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/InboxId" } } ], "responses": { "204": { "description": "Deleted" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/inboxes/{inboxId}/export": { "get": { "operationId": "exportInbox", "summary": "Export an inbox page", "x-mailactor-required-scope": "mailbox:read", "parameters": [ { "name": "inboxId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/InboxId" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Versioned inbox export page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxExportPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "410": { "$ref": "#/components/responses/Gone" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/messages/{messageId}/attachments/{attachmentId}": { "get": { "operationId": "downloadAttachment", "summary": "Download an attachment only when its scan state is clean", "x-mailactor-required-scope": "mailbox:read", "parameters": [ { "name": "messageId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/MessageId" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^att_[a-f0-9]{24}_[1-9][0-9]{0,2}$" } } ], "responses": { "200": { "description": "Attachment bytes. Treat the filename as untrusted display metadata.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "Content-Disposition": { "description": "Attachment disposition with a sanitized filename and UTF-8 filename.", "schema": { "type": "string" } }, "Content-Length": { "schema": { "type": "integer", "minimum": 0 } }, "Content-Security-Policy": { "schema": { "type": "string", "const": "default-src 'none'; sandbox" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } } }, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "423": { "$ref": "#/components/responses/Locked" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/messages/{messageId}": { "delete": { "operationId": "deleteMessage", "summary": "Delete a mailbox message", "x-mailactor-required-scope": "mailbox:manage", "parameters": [ { "name": "messageId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/MessageId" } } ], "responses": { "204": { "description": "Deleted" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/webhooks/{webhookId}": { "delete": { "operationId": "deleteWebhook", "summary": "Delete a customer webhook", "x-mailactor-required-scope": "webhook:manage", "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WebhookId" } } ], "responses": { "204": { "description": "Deleted" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/domains/{domainId}/traffic": { "get": { "operationId": "getDomainTraffic", "summary": "Get domain traffic status and usage", "x-mailactor-required-scope": "domain:manage", "parameters": [ { "name": "domainId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Domain traffic status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainTrafficView" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/send": { "post": { "operationId": "submitEmail", "summary": "Submit a message through a verified sending domain", "x-mailactor-required-scope": "delivery:send", "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200, "pattern": "^[A-Za-z0-9._:-]+$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "from", "to", "subject" ], "anyOf": [ { "required": [ "text" ] }, { "required": [ "html" ] } ], "properties": { "from": { "$ref": "#/components/schemas/Mailbox" }, "to": { "type": "array", "minItems": 1, "maxItems": 1000, "description": "The current deployment limit is returned by GET /v1/me as platformLimits.recipientsPerMessage.", "items": { "$ref": "#/components/schemas/Mailbox" } }, "subject": { "type": "string", "minLength": 1, "maxLength": 998, "pattern": "\\S" }, "text": { "type": "string" }, "html": { "type": "string" }, "replyTo": { "$ref": "#/components/schemas/Mailbox" }, "headers": { "type": "object", "additionalProperties": false, "maxProperties": 3, "properties": { "x-campaign": { "type": "string", "maxLength": 998, "pattern": "^[^\\r\\n]*$" }, "x-campaign-id": { "type": "string", "maxLength": 998, "pattern": "^[^\\r\\n]*$" }, "x-entity-ref-id": { "type": "string", "maxLength": 998, "pattern": "^[^\\r\\n]*$" } }, "description": "Only these three non-routing customer headers are accepted." }, "metadata": { "$ref": "#/components/schemas/Metadata" } } } } } }, "responses": { "202": { "description": "Durable delivery submission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliverySubmissionAccepted" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/submissions": { "get": { "operationId": "listSubmissions", "summary": "List delivery submissions", "x-mailactor-required-scope": "delivery:read", "responses": { "200": { "description": "Delivery submissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliverySubmissionList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/submissions/{submissionId}": { "get": { "operationId": "getSubmission", "summary": "Get a delivery submission", "x-mailactor-required-scope": "delivery:read", "parameters": [ { "name": "submissionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Delivery submission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliverySubmission" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/submissions/{submissionId}/events": { "get": { "operationId": "listSubmissionEvents", "summary": "List delivery events", "x-mailactor-required-scope": "delivery:read", "parameters": [ { "name": "submissionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Delivery events", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryEventList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/metrics/delivery": { "get": { "operationId": "getDeliveryMetrics", "summary": "Get delivery metrics", "x-mailactor-required-scope": "delivery:read", "parameters": [ { "name": "hours", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 720, "default": 24 } } ], "responses": { "200": { "description": "Delivery metrics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryHealthMetrics" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/suppressions": { "get": { "operationId": "listSuppressions", "summary": "List suppressions", "x-mailactor-required-scope": "delivery:read", "responses": { "200": { "description": "Suppressions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuppressionList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "post": { "operationId": "createSuppression", "summary": "Suppress an address", "x-mailactor-required-scope": "delivery:send", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 320 } } } } } }, "responses": { "201": { "description": "Suppression", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Suppression" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "delete": { "operationId": "deleteSuppression", "summary": "Remove an address suppression", "x-mailactor-required-scope": "delivery:send", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 320 } } } } } }, "responses": { "204": { "description": "Removed" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/complaints": { "get": { "operationId": "listComplaints", "summary": "List complaints", "x-mailactor-required-scope": "delivery:read", "responses": { "200": { "description": "Complaints", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComplaintList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/domains": { "post": { "operationId": "registerDomain", "summary": "Register a customer-owned domain", "x-mailactor-required-scope": "domain:manage", "description": "Returns TXT ownership, DKIM and MX instructions. Inbound and outbound capabilities verify independently.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "domain" ], "properties": { "domain": { "type": "string", "format": "hostname", "minLength": 1, "maxLength": 253, "description": "A fully qualified customer-owned hostname. Mailactor trims, removes one trailing dot, converts IDNs to ASCII, and lowercases it.", "example": "agents.example.com" } } } } } }, "responses": { "201": { "description": "Domain and DNS instructions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendingDomain" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "get": { "operationId": "listDomains", "summary": "List customer-owned domains", "x-mailactor-required-scope": "domain:manage", "responses": { "200": { "description": "Registered domains", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/domains/{domainId}": { "get": { "operationId": "getDomain", "summary": "Get a customer-owned domain", "x-mailactor-required-scope": "domain:manage", "parameters": [ { "name": "domainId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Domain and DNS instructions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendingDomain" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/domains/{domainId}/verify": { "post": { "operationId": "verifyDomain", "summary": "Check outbound and inbound DNS", "x-mailactor-required-scope": "domain:manage", "parameters": [ { "name": "domainId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Checks plus independent capabilities.outbound and capabilities.inbound results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainVerification" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/inboxes": { "post": { "operationId": "createInbox", "summary": "Create an inbox", "x-mailactor-required-scope": "mailbox:manage", "description": "Omit domainId for a managed starter address, or supply a verified customer-domain ID.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "localPart": { "type": "string", "pattern": "^(?!.*\\.\\.)[a-z0-9](?:[a-z0-9._-]{0,62}[a-z0-9])?$", "description": "Lowercase ASCII after normalization. Reserved operational local parts are rejected.", "example": "maurice" }, "displayName": { "type": "string", "minLength": 1, "maxLength": 200, "example": "Maurice" }, "domainId": { "type": "string", "format": "uuid" } } } } } }, "responses": { "201": { "description": "Created inbox", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Inbox" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "get": { "operationId": "listInboxes", "summary": "List inboxes", "x-mailactor-required-scope": "mailbox:read", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Cursor-paginated inboxes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/inboxes/{inboxId}/messages": { "post": { "operationId": "sendInboxMessage", "summary": "Send from an inbox", "x-mailactor-required-scope": "mailbox:send", "description": "Managed addresses have a deployment-configured lifetime starter allowance. Customer-domain inboxes do not use it.", "parameters": [ { "name": "inboxId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/InboxId" } }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200, "pattern": "^[A-Za-z0-9._:-]+$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "to", "subject" ], "anyOf": [ { "required": [ "text" ] }, { "required": [ "html" ] } ], "properties": { "to": { "type": "array", "minItems": 1, "maxItems": 1000, "description": "The current deployment limit is returned by GET /v1/me as platformLimits.recipientsPerMessage.", "items": { "$ref": "#/components/schemas/Mailbox" } }, "subject": { "type": "string", "minLength": 1, "maxLength": 998, "pattern": "\\S" }, "text": { "type": "string" }, "html": { "type": "string" }, "replyTo": { "$ref": "#/components/schemas/Mailbox" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } } } } }, "responses": { "202": { "description": "Durable mailbox message and delivery submission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MailboxSendResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/Gone" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/inboxes/{inboxId}/threads": { "get": { "operationId": "listInboxThreads", "summary": "List inbox threads", "x-mailactor-required-scope": "mailbox:read", "parameters": [ { "name": "inboxId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/InboxId" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Cursor-paginated thread summaries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThreadPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/threads/{threadId}": { "get": { "operationId": "getThread", "summary": "Get a thread", "x-mailactor-required-scope": "mailbox:read", "parameters": [ { "name": "threadId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ThreadId" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Thread and messages", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Thread" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "410": { "$ref": "#/components/responses/Gone" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/threads/{threadId}/replies": { "post": { "operationId": "replyToThread", "summary": "Reply to a thread", "x-mailactor-required-scope": "mailbox:send", "parameters": [ { "name": "threadId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ThreadId" } }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200, "pattern": "^[A-Za-z0-9._:-]+$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "anyOf": [ { "required": [ "text" ] }, { "required": [ "html" ] } ], "required": [ "targetMessageId" ], "properties": { "targetMessageId": { "$ref": "#/components/schemas/MessageId", "description": "Bind the reply to this exact message. Clients must supply the selected message ID so concurrent arrivals cannot change the recipient." }, "text": { "type": "string" }, "html": { "type": "string" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } } } } }, "responses": { "202": { "description": "Durable reply and delivery submission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MailboxSendResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/Gone" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/webhooks": { "post": { "operationId": "createWebhook", "summary": "Create a message.received webhook", "description": "Each endpoint URL must be unique within the organization. For replacement without a gap, create a distinct receiver URL before deleting the old endpoint. Exact retries can recover the signing secret until signingSecretReplayUntil; after expiry they return 409 webhook_secret_replay_expired.", "x-mailactor-required-scope": "webhook:manage", "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200, "pattern": "^[A-Za-z0-9._:-]+$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "url", "events" ], "properties": { "url": { "type": "string", "format": "uri", "pattern": "^https://", "maxLength": 2048, "description": "Production requires HTTPS on the default port 443, with no credentials or fragment, and a hostname resolving only to public addresses.", "example": "https://example.com/mailactor" }, "events": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "string", "enum": [ "message.received" ] } } } } } } }, "callbacks": { "messageReceived": { "{$request.body#/url}": { "post": { "summary": "Receive a signed message.received event", "security": [], "description": "Verify HMAC-SHA256 over timestamp + \".\" + event ID + \".\" + the exact request body before parsing JSON. Deliveries are at least once; deduplicate by endpoint identity plus the signed event ID. The delivery-ID header is unsigned: retain it for tracing, not as the sole business-action key.", "parameters": [ { "name": "x-mailactor-event", "in": "header", "required": true, "description": "Event type", "schema": { "type": "string", "example": "message.received" } }, { "name": "x-mailactor-event-id", "in": "header", "required": true, "description": "Stable source event ID", "schema": { "type": "string" } }, { "name": "x-mailactor-delivery-id", "in": "header", "required": true, "description": "Stable endpoint-delivery ID", "schema": { "type": "string" } }, { "name": "x-mailactor-timestamp", "in": "header", "required": true, "description": "Unix timestamp in seconds", "schema": { "type": "string" } }, { "name": "x-mailactor-signature", "in": "header", "required": true, "description": "HMAC signature formatted as v1=", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Accepted. Any 2xx status acknowledges the delivery." }, "204": { "description": "Durably accepted with no response body." } } } } } }, "responses": { "200": { "description": "Exact idempotent replay during the secret replay window", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreateResult" } } } }, "201": { "description": "Webhook and signing secret recoverable during the bounded replay window", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreateResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "Idempotency input conflict, endpoint URL already registered, or signing-secret replay expired. Inspect error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "The endpoint created by this idempotency key was deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "get": { "operationId": "listWebhooks", "summary": "List webhooks", "x-mailactor-required-scope": "webhook:manage", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook endpoints", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } } }, "components": { "schemas": { "TenantAccessProfile": { "type": "object", "additionalProperties": false, "required": [ "organization", "apiKey", "managedStarter", "platformLimits" ], "properties": { "organization": { "type": "object", "additionalProperties": false, "required": [ "id", "status", "sendLimits" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "active", "suspended", "deleting" ] }, "sendLimits": { "$ref": "#/components/schemas/TrafficLimits" } } }, "apiKey": { "unevaluatedProperties": false, "allOf": [ { "$ref": "#/components/schemas/ApiKeyRestrictions" }, { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" } } } ] }, "managedStarter": { "type": "object", "additionalProperties": false, "required": [ "limit", "used", "remaining" ], "properties": { "limit": { "type": "integer", "minimum": 1 }, "used": { "type": "integer", "minimum": 0 }, "remaining": { "type": "integer", "minimum": 0 } } }, "platformLimits": { "type": "object", "additionalProperties": false, "required": [ "recipientsPerMessage", "messageContentBytes", "inboxes", "domains", "webhookEndpoints" ], "properties": { "recipientsPerMessage": { "type": "integer", "minimum": 1, "maximum": 1000 }, "messageContentBytes": { "type": "integer", "minimum": 1, "maximum": 20000000 }, "inboxes": { "type": "integer", "minimum": 1, "maximum": 10000 }, "domains": { "type": "integer", "minimum": 1, "maximum": 1000 }, "webhookEndpoints": { "type": "integer", "minimum": 1, "maximum": 100 } } } } }, "TrafficLimits": { "type": "object", "additionalProperties": false, "required": [ "messagesPerMinute", "messagesPerDay", "recipientsPerDay" ], "properties": { "messagesPerMinute": { "type": "integer", "minimum": 1 }, "messagesPerDay": { "type": "integer", "minimum": 1 }, "recipientsPerDay": { "type": "integer", "minimum": 1 } } }, "ApiKeyRestrictions": { "type": "object", "required": [ "kind", "scopes", "inboxIds", "allowedIps", "sendMode", "allowedRecipientDomains", "expiresAt", "requestsPerMinute" ], "properties": { "kind": { "type": "string", "enum": [ "backend", "agent", "human" ] }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "*", "mailbox:read", "mailbox:send", "mailbox:manage", "delivery:read", "delivery:send", "validation:use", "webhook:manage", "domain:manage" ] } }, "inboxIds": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/InboxId" } }, "allowedIps": { "type": [ "array", "null" ], "items": { "oneOf": [ { "type": "string", "format": "ipv4" }, { "type": "string", "format": "ipv6" } ] } }, "sendMode": { "type": "string", "enum": [ "reply_only", "new_and_reply" ] }, "allowedRecipientDomains": { "type": [ "array", "null" ], "items": { "type": "string", "format": "hostname" } }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "requestsPerMinute": { "type": "integer", "minimum": 1, "maximum": 600 } } }, "InboxId": { "type": "string", "pattern": "^inb_[a-f0-9]{24}$", "example": "inb_0123456789abcdef01234567" }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code.", "examples": [ "invalid_request", "api_key_scope_denied" ] }, "message": { "type": "string", "description": "Human-readable diagnostic; do not branch on it." }, "retryable": { "type": "boolean", "description": "When present, whether retrying without changing the request can succeed." }, "action_required": { "type": "string", "description": "Stable remediation action, for example configure_customer_domain." }, "details": { "type": "array", "description": "Optional validation details. Shape may grow; branch on error instead.", "items": { "type": "object", "additionalProperties": true } }, "scope": { "type": "string", "enum": [ "ip", "tenant", "api_key", "global" ], "description": "Rate-limit dimension when error is api_rate_limit_exceeded." } }, "additionalProperties": false, "examples": [ { "error": "managed_starter_allowance_exhausted", "message": "The managed starter allowance is exhausted; configure a customer-owned domain", "retryable": false, "action_required": "configure_customer_domain" } ] }, "EmailValidationResult": { "type": "object", "additionalProperties": false, "required": [ "email", "normalizedEmail", "status", "reason", "checks", "mxHosts", "suggestion", "checkedAt", "expiresAt" ], "properties": { "email": { "type": "string" }, "normalizedEmail": { "type": [ "string", "null" ], "format": "email" }, "status": { "type": "string", "enum": [ "valid", "risky", "invalid", "unknown" ] }, "reason": { "type": "string" }, "checks": { "$ref": "#/components/schemas/ValidationChecks" }, "mxHosts": { "type": "array", "items": { "type": "string", "format": "hostname" } }, "suggestion": { "type": [ "string", "null" ] }, "checkedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" } } }, "ValidationChecks": { "type": "object", "additionalProperties": false, "required": [ "syntax", "domain", "asciiDomain", "mx", "implicitMx", "nullMx", "disposable", "roleAddress" ], "properties": { "syntax": { "type": "boolean" }, "domain": { "type": [ "string", "null" ] }, "asciiDomain": { "type": [ "string", "null" ] }, "mx": { "type": "boolean" }, "implicitMx": { "type": "boolean" }, "nullMx": { "type": "boolean" }, "disposable": { "type": "boolean" }, "roleAddress": { "type": "boolean" } } }, "ValidationResultList": { "type": "object", "additionalProperties": false, "required": [ "results" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/EmailValidationResult" } } } }, "Inbox": { "type": "object", "additionalProperties": false, "required": [ "id", "localPart", "domainId", "domainKind", "domain", "address", "displayName", "status", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/InboxId" }, "localPart": { "type": "string", "pattern": "^(?!.*\\.\\.)[a-z0-9](?:[a-z0-9._-]{0,62}[a-z0-9])?$", "description": "Normalized lowercase ASCII local part. Operational names such as admin, postmaster, abuse, security, support, and noreply are reserved.", "example": "maurice" }, "domainId": { "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "domainKind": { "type": "string", "enum": [ "managed", "customer" ] }, "domain": { "type": "string", "format": "hostname", "example": "inbox.mailactor.com" }, "address": { "type": "string", "format": "email", "example": "maurice@inbox.mailactor.com" }, "displayName": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "InboxExportPage": { "type": "object", "additionalProperties": false, "required": [ "formatVersion", "inbox", "messages", "nextCursor" ], "properties": { "formatVersion": { "const": 1 }, "inbox": { "$ref": "#/components/schemas/Inbox" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/MailboxMessage" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page. Null means the page is final." } } }, "MailboxMessage": { "type": "object", "additionalProperties": false, "required": [ "id", "inboxId", "threadId", "direction", "internetMessageId", "inReplyTo", "references", "from", "to", "subject", "metadata", "delivery", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/MessageId" }, "inboxId": { "$ref": "#/components/schemas/InboxId" }, "threadId": { "$ref": "#/components/schemas/ThreadId" }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ] }, "internetMessageId": { "type": "string" }, "inReplyTo": { "type": [ "string", "null" ] }, "references": { "type": "array", "items": { "type": "string" } }, "from": { "$ref": "#/components/schemas/Mailbox" }, "to": { "type": "array", "items": { "$ref": "#/components/schemas/Mailbox" } }, "subject": { "type": "string" }, "text": { "type": "string" }, "html": { "type": "string", "description": "Sanitized HTML for inbound messages." }, "replyTo": { "$ref": "#/components/schemas/Mailbox" }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "delivery": { "type": "object", "additionalProperties": false, "required": [ "submissionId", "status", "failureCode" ], "properties": { "submissionId": { "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "pending", "submitted", "failed", "received" ] }, "failureCode": { "type": [ "string", "null" ] } } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "attachments": { "type": "array", "description": "Attachment metadata. Use each item id with the owning message id for download; inboundSecurity.attachments is a policy state, not an identifier.", "items": { "$ref": "#/components/schemas/MailboxAttachment" } }, "inboundSecurity": { "$ref": "#/components/schemas/InboundSecurity" } } }, "MessageId": { "type": "string", "pattern": "^msg_[a-f0-9]{24}$", "example": "msg_0123456789abcdef01234567" }, "ThreadId": { "type": "string", "pattern": "^thr_[a-f0-9]{24}$", "example": "thr_0123456789abcdef01234567" }, "Mailbox": { "type": "object", "additionalProperties": false, "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 320 }, "name": { "type": "string", "minLength": 1, "maxLength": 200 } }, "examples": [ { "email": "recipient@example.com", "name": "Example Recipient" } ] }, "Metadata": { "type": "object", "maxProperties": 20, "propertyNames": { "minLength": 1, "maxLength": 100 }, "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "At most 20 string entries. Keys are 1-100 characters." }, "MailboxAttachment": { "type": "object", "additionalProperties": false, "required": [ "id", "filename", "contentType", "contentDisposition", "contentId", "size" ], "properties": { "id": { "type": "string", "pattern": "^att_[a-f0-9]{24}_[1-9][0-9]{0,2}$" }, "filename": { "type": "string" }, "contentType": { "type": "string" }, "contentDisposition": { "type": "string", "enum": [ "attachment", "inline" ] }, "contentId": { "type": [ "string", "null" ] }, "size": { "type": "integer", "minimum": 0 } } }, "InboundSecurity": { "type": "object", "additionalProperties": false, "required": [ "trust", "smtp", "authentication", "attachments" ], "properties": { "trust": { "const": "untrusted", "description": "Email content and claimed identity are adversarial input." }, "smtp": { "type": "object", "additionalProperties": false, "required": [ "remoteIp", "helo", "tls" ], "properties": { "remoteIp": { "oneOf": [ { "oneOf": [ { "type": "string", "format": "ipv4" }, { "type": "string", "format": "ipv6" } ] }, { "const": "unknown" } ] }, "helo": { "type": "string" }, "tls": { "type": "object", "additionalProperties": false, "required": [ "encrypted", "protocol", "cipher" ], "properties": { "encrypted": { "oneOf": [ { "const": true }, { "const": "unknown" } ] }, "protocol": { "type": "string" }, "cipher": { "type": "string" } } } } }, "authentication": { "type": "object", "additionalProperties": false, "required": [ "spf", "dkim", "dmarc" ], "properties": { "spf": { "const": "not_evaluated" }, "dkim": { "const": "not_evaluated" }, "dmarc": { "const": "not_evaluated" } } }, "attachments": { "type": "string", "enum": [ "unscanned", "clean", "quarantined" ] } } }, "WebhookId": { "type": "string", "pattern": "^whk_[a-f0-9]{24}$", "example": "whk_0123456789abcdef01234567" }, "DomainTrafficView": { "type": "object", "additionalProperties": false, "required": [ "domain", "effectiveLimits", "warmupStage", "usage", "health" ], "properties": { "domain": { "$ref": "#/components/schemas/SendingDomain" }, "effectiveLimits": { "$ref": "#/components/schemas/TrafficLimits" }, "warmupStage": { "type": [ "integer", "null" ], "minimum": 0 }, "usage": { "type": "object", "required": [ "tenant", "domain" ], "properties": { "tenant": { "$ref": "#/components/schemas/TrafficUsage" }, "domain": { "$ref": "#/components/schemas/TrafficUsage" }, "global": { "$ref": "#/components/schemas/TrafficUsage" } } }, "health": { "type": "object", "additionalProperties": false, "required": [ "window", "delivered", "bounced", "complaints", "rates" ], "properties": { "window": { "$ref": "#/components/schemas/TimeWindow" }, "delivered": { "type": "integer", "minimum": 0 }, "bounced": { "type": "integer", "minimum": 0 }, "complaints": { "type": "integer", "minimum": 0 }, "rates": { "type": "object", "required": [ "bounce", "complaint" ], "properties": { "bounce": { "type": "number" }, "complaint": { "type": "number" } } } } } } }, "SendingDomain": { "type": "object", "additionalProperties": false, "required": [ "id", "domain", "kind", "status", "inboundStatus", "dkimSelector", "trafficStatus", "trafficPauseReason", "trafficPausedAt", "trafficPolicy", "dnsRecords", "createdAt", "updatedAt", "verifiedAt", "inboundVerifiedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "domain": { "type": "string", "format": "hostname", "example": "agents.example.com" }, "kind": { "const": "customer" }, "status": { "type": "string", "enum": [ "pending", "verified" ], "description": "Outbound state. verified means ownership and DKIM both pass." }, "inboundStatus": { "type": "string", "enum": [ "pending", "verified" ], "description": "Inbound state. verified means ownership and MX both pass." }, "dkimSelector": { "type": "string" }, "trafficStatus": { "type": "string", "enum": [ "active", "paused", "automatically_paused" ] }, "trafficPauseReason": { "type": [ "string", "null" ] }, "trafficPausedAt": { "type": [ "string", "null" ], "format": "date-time" }, "trafficPolicy": { "$ref": "#/components/schemas/DomainTrafficPolicy" }, "dnsRecords": { "type": "array", "items": { "$ref": "#/components/schemas/DnsInstruction" }, "minItems": 3 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "inboundVerifiedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "DomainTrafficPolicy": { "type": "object", "additionalProperties": false, "required": [ "limits", "warmup", "automaticPause" ], "properties": { "limits": { "$ref": "#/components/schemas/TrafficLimits" }, "warmup": { "type": "object", "additionalProperties": false, "required": [ "enabled", "dailyCaps", "startedAt" ], "properties": { "enabled": { "type": "boolean" }, "dailyCaps": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "automaticPause": { "$ref": "#/components/schemas/AutomaticSuspensionThresholds" } } }, "AutomaticSuspensionThresholds": { "type": "object", "additionalProperties": false, "required": [ "minimumSampleSize", "bounceRate", "complaintRate" ], "properties": { "minimumSampleSize": { "type": "integer", "minimum": 1 }, "bounceRate": { "type": "number", "exclusiveMinimum": 0, "maximum": 1 }, "complaintRate": { "type": "number", "exclusiveMinimum": 0, "maximum": 1 } } }, "DnsInstruction": { "oneOf": [ { "$ref": "#/components/schemas/TxtDnsInstruction" }, { "$ref": "#/components/schemas/MxDnsInstruction" } ], "discriminator": { "propertyName": "type" } }, "TxtDnsInstruction": { "type": "object", "additionalProperties": false, "required": [ "type", "name", "value", "purpose" ], "properties": { "type": { "const": "TXT" }, "name": { "type": "string", "description": "Fully qualified DNS owner name." }, "value": { "type": "string", "description": "Publish exactly this TXT value." }, "purpose": { "type": "string", "enum": [ "ownership", "dkim" ] } }, "examples": [ { "type": "TXT", "name": "_mailactor.agents.example.com", "value": "ma_verify_REDACTED", "purpose": "ownership" } ] }, "MxDnsInstruction": { "type": "object", "additionalProperties": false, "required": [ "type", "name", "value", "priority", "purpose" ], "properties": { "type": { "const": "MX" }, "name": { "type": "string", "description": "Fully qualified DNS owner name." }, "value": { "type": "string", "description": "Mailactor inbound SMTP hostname." }, "priority": { "type": "integer", "minimum": 0, "maximum": 65535 }, "purpose": { "const": "inbound" } }, "examples": [ { "type": "MX", "name": "agents.example.com", "value": "mta1.mailactor.com", "priority": 10, "purpose": "inbound" } ] }, "TrafficUsage": { "type": "object", "additionalProperties": false, "required": [ "messagesThisMinute", "messagesToday", "recipientsToday" ], "properties": { "messagesThisMinute": { "type": "integer", "minimum": 0 }, "messagesToday": { "type": "integer", "minimum": 0 }, "recipientsToday": { "type": "integer", "minimum": 0 } } }, "TimeWindow": { "type": "object", "additionalProperties": false, "required": [ "since", "until" ], "properties": { "since": { "type": "string", "format": "date-time" }, "until": { "type": "string", "format": "date-time" } } }, "DeliverySubmissionAccepted": { "unevaluatedProperties": false, "allOf": [ { "$ref": "#/components/schemas/DeliverySubmission" }, { "type": "object", "required": [ "replayed" ], "properties": { "replayed": { "type": "boolean" } } } ] }, "DeliverySubmission": { "type": "object", "required": [ "id", "from", "recipients", "subject", "metadata", "status", "queueId", "response", "failureCode", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "from": { "$ref": "#/components/schemas/Mailbox" }, "recipients": { "type": "array", "items": { "$ref": "#/components/schemas/DeliveryRecipient" } }, "subject": { "type": "string" }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "status": { "type": "string", "enum": [ "pending", "queued", "deferred", "delivered", "partially_delivered", "bounced", "expired", "unknown", "failed" ] }, "queueId": { "type": [ "string", "null" ] }, "response": { "type": [ "string", "null" ] }, "failureCode": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "DeliveryRecipient": { "type": "object", "additionalProperties": false, "required": [ "email", "status", "response", "updatedAt" ], "properties": { "email": { "type": "string", "format": "email" }, "status": { "type": "string", "enum": [ "pending", "queued", "deferred", "delivered", "bounced", "expired", "unknown" ] }, "response": { "type": [ "string", "null" ] }, "updatedAt": { "type": "string", "format": "date-time" } } }, "DeliverySubmissionList": { "type": "object", "additionalProperties": false, "required": [ "submissions" ], "properties": { "submissions": { "type": "array", "items": { "$ref": "#/components/schemas/DeliverySubmission" } } } }, "DeliveryEventList": { "type": "object", "additionalProperties": false, "required": [ "events" ], "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/DeliveryEvent" } } } }, "DeliveryEvent": { "type": "object", "additionalProperties": false, "required": [ "id", "sourceEventId", "organizationId", "submissionId", "queueId", "type", "recipient", "response", "category", "occurredAt", "receivedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "sourceEventId": { "type": "string" }, "organizationId": { "type": "string", "format": "uuid" }, "submissionId": { "type": "string", "format": "uuid" }, "queueId": { "type": "string" }, "type": { "type": "string", "enum": [ "delivered", "deferred", "bounced", "expired", "unknown" ] }, "recipient": { "type": "string", "format": "email" }, "response": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "occurredAt": { "type": "string", "format": "date-time" }, "receivedAt": { "type": "string", "format": "date-time" } } }, "DeliveryHealthMetrics": { "type": "object", "description": "Counts, rates, suppression totals, and active-recipient age for the requested window.", "additionalProperties": false, "required": [ "window", "submissions", "recipients", "events", "complaints", "suppressions", "rates", "queue" ], "properties": { "window": { "$ref": "#/components/schemas/TimeWindow" }, "submissions": { "type": "object", "additionalProperties": false, "required": [ "pending", "queued", "deferred", "delivered", "partially_delivered", "bounced", "expired", "unknown", "failed", "total" ], "properties": { "pending": { "type": "integer", "minimum": 0 }, "queued": { "type": "integer", "minimum": 0 }, "deferred": { "type": "integer", "minimum": 0 }, "delivered": { "type": "integer", "minimum": 0 }, "partially_delivered": { "type": "integer", "minimum": 0 }, "bounced": { "type": "integer", "minimum": 0 }, "expired": { "type": "integer", "minimum": 0 }, "unknown": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 }, "total": { "type": "integer", "minimum": 0 } } }, "recipients": { "type": "object", "additionalProperties": false, "required": [ "pending", "queued", "deferred", "delivered", "bounced", "expired", "unknown", "total" ], "properties": { "pending": { "type": "integer", "minimum": 0 }, "queued": { "type": "integer", "minimum": 0 }, "deferred": { "type": "integer", "minimum": 0 }, "delivered": { "type": "integer", "minimum": 0 }, "bounced": { "type": "integer", "minimum": 0 }, "expired": { "type": "integer", "minimum": 0 }, "unknown": { "type": "integer", "minimum": 0 }, "total": { "type": "integer", "minimum": 0 } } }, "events": { "type": "object", "additionalProperties": false, "required": [ "delivered", "deferred", "bounced", "expired", "unknown", "total" ], "properties": { "delivered": { "type": "integer", "minimum": 0 }, "deferred": { "type": "integer", "minimum": 0 }, "bounced": { "type": "integer", "minimum": 0 }, "expired": { "type": "integer", "minimum": 0 }, "unknown": { "type": "integer", "minimum": 0 }, "total": { "type": "integer", "minimum": 0 } } }, "complaints": { "type": "integer", "minimum": 0 }, "suppressions": { "type": "object", "additionalProperties": false, "required": [ "total", "hardBounce", "complaint", "manual" ], "properties": { "total": { "type": "integer", "minimum": 0 }, "hardBounce": { "type": "integer", "minimum": 0 }, "complaint": { "type": "integer", "minimum": 0 }, "manual": { "type": "integer", "minimum": 0 } } }, "rates": { "type": "object", "additionalProperties": false, "required": [ "delivery", "bounce", "complaint" ], "properties": { "delivery": { "type": "number", "minimum": 0, "maximum": 1 }, "bounce": { "type": "number", "minimum": 0, "maximum": 1 }, "complaint": { "type": "number", "minimum": 0, "maximum": 1 } } }, "queue": { "type": "object", "additionalProperties": false, "required": [ "activeRecipients", "oldestActiveAt" ], "properties": { "activeRecipients": { "type": "integer", "minimum": 0 }, "oldestActiveAt": { "type": [ "string", "null" ], "format": "date-time" } } } } }, "SuppressionList": { "type": "object", "additionalProperties": false, "required": [ "suppressions" ], "properties": { "suppressions": { "type": "array", "items": { "$ref": "#/components/schemas/Suppression" } } } }, "Suppression": { "type": "object", "additionalProperties": false, "required": [ "id", "organizationId", "email", "reason", "sourceReferenceId", "createdAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "reason": { "type": "string", "enum": [ "hard_bounce", "complaint", "manual" ] }, "sourceReferenceId": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" } } }, "ComplaintList": { "type": "object", "additionalProperties": false, "required": [ "complaints" ], "properties": { "complaints": { "type": "array", "items": { "$ref": "#/components/schemas/Complaint" } } } }, "Complaint": { "type": "object", "additionalProperties": false, "required": [ "id", "sourceComplaintId", "organizationId", "submissionId", "senderDomain", "recipient", "provider", "feedbackType", "reportedAt", "receivedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "sourceComplaintId": { "type": "string" }, "organizationId": { "type": "string", "format": "uuid" }, "submissionId": { "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "senderDomain": { "type": [ "string", "null" ], "format": "hostname" }, "recipient": { "type": "string", "format": "email" }, "provider": { "type": "string" }, "feedbackType": { "type": "string", "enum": [ "abuse", "fraud", "virus", "other" ] }, "reportedAt": { "type": "string", "format": "date-time" }, "receivedAt": { "type": "string", "format": "date-time" } } }, "DomainList": { "type": "object", "additionalProperties": false, "required": [ "domains" ], "properties": { "domains": { "type": "array", "items": { "$ref": "#/components/schemas/SendingDomain" } } } }, "DomainVerification": { "type": "object", "additionalProperties": false, "required": [ "domain", "checks", "capabilities", "verified" ], "properties": { "domain": { "$ref": "#/components/schemas/SendingDomain" }, "checks": { "type": "object", "additionalProperties": false, "required": [ "ownership", "dkim", "inboundMx" ], "properties": { "ownership": { "type": "boolean" }, "dkim": { "type": "boolean" }, "inboundMx": { "type": "boolean" } } }, "capabilities": { "type": "object", "additionalProperties": false, "required": [ "outbound", "inbound" ], "properties": { "outbound": { "type": "boolean", "description": "True when ownership and DKIM pass; required to send." }, "inbound": { "type": "boolean", "description": "True when ownership and MX pass; required to create an inbox." } } }, "verified": { "type": "boolean", "description": "Compatibility alias for capabilities.outbound." } } }, "InboxPage": { "type": "object", "additionalProperties": false, "required": [ "inboxes", "nextCursor" ], "properties": { "inboxes": { "type": "array", "items": { "$ref": "#/components/schemas/Inbox" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page. Null means the page is final." } } }, "MailboxSendResult": { "type": "object", "additionalProperties": false, "required": [ "message", "submission", "replayed" ], "properties": { "message": { "$ref": "#/components/schemas/MailboxMessage" }, "submission": { "$ref": "#/components/schemas/DeliverySubmission" }, "replayed": { "type": "boolean" } } }, "ThreadPage": { "type": "object", "additionalProperties": false, "required": [ "threads", "nextCursor" ], "properties": { "threads": { "type": "array", "items": { "$ref": "#/components/schemas/ThreadSummary" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page. Null means the page is final." } } }, "ThreadSummary": { "type": "object", "required": [ "id", "inboxId", "subject", "participants", "messageCount", "lastMessageAt" ], "properties": { "id": { "$ref": "#/components/schemas/ThreadId" }, "inboxId": { "$ref": "#/components/schemas/InboxId" }, "subject": { "type": "string" }, "participants": { "type": "array", "items": { "type": "string", "format": "email" } }, "messageCount": { "type": "integer", "minimum": 1 }, "lastMessageAt": { "type": "string", "format": "date-time" } } }, "Thread": { "unevaluatedProperties": false, "allOf": [ { "$ref": "#/components/schemas/ThreadSummary" }, { "type": "object", "required": [ "messages", "nextCursor" ], "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/MailboxMessage" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page. Null means the page is final." } } } ] }, "WebhookEvent": { "type": "object", "additionalProperties": false, "required": [ "id", "type", "createdAt", "data" ], "properties": { "id": { "type": "string", "description": "Stable event ID; use it for deduplication." }, "type": { "const": "message.received" }, "createdAt": { "type": "string", "format": "date-time" }, "data": { "type": "object", "additionalProperties": false, "required": [ "messageId", "inboxId", "threadId" ], "properties": { "messageId": { "$ref": "#/components/schemas/MessageId" }, "inboxId": { "$ref": "#/components/schemas/InboxId" }, "threadId": { "$ref": "#/components/schemas/ThreadId" } } } }, "examples": [ { "id": "evt_0123456789abcdef01234567", "type": "message.received", "createdAt": "2026-08-31T12:00:00.000Z", "data": { "messageId": "msg_0123456789abcdef01234567", "inboxId": "inb_0123456789abcdef01234567", "threadId": "thr_0123456789abcdef01234567" } } ] }, "WebhookCreateResult": { "unevaluatedProperties": false, "allOf": [ { "$ref": "#/components/schemas/WebhookEndpoint" }, { "type": "object", "required": [ "signingSecret", "signingSecretReplayUntil", "replayed" ], "properties": { "signingSecret": { "type": "string", "pattern": "^whsec_[A-Za-z0-9_-]+$", "readOnly": true, "description": "Returned only during the bounded idempotent creation replay window.", "example": "whsec_REDACTED" }, "signingSecretReplayUntil": { "type": "string", "format": "date-time", "readOnly": true, "description": "Last instant when an exact create retry can recover the same signing secret." }, "replayed": { "type": "boolean" } } } ] }, "WebhookEndpoint": { "type": "object", "required": [ "id", "url", "events", "status", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/WebhookId" }, "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "events": { "type": "array", "items": { "const": "message.received" }, "minItems": 1, "maxItems": 1 }, "status": { "type": "string", "enum": [ "active", "deleting" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "WebhookPage": { "type": "object", "additionalProperties": false, "required": [ "endpoints", "nextCursor" ], "properties": { "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page. Null means the page is final." } } } }, "responses": { "BadRequest": { "description": "The request, cursor, idempotency key, or resource input is invalid. Correct it before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "The tenant key is missing, unknown, revoked, expired, or called from a source IP outside its exact allowlist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "The authenticated key lacks the required scope, inbox, send-mode, recipient-domain, organization, or resource permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "A request or sending limit was reached. Respect Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying this admission request.", "schema": { "type": "integer", "minimum": 1 } } } }, "InternalError": { "description": "The request failed unexpectedly. Reuse the same idempotency key when retrying a mutating operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unavailable": { "description": "A required dependency, safety policy, object store, or delivery path is unavailable. Retry only when retryable is true.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "The tenant-owned resource does not exist or is not visible to this key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Conflict": { "description": "The operation conflicts with current state or reuses an idempotency key with different input. Inspect error and action_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Gone": { "description": "The requested mailbox content was deleted and cannot be returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "PayloadTooLarge": { "description": "The request content, attachment, or mailbox response item exceeds a configured byte limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Locked": { "description": "The inbound attachment remains quarantined because its trusted scan state is not clean.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "UnprocessableEntity": { "description": "The request is valid, but a recipient is suppressed or no safe external reply recipient exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "securitySchemes": { "tenantApiKey": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "A scoped tenant key returned once by an operator. Never place it in URLs, logs, prompts, or client-side application code." } } } }