{ "openapi": "3.1.0", "info": { "title": "Marmunk API", "version": "1.0.0", "description": "Canonical provider-independent Marmunk control-plane and outbound API." }, "servers": [ { "url": "https://api.marmunk.com" } ], "paths": { "/health": { "get": { "operationId": "getHealth", "responses": { "200": { "description": "Service is healthy" } } } }, "/openapi.json": { "get": { "operationId": "getOpenApi", "responses": { "200": { "description": "Canonical OpenAPI document" } } } }, "/.well-known/oauth-authorization-server": { "get": { "operationId": "getOAuthAuthorizationServerMetadata", "summary": "Discover Marmunk OAuth endpoints", "responses": { "200": { "description": "RFC 8414 authorization server metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthAuthorizationServerMetadata" } } } } } } }, "/.well-known/oauth-protected-resource/mcp": { "get": { "operationId": "getMcpProtectedResourceMetadata", "summary": "Discover MCP resource authorization", "responses": { "200": { "description": "RFC 9728 protected resource metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthProtectedResourceMetadata" } } } } } } }, "/oauth/register": { "post": { "operationId": "registerOAuthClient", "summary": "Register a public OAuth client", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthClientRegistrationRequest" } } } }, "responses": { "201": { "description": "Public client registration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthClientRegistration" } } } }, "400": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/oauth/authorize": { "get": { "operationId": "beginOAuthAuthorization", "summary": "Begin authorization code flow with PKCE", "description": "Validates the public client and redirects the human to Marmunk's consent surface.", "parameters": [ { "name": "response_type", "in": "query", "required": true, "schema": { "type": "string", "const": "code" } }, { "name": "client_id", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "redirect_uri", "in": "query", "required": true, "schema": { "type": "string", "format": "uri" } }, { "name": "code_challenge", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "code_challenge_method", "in": "query", "required": true, "schema": { "type": "string", "const": "S256" } }, { "name": "resource", "in": "query", "required": true, "schema": { "type": "string", "format": "uri" } }, { "name": "scope", "in": "query", "schema": { "type": "string" } }, { "name": "state", "in": "query", "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirect to Marmunk sign-in and consent" }, "400": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/oauth/token": { "post": { "operationId": "exchangeOAuthToken", "summary": "Exchange an authorization code or refresh token", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/OAuthTokenRequest" } } } }, "responses": { "200": { "description": "OAuth access and refresh tokens", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthTokenResponse" } } } }, "400": { "description": "OAuth error response" } } } }, "/oauth/revoke": { "post": { "operationId": "revokeOAuthToken", "summary": "Revoke an OAuth access or refresh token", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string", "writeOnly": true }, "token_type_hint": { "enum": [ "access_token", "refresh_token" ] } } } } } }, "responses": { "200": { "description": "Token revoked or already inactive" } } } }, "/mcp": { "post": { "operationId": "invokeMcp", "summary": "Use the hosted Streamable HTTP MCP endpoint", "description": "MCP clients should discover OAuth metadata and negotiate the protocol rather than constructing this request directly.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Streamable HTTP MCP response" }, "401": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/oauth/authorization-requests/{requestId}": { "get": { "operationId": "getOAuthAuthorizationRequest", "summary": "Read a pending OAuth consent request", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "Pending client, resource, and requested scopes" }, "401": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "410": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/oauth/authorization-requests/{requestId}/approve": { "post": { "operationId": "approveOAuthAuthorization", "summary": "Approve selected OAuth scopes", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "Validated client redirect URI" }, "401": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "410": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/oauth/authorization-requests/{requestId}/deny": { "post": { "operationId": "denyOAuthAuthorization", "summary": "Deny an OAuth authorization request", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "Validated client redirect URI with access_denied" }, "401": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "410": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/oauth/connections": { "get": { "operationId": "listOAuthConnections", "summary": "List delegated OAuth connections", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "Tenant OAuth grants" }, "401": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/oauth/connections/{grantId}": { "delete": { "operationId": "revokeOAuthConnection", "summary": "Revoke a delegated OAuth connection", "security": [ { "sessionCookie": [] } ], "responses": { "204": { "description": "Connection revoked" }, "401": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/bootstrap/accounts": { "post": { "operationId": "bootstrapAccount", "summary": "Create a test-only account and bounded bootstrap credential", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BootstrapAccountRequest" } } } }, "responses": { "201": { "description": "Account and one-time bootstrap secret", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BootstrapAccountResponse" } } } }, "400": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/bootstrap/status": { "get": { "operationId": "getBootstrapStatus", "security": [ { "bootstrapAuth": [] } ], "responses": { "200": { "description": "Account onboarding status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } } }, "401": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/sessions": { "post": { "operationId": "createSession", "summary": "Exchange a verified Firebase ID token for an opaque session", "security": [ { "firebaseIdToken": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionProvisioningRequest" } } } }, "responses": { "204": { "description": "Secure session cookie set" }, "400": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/session": { "delete": { "operationId": "deleteSession", "security": [ { "sessionCookie": [] } ], "responses": { "204": { "description": "Session revoked" }, "401": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/account": { "get": { "operationId": "getAccount", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Current account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } } }, "401": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/billing": { "get": { "operationId": "getBilling", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "Current billing plan and subscription state" }, "401": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/billing/checkout": { "post": { "operationId": "createBillingCheckout", "security": [ { "sessionCookie": [] }, { "bearerAuth": [ "account.manage" ] } ], "responses": { "200": { "description": "Stripe Checkout redirect URL" }, "400": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/billing/portal": { "post": { "operationId": "createBillingPortal", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "Stripe Customer Portal redirect URL" }, "401": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/billing/webhook": { "post": { "operationId": "processStripeWebhook", "security": [], "responses": { "200": { "description": "Signed Stripe event accepted" }, "400": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/memberships": { "get": { "operationId": "listMemberships", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "Account memberships" }, "401": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "createMembership", "security": [ { "sessionCookie": [] } ], "responses": { "201": { "description": "Membership created" }, "401": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/tenants": { "get": { "operationId": "listTenants", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Account tenants" }, "401": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/domains": { "get": { "operationId": "listDomains", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Tenant domains" }, "401": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "createDomain", "security": [ { "sessionCookie": [] }, { "bearerAuth": [ "domain.manage" ] } ], "responses": { "201": { "description": "Domain and projected DNS requirements", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } } }, "401": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/domains/{domainId}": { "get": { "operationId": "getDomain", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Domain" }, "404": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/domains/{domainId}/verify": { "post": { "operationId": "verifyDomain", "security": [ { "sessionCookie": [] }, { "bearerAuth": [ "domain.manage" ] } ], "responses": { "200": { "description": "Updated verification dimensions" }, "403": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/api-keys": { "get": { "operationId": "listApiKeys", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "API key metadata" }, "401": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "createApiKey", "summary": "Create a scoped key; the secret is returned exactly once", "security": [ { "sessionCookie": [] } ], "responses": { "201": { "description": "API key metadata and one-time secret" }, "401": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/api-keys/{apiKeyId}": { "delete": { "operationId": "revokeApiKey", "security": [ { "sessionCookie": [] } ], "responses": { "204": { "description": "API key revoked" }, "401": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/sending-applications": { "post": { "operationId": "submitSendingApplication", "security": [ { "sessionCookie": [] } ], "responses": { "201": { "description": "Application received for manual review" }, "401": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/sending-applications/{applicationId}": { "get": { "operationId": "getSendingApplication", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "Sending application" }, "404": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/sending-approval": { "get": { "operationId": "getSendingApproval", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Customer-safe sending approval" }, "401": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/usage": { "get": { "operationId": "getUsageAndLimits", "security": [ { "bearerAuth": [ "usage.read" ] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Current usage and enforced limits" } } } }, "/v1/operator/applications": { "get": { "operationId": "operatorListApplications", "security": [ { "operatorSession": [] } ], "responses": { "200": { "description": "Cross-tenant approval queue" }, "403": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/operator/overview": { "get": { "operationId": "operatorGetOverview", "security": [ { "operatorSession": [] } ], "responses": { "200": { "description": "Cross-tenant service, delivery, queue, and SES health" }, "403": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/operator/clients": { "get": { "operationId": "operatorListClients", "security": [ { "operatorSession": [] } ], "responses": { "200": { "description": "Cursor-paginated cross-tenant client directory" }, "403": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/operator/applications/{applicationId}": { "get": { "operationId": "operatorGetApplication", "security": [ { "operatorSession": [] } ], "responses": { "200": { "description": "Application and review evidence" } } } }, "/v1/operator/applications/{applicationId}/decisions": { "post": { "operationId": "operatorDecideApplication", "security": [ { "operatorSession": [] } ], "responses": { "200": { "description": "Review recorded; activation requires two reviewers" }, "403": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/operator/tenants/{tenantId}/pause": { "post": { "operationId": "operatorPauseTenant", "security": [ { "operatorSession": [] } ], "responses": { "200": { "description": "Tenant paused" }, "403": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/operator/tenants/{tenantId}/resume": { "post": { "operationId": "operatorResumeTenant", "security": [ { "operatorSession": [] } ], "responses": { "200": { "description": "Resume review recorded; two operators required" }, "403": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/operator/tenants/{tenantId}/provider-mapping": { "put": { "operationId": "operatorUpsertProviderMapping", "security": [ { "operatorSession": [] } ], "responses": { "200": { "description": "SES provider mapping upserted" }, "400": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/operator/audit-events": { "get": { "operationId": "operatorListAuditEvents", "security": [ { "operatorSession": [] } ], "responses": { "200": { "description": "Append-only audit events" } } } }, "/v1/emails": { "get": { "operationId": "listEmails", "summary": "List email intents", "description": "Returns tenant-owned durable message intents. Delivery events are available separately.", "security": [ { "bearerAuth": [ "email.read" ] } ], "responses": { "200": { "description": "Tenant email intents", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } } }, "403": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "createEmail", "summary": "Queue an email intent", "description": "Durably accepts an approved email intent. A 202 response does not mean provider submission or recipient delivery.", "security": [ { "bearerAuth": [ "email.send" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Stable tenant-and-operation-scoped key. Identical retries return the original message ID.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendEmailRequest" } } } }, "responses": { "202": { "description": "Email intent durably queued or policy held", "headers": { "X-Marmunk-Request-Id": { "description": "Identifier for this API attempt", "schema": { "type": "string", "pattern": "^req_[A-Za-z0-9_-]+$" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendEmailResponse" } } } }, "400": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/emails/{messageId}": { "get": { "operationId": "getEmail", "summary": "Get one email intent", "security": [ { "bearerAuth": [ "email.read" ] } ], "parameters": [ { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^msg_[A-Za-z0-9_-]+$" } } ], "responses": { "200": { "description": "Tenant email intent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "404": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/emails/{messageId}/events": { "get": { "operationId": "listEmailEvents", "summary": "List normalized delivery events", "security": [ { "bearerAuth": [ "email.read" ] } ], "parameters": [ { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^msg_[A-Za-z0-9_-]+$" } } ], "responses": { "200": { "description": "Normalized delivery events", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MessageEvent" } } } } }, "404": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/email-traces/{referenceId}": { "get": { "operationId": "traceEmail", "summary": "Trace an API attempt or durable email", "description": "Resolve a request ID for one API attempt or a message ID for the durable asynchronous send lifecycle.", "security": [ { "bearerAuth": [ "email.read" ] } ], "parameters": [ { "name": "referenceId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^(req|msg)_[A-Za-z0-9_-]+$" } } ], "responses": { "200": { "description": "Tenant-scoped, support-safe send timeline", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailTrace" } } } }, "404": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/suppressions": { "get": { "operationId": "listSuppressions", "security": [ { "bearerAuth": [ "suppression.read" ] } ], "responses": { "200": { "description": "Tenant suppressions" } } }, "post": { "operationId": "createSuppression", "security": [ { "bearerAuth": [ "suppression.manage" ] } ], "responses": { "201": { "description": "Suppression created" } } } }, "/v1/suppressions/{suppressionId}": { "delete": { "operationId": "deleteSuppression", "security": [ { "bearerAuth": [ "suppression.manage" ] } ], "responses": { "204": { "description": "Customer suppression removed" }, "404": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/webhooks": { "get": { "operationId": "listWebhooks", "summary": "List webhook endpoints", "security": [ { "bearerAuth": [ "webhook.read" ] } ], "responses": { "200": { "description": "Tenant webhook endpoints", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } } } } } } }, "post": { "operationId": "createWebhook", "summary": "Create a webhook endpoint", "security": [ { "bearerAuth": [ "webhook.manage" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookRequest" } } } }, "responses": { "201": { "description": "Webhook endpoint and one-time secret", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedWebhookEndpoint" } } } }, "400": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/webhooks/{webhookId}": { "get": { "operationId": "getWebhook", "summary": "Get a webhook endpoint", "security": [ { "bearerAuth": [ "webhook.read" ] } ], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^whk_[A-Za-z0-9_-]+$" } } ], "responses": { "200": { "description": "Webhook endpoint without secret", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "404": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/webhooks/{webhookId}/rotate-secret": { "post": { "operationId": "rotateWebhookSecret", "summary": "Rotate a webhook signing secret", "security": [ { "bearerAuth": [ "webhook.manage" ] } ], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^whk_[A-Za-z0-9_-]+$" } } ], "responses": { "200": { "description": "Rotated one-time webhook secret", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotatedWebhookSecret" } } } }, "404": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/webhook-events/{eventId}/replay": { "post": { "operationId": "replayWebhookEvent", "summary": "Replay one normalized event", "security": [ { "bearerAuth": [ "webhook.manage" ] } ], "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^evt_[A-Za-z0-9_-]+$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "202": { "description": "Webhook replay generation queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookReplayResponse" } } } }, "400": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Marmunk error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" }, "bootstrapAuth": { "type": "http", "scheme": "bearer" }, "firebaseIdToken": { "type": "http", "scheme": "bearer", "bearerFormat": "Firebase ID token" }, "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "__Host-marmunk_session" }, "operatorSession": { "type": "apiKey", "in": "cookie", "name": "__Host-marmunk_session" } }, "schemas": { "BootstrapAccountRequest": { "type": "object", "additionalProperties": false, "required": [ "organization_name", "owner_email" ], "properties": { "organization_name": { "type": "string", "minLength": 1, "maxLength": 200 }, "owner_email": { "type": "string", "format": "email", "maxLength": 320 } } }, "BootstrapAccountResponse": { "type": "object", "required": [ "account", "bootstrap_secret" ], "properties": { "account": { "$ref": "#/components/schemas/Account" }, "bootstrap_secret": { "type": "string", "writeOnly": true } } }, "SessionProvisioningRequest": { "type": "object", "additionalProperties": false, "properties": { "organization_name": { "type": "string", "minLength": 1, "maxLength": 200 }, "terms_accepted": { "type": "boolean", "const": true }, "operator": { "type": "boolean" } } }, "Account": { "type": "object", "required": [ "id", "organization_id", "organization_name", "tenant_id", "tenant_state", "created_at" ], "properties": { "id": { "type": "string", "pattern": "^acct_[A-Za-z0-9]+$" }, "organization_id": { "type": "string", "pattern": "^org_[A-Za-z0-9]+$" }, "organization_name": { "type": "string" }, "tenant_id": { "type": "string", "pattern": "^ten_[A-Za-z0-9]+$" }, "tenant_state": { "enum": [ "test_only", "pending_review", "active", "paused", "rejected", "closed" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "Domain": { "type": "object", "required": [ "id", "tenant_id", "name", "region", "dns_status", "provider_status", "sending_status", "records", "created_at" ], "properties": { "id": { "type": "string", "pattern": "^dom_[A-Za-z0-9]+$" }, "tenant_id": { "type": "string", "pattern": "^ten_[A-Za-z0-9]+$" }, "name": { "type": "string", "format": "hostname" }, "region": { "type": "string" }, "dns_status": { "enum": [ "pending", "verified", "failed" ] }, "provider_status": { "enum": [ "pending", "ready", "failed" ] }, "sending_status": { "enum": [ "not_approved", "pending_review", "approved", "paused" ] }, "records": { "type": "array", "items": { "type": "object" } }, "created_at": { "type": "string", "format": "date-time" }, "dashboard_url": { "type": "string", "format": "uri" }, "dns_connect": { "type": "object", "required": [ "provider", "apply_url" ], "properties": { "provider": { "enum": [ "cloudflare" ] }, "apply_url": { "type": "string", "format": "uri" } } } } }, "OAuthAuthorizationServerMetadata": { "type": "object", "required": [ "issuer", "authorization_endpoint", "token_endpoint", "registration_endpoint", "revocation_endpoint", "response_types_supported", "grant_types_supported", "code_challenge_methods_supported", "scopes_supported" ], "properties": { "issuer": { "type": "string", "format": "uri" }, "authorization_endpoint": { "type": "string", "format": "uri" }, "token_endpoint": { "type": "string", "format": "uri" }, "registration_endpoint": { "type": "string", "format": "uri" }, "revocation_endpoint": { "type": "string", "format": "uri" }, "response_types_supported": { "type": "array", "items": { "type": "string" } }, "grant_types_supported": { "type": "array", "items": { "type": "string" } }, "token_endpoint_auth_methods_supported": { "type": "array", "items": { "type": "string" } }, "code_challenge_methods_supported": { "type": "array", "items": { "type": "string" } }, "scopes_supported": { "type": "array", "items": { "type": "string" } }, "resource_indicators_supported": { "type": "boolean" } } }, "OAuthProtectedResourceMetadata": { "type": "object", "required": [ "resource", "authorization_servers", "bearer_methods_supported", "scopes_supported" ], "properties": { "resource": { "type": "string", "format": "uri" }, "authorization_servers": { "type": "array", "items": { "type": "string", "format": "uri" } }, "bearer_methods_supported": { "type": "array", "items": { "type": "string" } }, "scopes_supported": { "type": "array", "items": { "type": "string" } } } }, "OAuthClientRegistrationRequest": { "type": "object", "additionalProperties": false, "required": [ "client_name", "redirect_uris" ], "properties": { "client_name": { "type": "string", "minLength": 1, "maxLength": 120 }, "redirect_uris": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "string", "format": "uri" } } } }, "OAuthClientRegistration": { "type": "object", "required": [ "client_id", "client_name", "redirect_uris", "token_endpoint_auth_method", "client_id_issued_at" ], "properties": { "client_id": { "type": "string" }, "client_name": { "type": "string" }, "redirect_uris": { "type": "array", "items": { "type": "string", "format": "uri" } }, "token_endpoint_auth_method": { "type": "string", "const": "none" }, "client_id_issued_at": { "type": "integer" } } }, "OAuthTokenRequest": { "type": "object", "required": [ "grant_type", "client_id" ], "properties": { "grant_type": { "enum": [ "authorization_code", "refresh_token" ] }, "client_id": { "type": "string" }, "code": { "type": "string", "writeOnly": true }, "code_verifier": { "type": "string", "writeOnly": true }, "redirect_uri": { "type": "string", "format": "uri" }, "refresh_token": { "type": "string", "writeOnly": true }, "resource": { "type": "string", "format": "uri" } } }, "OAuthTokenResponse": { "type": "object", "required": [ "access_token", "token_type", "expires_in", "scope" ], "properties": { "access_token": { "type": "string", "writeOnly": true }, "token_type": { "type": "string", "const": "Bearer" }, "expires_in": { "type": "integer", "minimum": 1 }, "scope": { "type": "string" }, "refresh_token": { "type": "string", "writeOnly": true } } }, "EmailAddress": { "type": "object", "additionalProperties": false, "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 320 }, "name": { "type": "string", "maxLength": 200 } } }, "EmailAttachment": { "type": "object", "additionalProperties": false, "required": [ "filename", "content_type", "content_base64" ], "properties": { "filename": { "type": "string", "minLength": 1 }, "content_type": { "type": "string", "minLength": 1 }, "content_base64": { "type": "string", "contentEncoding": "base64", "description": "Base64-encoded attachment bytes." } } }, "SendEmailRequest": { "type": "object", "additionalProperties": false, "required": [ "from", "to", "subject" ], "anyOf": [ { "required": [ "text" ] }, { "required": [ "html" ] } ], "properties": { "from": { "$ref": "#/components/schemas/EmailAddress" }, "to": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "$ref": "#/components/schemas/EmailAddress" } }, "cc": { "type": "array", "items": { "$ref": "#/components/schemas/EmailAddress" } }, "bcc": { "type": "array", "items": { "$ref": "#/components/schemas/EmailAddress" } }, "reply_to": { "$ref": "#/components/schemas/EmailAddress" }, "subject": { "type": "string", "minLength": 1 }, "text": { "type": "string" }, "html": { "type": "string" }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/EmailAttachment" } }, "tags": { "type": "object", "additionalProperties": { "type": "string" } } } }, "SendEmailResponse": { "type": "object", "additionalProperties": false, "required": [ "id", "status", "created_at", "request_id" ], "properties": { "id": { "type": "string", "pattern": "^msg_[A-Za-z0-9_-]+$" }, "status": { "enum": [ "queued", "policy_held" ] }, "created_at": { "type": "string", "format": "date-time" }, "request_id": { "type": "string", "pattern": "^req_[A-Za-z0-9_-]+$" } } }, "Recipient": { "type": "object", "required": [ "id", "email", "status" ], "properties": { "id": { "type": "string", "pattern": "^rcp_[A-Za-z0-9_-]+$" }, "email": { "type": "string", "format": "email" }, "status": { "enum": [ "pending", "queued", "delivered", "bounced", "complained", "suppressed", "failed" ] } } }, "Message": { "type": "object", "required": [ "id", "accountId", "from", "recipients", "subject", "status", "createdAt" ], "properties": { "id": { "type": "string", "pattern": "^msg_[A-Za-z0-9_-]+$" }, "accountId": { "type": "string", "pattern": "^acct_[A-Za-z0-9_-]+$" }, "from": { "type": "string", "format": "email" }, "recipients": { "type": "array", "items": { "$ref": "#/components/schemas/Recipient" } }, "subject": { "type": "string" }, "status": { "enum": [ "queued", "policy_held", "submitting", "submitted", "unknown", "delayed", "delivered", "partially_delivered", "bounced", "complained", "rejected", "failed", "canceled" ] }, "createdAt": { "type": "string", "format": "date-time" }, "provider_message_id": { "type": "string", "description": "Safe provider correlation metadata, not a public resource locator." } } }, "MessageEvent": { "type": "object", "required": [ "id", "messageId", "type", "occurredAt" ], "properties": { "id": { "type": "string", "pattern": "^evt_[A-Za-z0-9_-]+$" }, "messageId": { "type": "string", "pattern": "^msg_[A-Za-z0-9_-]+$" }, "recipientId": { "type": "string", "pattern": "^rcp_[A-Za-z0-9_-]+$" }, "type": { "enum": [ "message.accepted", "message.rejected", "delivery.succeeded", "delivery.bounced", "delivery.complained", "delivery.failed" ] }, "occurredAt": { "type": "string", "format": "date-time" } } }, "EmailRequestTrace": { "type": "object", "required": [ "request_id", "channel", "outcome", "status_code", "created_at" ], "properties": { "request_id": { "type": "string", "pattern": "^req_[A-Za-z0-9_-]+$" }, "channel": { "enum": [ "api", "mcp", "human" ] }, "outcome": { "enum": [ "accepted", "replayed", "denied", "failed" ] }, "status_code": { "type": "integer", "minimum": 100, "maximum": 599 }, "error_code": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "EmailProviderAttemptTrace": { "type": "object", "required": [ "id", "outcome", "created_at" ], "properties": { "id": { "type": "string" }, "outcome": { "enum": [ "started", "submitted", "unknown", "failed" ] }, "provider_message_id": { "type": "string" }, "error_code": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time" } } }, "EmailWebhookTrace": { "type": "object", "required": [ "delivery_id", "event_id", "status", "attempts", "updated_at" ], "properties": { "delivery_id": { "type": "string" }, "event_id": { "type": "string", "pattern": "^evt_[A-Za-z0-9_-]+$" }, "status": { "enum": [ "pending", "delivering", "succeeded", "retrying", "failed" ] }, "attempts": { "type": "integer", "minimum": 0 }, "last_outcome": { "enum": [ "succeeded", "retry", "permanent_failure", "blocked" ] }, "last_error_code": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "EmailTrace": { "type": "object", "required": [ "reference_id", "requests", "provider_attempts", "events", "webhooks" ], "description": "Tenant-scoped trace that excludes message bodies, attachments, credentials, and raw provider payloads.", "properties": { "reference_id": { "type": "string", "pattern": "^(req|msg)_[A-Za-z0-9_-]+$" }, "message": { "$ref": "#/components/schemas/Message" }, "requests": { "type": "array", "items": { "$ref": "#/components/schemas/EmailRequestTrace" } }, "provider_attempts": { "type": "array", "items": { "$ref": "#/components/schemas/EmailProviderAttemptTrace" } }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/MessageEvent" } }, "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/EmailWebhookTrace" } } } }, "WebhookEndpoint": { "type": "object", "required": [ "id", "url", "event_types", "enabled", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "pattern": "^whk_[A-Za-z0-9_-]+$" }, "url": { "type": "string", "format": "uri", "pattern": "^https://" }, "event_types": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "CreateWebhookRequest": { "type": "object", "additionalProperties": false, "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "pattern": "^https://" }, "event_types": { "type": "array", "items": { "type": "string" } } } }, "CreatedWebhookEndpoint": { "allOf": [ { "$ref": "#/components/schemas/WebhookEndpoint" }, { "type": "object", "required": [ "secret" ], "properties": { "secret": { "type": "string", "writeOnly": true } } } ] }, "RotatedWebhookSecret": { "type": "object", "required": [ "webhook_id", "secret", "previous_secret_expires_at" ], "properties": { "webhook_id": { "type": "string", "pattern": "^whk_[A-Za-z0-9_-]+$" }, "secret": { "type": "string", "writeOnly": true }, "previous_secret_expires_at": { "type": "string", "format": "date-time" } } }, "WebhookReplayResponse": { "type": "object", "required": [ "event_id", "delivery_generation", "request_id" ], "properties": { "event_id": { "type": "string", "pattern": "^evt_[A-Za-z0-9_-]+$" }, "delivery_generation": { "type": "integer", "minimum": 0 }, "request_id": { "type": "string", "pattern": "^req_[A-Za-z0-9_-]+$" } } }, "ErrorEnvelope": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "pattern": "^req_[A-Za-z0-9_-]+$" }, "retryable": { "type": "boolean" }, "details": { "type": "object", "additionalProperties": true } } } } } } }, "tags": [ { "name": "v1" } ] }