{ "openapi": "3.0.0", "info": { "description": "Control plane for the Spore transactional email platform.", "title": "Spore API", "contact": { "name": "Spore", "url": "https://sporee.fr", "email": "contact@sporee.fr" }, "license": { "name": "Proprietary" }, "version": "0.1.0" }, "paths": { "/api-keys": { "get": { "security": [ { "BearerAuth": [] } ], "tags": [ "api-keys" ], "summary": "List API keys", "operationId": "listApiKeys", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apikeys.ListAPIKeysResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } } } }, "post": { "security": [ { "BearerAuth": [] } ], "tags": [ "api-keys" ], "summary": "Create an API key", "operationId": "createApiKey", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apikeys.CreateAPIKeyRequest" } } }, "description": "API key to create", "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/apikeys.CreatedKey" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } } } } }, "/api-keys/{id}": { "delete": { "security": [ { "BearerAuth": [] } ], "tags": [ "api-keys" ], "summary": "Revoke an API key", "operationId": "revokeApiKey", "parameters": [ { "description": "API key ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "401": { "description": "Unauthorized", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "404": { "description": "Not Found", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } } } } }, "/billing/checkout": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Opens a hosted payment that collects the first period and establishes the mandate future charges ride on. Returns the URL to redirect the customer to. Entitlement is granted only once the payment is confirmed by the provider webhook — this endpoint grants nothing.", "tags": [ "billing" ], "summary": "Open a checkout for a paid plan", "operationId": "startBillingCheckout", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/start_checkout.StartCheckoutRequest" } } }, "description": "Plan to subscribe to", "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/start_checkout.Result" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "409": { "description": "already holds an entitling subscription", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "422": { "description": "plan is not purchasable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "503": { "description": "billing is not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } } } } }, "/billing/downgrade": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Schedules a move to a smaller tier, effective at the next renewal. Nothing changes today and nothing is refunded: the tenant keeps the tier they paid for until the current period ends. Moving to the free tier is a cancellation, not a downgrade.", "tags": [ "billing" ], "summary": "Schedule a downgrade to a smaller plan", "operationId": "downgradeBillingSubscription", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/downgrade_subscription.DowngradeRequest" } } }, "description": "Target plan", "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/downgrade_subscription.Result" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "404": { "description": "no subscription", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "422": { "description": "not a downgrade, or use cancellation for the free tier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "503": { "description": "billing is not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } } } } }, "/billing/pending-change": { "delete": { "security": [ { "BearerAuth": [] } ], "description": "Withdraws a scheduled downgrade before it fires. Idempotent: withdrawing when nothing is scheduled succeeds.", "tags": [ "billing" ], "summary": "Withdraw a scheduled plan change", "operationId": "cancelBillingPendingChange", "responses": { "204": { "description": "withdrawn" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "404": { "description": "no subscription", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "503": { "description": "billing is not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } } } } }, "/billing/state": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns the subscription's health: which tier is paid for, whether a payment failed and until when it can still be fixed, and any scheduled change. A tenant who never subscribed is reported healthy with hasSubscription=false — the free tier is not a degraded state.", "tags": [ "billing" ], "summary": "Get the calling tenant's billing state", "operationId": "getBillingState", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_billing_state.State" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } } } } }, "/billing/subscription": { "delete": { "security": [ { "BearerAuth": [] } ], "description": "Stops future charges. Access is NOT revoked: the period already paid for keeps entitling until it lapses, and the response carries that date. Idempotent.", "tags": [ "billing" ], "summary": "Cancel the subscription", "operationId": "cancelBillingSubscription", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cancel_subscription.Result" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "404": { "description": "no subscription", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "503": { "description": "billing is not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } } } } }, "/billing/upgrade": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Moves the tenant to a larger tier, effective immediately. The prorated difference is charged on the existing mandate BEFORE the tier is applied: a declined charge leaves the tier untouched. Requires explicit consent to the amount returned by the quote endpoint.", "tags": [ "billing" ], "summary": "Upgrade to a larger plan", "operationId": "upgradeBillingSubscription", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/upgrade_subscription.UpgradeRequest" } } }, "description": "Target plan and accepted amount", "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/upgrade_subscription.Result" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "402": { "description": "the payment was declined", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "404": { "description": "no subscription — open a checkout instead", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "409": { "description": "the quoted amount was not consented to", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "422": { "description": "not an upgrade, or the subscription cannot change tier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "503": { "description": "billing is not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } } } } }, "/billing/upgrade/quote": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Returns the prorated amount owed today for moving to a larger tier — the difference between the tiers for the time remaining in the period already paid, never the catalogue price. Charges nothing. An amount of 0 means the upgrade is granted without a charge.", "tags": [ "billing" ], "summary": "Quote what an upgrade would cost", "operationId": "quoteBillingUpgrade", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/upgrade_subscription.QuoteRequest" } } }, "description": "Target plan", "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/upgrade_subscription.Quote" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "404": { "description": "no subscription — open a checkout instead", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "422": { "description": "not an upgrade, or the subscription cannot change tier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "503": { "description": "billing is not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } } } } }, "/billing/webhook/lungor": { "post": { "description": "Ingests Lungor's subscription lifecycle events. Authenticated by HMAC signature, not by API key — never called by clients.", "tags": [ "billing" ], "summary": "Lungor subscription webhook", "operationId": "lungorWebhook", "responses": { "200": { "description": "ok", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "invalid signature", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/billing/webhook/mollie": { "post": { "description": "Receives payment notifications from Mollie. The body is unsigned and carries only a payment id, so the payment is re-fetched with the API key before anything is applied — the authenticated read is the security boundary. Idempotent: replayed notifications are acknowledged without being re-applied.", "tags": [ "internal" ], "summary": "Payment provider webhook", "operationId": "handleMollieWebhook", "responses": { "200": { "description": "acknowledged — applied, replayed, or attributable to nobody" }, "400": { "description": "no payment id in the body", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "500": { "description": "not applied — the provider should retry", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "503": { "description": "billing is not configured", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } } } } }, "/emails": { "get": { "security": [ { "BearerAuth": [] } ], "tags": [ "messaging" ], "summary": "List enqueued/sent messages", "operationId": "listEmails", "parameters": [ { "description": "Filter by identity", "name": "identityId", "in": "query", "schema": { "type": "string" } }, { "description": "Filter by status", "name": "status", "in": "query", "schema": { "type": "string" } }, { "description": "Search subject or recipient", "name": "q", "in": "query", "schema": { "type": "string" } }, { "description": "Created at >= RFC3339 timestamp", "name": "from", "in": "query", "schema": { "type": "string" } }, { "description": "Created at < RFC3339 timestamp", "name": "to", "in": "query", "schema": { "type": "string" } }, { "description": "Page size", "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "description": "Offset", "name": "offset", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_messages.Result" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } } } }, "post": { "security": [ { "BearerAuth": [] } ], "tags": [ "messaging" ], "summary": "Enqueue a transactional email", "operationId": "sendEmail", "parameters": [ { "description": "Unique retry key kept for 24 hours", "name": "Idempotency-Key", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/send_email.SendEmailRequest" } } }, "description": "Email to send", "required": true }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/send_email.SendEmailResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "422": { "description": "monthly email quota reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/send_email.QuotaErrorBody" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } } } } }, "/emails/test": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Sends a server-built email through the full DKIM-sign + outbox + MTA pipeline. Bypasses the monthly quota and tags the message as kind=test.", "tags": [ "messaging" ], "summary": "Send a diagnostic test email from the UI", "operationId": "sendTestEmail", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/send_test_email.SendTestEmailRequest" } } }, "description": "Test parameters", "required": true }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/send_test_email.SendTestEmailResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } } } } }, "/emails/{id}": { "get": { "security": [ { "BearerAuth": [] } ], "tags": [ "messaging" ], "summary": "Get a message", "operationId": "getEmail", "parameters": [ { "description": "Message ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/repository.MessageView" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } } } } }, "/identities": { "get": { "security": [ { "BearerAuth": [] } ], "tags": [ "identities" ], "summary": "List sending identities", "operationId": "listIdentities", "parameters": [ { "description": "Page size", "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "description": "Offset", "name": "offset", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_identities.Response" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } } } }, "post": { "security": [ { "BearerAuth": [] } ], "tags": [ "identities" ], "summary": "Register a sending identity", "operationId": "createIdentity", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create_identity.CreateIdentityRequest" } } }, "description": "Identity to create", "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create_identity.CreateIdentityResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } } } } }, "/identities/{id}": { "get": { "security": [ { "BearerAuth": [] } ], "tags": [ "identities" ], "summary": "Get a sending identity", "operationId": "getIdentity", "parameters": [ { "description": "Identity ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/repository.IdentityView" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } } } }, "delete": { "security": [ { "BearerAuth": [] } ], "tags": [ "identities" ], "summary": "Delete a sending identity", "operationId": "deleteIdentity", "parameters": [ { "description": "Identity ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } } } } }, "/identities/{id}/addresses": { "post": { "security": [ { "BearerAuth": [] } ], "tags": [ "identities" ], "summary": "Add an allowed From address (local-part) on a verified identity", "operationId": "addIdentityAddress", "parameters": [ { "description": "Identity ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/add_address.addAddressRequest" } } }, "description": "Address payload", "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/add_address.AddAddressResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } } } } }, "/identities/{id}/addresses/{localPart}": { "delete": { "security": [ { "BearerAuth": [] } ], "tags": [ "identities" ], "summary": "Remove an allowed From address", "operationId": "removeIdentityAddress", "parameters": [ { "description": "Identity ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "description": "Address local-part", "name": "localPart", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } } } } }, "/identities/{id}/addresses/{localPart}/disable": { "post": { "security": [ { "BearerAuth": [] } ], "tags": [ "identities" ], "summary": "Disable an allowed From address", "operationId": "disableIdentityAddress", "parameters": [ { "description": "Identity ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "description": "Address local-part", "name": "localPart", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/disable_address.disableAddressRequest" } } }, "description": "Optional reason" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/disable_address.DisableAddressResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } } } } }, "/identities/{id}/brand": { "get": { "security": [ { "BearerAuth": [] } ], "tags": [ "branding" ], "summary": "Get the branding for a sending identity", "operationId": "getBrand", "parameters": [ { "description": "Identity ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/repository.BrandView" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } } } }, "put": { "security": [ { "BearerAuth": [] } ], "tags": [ "branding" ], "summary": "Set the branding for a sending identity", "operationId": "setBrand", "parameters": [ { "description": "Identity ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/set_brand.SetBrandRequest" } } }, "description": "Branding fields", "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/set_brand.Response" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } } } } }, "/identities/{id}/brand/extract": { "post": { "security": [ { "BearerAuth": [] } ], "tags": [ "branding" ], "summary": "Extract a branding suggestion from a URL or HTML", "operationId": "extractBrand", "parameters": [ { "description": "Identity ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/extract_brand.ExtractBrandRequest" } } }, "description": "Source URL or raw HTML", "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/extract_brand.Response" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } } } } }, "/identities/{id}/verify": { "post": { "security": [ { "BearerAuth": [] } ], "tags": [ "identities" ], "summary": "Verify a sending identity's DNS records", "operationId": "verifyIdentity", "parameters": [ { "description": "Identity ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/verify_identity.VerifyIdentityResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } } } } }, "/internal/bounces": { "post": { "security": [ { "InternalToken": [] } ], "tags": [ "internal" ], "summary": "Ingest a raw RFC 3464 bounce DSN", "operationId": "ingestBounce", "parameters": [ { "description": "Resolved tenant id", "name": "X-Tenant-ID", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "text/plain": { "schema": { "type": "string" } } }, "description": "Raw DSN payload", "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ingest_bounce.Response" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } } } } }, "/internal/reputation/{tenantId}/unfreeze": { "post": { "security": [ { "InternalToken": [] } ], "description": "Internal endpoint. Requires the X-Internal-Token header. Unfreezing is manual by design — a frozen tenant never thaws on its own.", "tags": [ "reputation" ], "summary": "Lift a sending freeze on a tenant", "operationId": "unfreezeTenantReputation", "parameters": [ { "description": "Tenant id", "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/unfreeze.UnfreezeRequest" } } }, "description": "Reason for lifting the freeze", "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/unfreeze.Response" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } } } } }, "/internal/tenant/plan": { "post": { "security": [ { "InternalToken": [] } ], "description": "Internal endpoint used by the Stripe webhook bridge. Authenticated via the X-Internal-Token header — NOT the public BearerAuth scheme.", "tags": [ "internal" ], "summary": "Assign a plan to a tenant (service-to-service)", "operationId": "setTenantPlan", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/set_tenant_plan.SetTenantPlanRequest" } } }, "description": "Tenant + plan to assign", "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/domain.TenantPlan" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } } } } }, "/reputation": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Bounce rate over the trailing window plus the freeze state. belowMinVolume means the window holds too few sends for the rate to be acted on.", "tags": [ "reputation" ], "summary": "Get the current sending reputation for the authenticated tenant", "operationId": "getReputation", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/repository.StateView" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } } } } }, "/suppressions": { "get": { "security": [ { "BearerAuth": [] } ], "tags": [ "suppressions" ], "summary": "List suppressed emails", "operationId": "listSuppressions", "parameters": [ { "description": "Page size", "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "description": "Offset", "name": "offset", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_suppressions.Response" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } } } }, "post": { "security": [ { "BearerAuth": [] } ], "tags": [ "suppressions" ], "summary": "Add an email to the suppression list", "operationId": "addSuppression", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/add_suppression.AddSuppressionRequest" } } }, "description": "Suppression to add", "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/add_suppression.Response" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } } } } }, "/suppressions/{email}": { "delete": { "security": [ { "BearerAuth": [] } ], "tags": [ "suppressions" ], "summary": "Remove an email from the suppression list", "operationId": "removeSuppression", "parameters": [ { "description": "Suppressed email", "name": "email", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "401": { "description": "Unauthorized", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "404": { "description": "Not Found", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } } } } }, "/templates": { "get": { "security": [ { "BearerAuth": [] } ], "tags": [ "templates" ], "summary": "List built-in email templates", "operationId": "listTemplates", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_templates.Response" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } } } } }, "/templates/{id}/preview": { "post": { "security": [ { "BearerAuth": [] } ], "tags": [ "templates" ], "summary": "Render a preview of a template", "operationId": "previewTemplate", "parameters": [ { "description": "Template ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/preview_template.PreviewTemplateRequest" } } }, "description": "Locale and variables", "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/preview_template.Response" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } } } } }, "/tenant/plan": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns the plan and current billing period for the authenticated tenant. Tenants without an explicit assignment default to the Free plan.", "tags": [ "plans" ], "summary": "Get the calling tenant's plan", "operationId": "getTenantPlan", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/domain.TenantPlan" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } } } } }, "/unsubscribe": { "get": { "description": "Public HTML page shown when a recipient clicks the unsubscribe\nlink in their mail client UI. Submitting the form posts back to\n`POST /unsubscribe` with the same token.", "tags": [ "unsubscribe" ], "summary": "Render the unsubscribe confirmation page", "operationId": "viewUnsubscribe", "parameters": [ { "description": "Unsubscribe token", "name": "token", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTML confirmation page", "content": { "text/html": { "schema": { "type": "string" } } } }, "400": { "description": "Bad Request", "content": { "text/html": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "410": { "description": "expired token", "content": { "text/html": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } } } }, "post": { "description": "Public endpoint hit by mail-client user-agents. Accepts either\n`application/x-www-form-urlencoded` with `List-Unsubscribe=One-Click&token=...`\nor `application/json` with `{\"token\": \"...\"}`. Always returns 200 on\na valid token, even when the recipient is already suppressed (idempotent).", "tags": [ "unsubscribe" ], "summary": "One-click unsubscribe (RFC 8058)", "operationId": "confirmUnsubscribe", "parameters": [ { "description": "Token (when posted via query string)", "name": "token", "in": "query", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/confirm_unsubscribe.ConfirmUnsubscribeRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/confirm_unsubscribe.ConfirmUnsubscribeRequest" } } }, "description": "JSON body" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/confirm_unsubscribe.Response" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } } } } }, "/unsubscribes": { "get": { "security": [ { "BearerAuth": [] } ], "tags": [ "unsubscribes" ], "summary": "List unsubscribe events", "operationId": "listUnsubscribes", "parameters": [ { "description": "Page size", "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "description": "Offset", "name": "offset", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_unsubscribes.Response" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } } } } }, "/usage": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns the live counter for the current calendar month plus the last 12 months of history. The current period also carries a per-identity breakdown for dashboard display.", "tags": [ "usage" ], "summary": "Get the calling tenant's current and historical usage", "operationId": "getUsage", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_usage.UsageResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } } } } }, "/webhooks/endpoints": { "get": { "security": [ { "BearerAuth": [] } ], "tags": [ "webhooks" ], "summary": "List webhook endpoints", "operationId": "listWebhookEndpoints", "parameters": [ { "description": "Page size", "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "description": "Offset", "name": "offset", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_endpoints.Result" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } } } }, "post": { "security": [ { "BearerAuth": [] } ], "tags": [ "webhooks" ], "summary": "Create a webhook endpoint", "operationId": "createWebhookEndpoint", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create_endpoint.CreateEndpointRequest" } } }, "description": "Endpoint to create", "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create_endpoint.Result" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } } } } }, "/webhooks/endpoints/{id}": { "get": { "security": [ { "BearerAuth": [] } ], "tags": [ "webhooks" ], "summary": "Get a webhook endpoint", "operationId": "getWebhookEndpoint", "parameters": [ { "description": "Endpoint ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/repository.EndpointView" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } } } }, "delete": { "security": [ { "BearerAuth": [] } ], "tags": [ "webhooks" ], "summary": "Delete a webhook endpoint", "operationId": "deleteWebhookEndpoint", "parameters": [ { "description": "Endpoint ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "401": { "description": "Unauthorized", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "404": { "description": "Not Found", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } } } }, "patch": { "security": [ { "BearerAuth": [] } ], "tags": [ "webhooks" ], "summary": "Update a webhook endpoint", "operationId": "updateWebhookEndpoint", "parameters": [ { "description": "Endpoint ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/update_endpoint.UpdateEndpointRequest" } } }, "description": "Updated fields", "required": true }, "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } } } } }, "/webhooks/endpoints/{id}/rotate-secret": { "post": { "security": [ { "BearerAuth": [] } ], "tags": [ "webhooks" ], "summary": "Rotate a webhook endpoint's signing secret", "operationId": "rotateWebhookSecret", "parameters": [ { "description": "Endpoint ID", "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/rotate_secret.Result" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/echo.HTTPError" } } } } } } } }, "servers": [ { "url": "https://api.sporee.fr" } ], "components": { "securitySchemes": { "BearerAuth": { "description": "Pass `Bearer `. Accepts a managed sk_live_* key, an HS256 JWT, or the static API_KEY.", "type": "apiKey", "name": "Authorization", "in": "header" }, "InternalToken": { "description": "Service-to-service token used by /internal/* endpoints.", "type": "apiKey", "name": "X-Internal-Token", "in": "header" } }, "schemas": { "add_address.AddAddressResult": { "type": "object", "properties": { "identityId": { "type": "string" }, "label": { "type": "string" }, "localPart": { "type": "string" }, "status": { "type": "string" } } }, "add_address.addAddressRequest": { "type": "object", "properties": { "label": { "type": "string" }, "localPart": { "type": "string" } } }, "add_suppression.AddSuppressionRequest": { "type": "object", "properties": { "email": { "type": "string" }, "reason": { "type": "string" } } }, "add_suppression.Response": { "type": "object", "properties": { "email": { "type": "string" }, "id": { "type": "string" }, "status": { "type": "string" } } }, "apikeys.CreateAPIKeyRequest": { "type": "object", "properties": { "name": { "type": "string" } } }, "apikeys.CreatedKey": { "type": "object", "properties": { "createdAt": { "type": "string" }, "id": { "type": "string" }, "lastUsedAt": { "type": "string" }, "name": { "type": "string" }, "plaintext": { "type": "string" }, "prefix": { "description": "\"sk_live_aB3x\" (first 12 chars), safe to display", "type": "string" }, "revokedAt": { "type": "string" }, "tenantId": { "type": "string" } } }, "apikeys.ListAPIKeysResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/apikeys.View" } } } }, "apikeys.View": { "type": "object", "properties": { "createdAt": { "type": "string" }, "id": { "type": "string" }, "lastUsedAt": { "type": "string" }, "name": { "type": "string" }, "prefix": { "description": "\"sk_live_aB3x\" (first 12 chars), safe to display", "type": "string" }, "revokedAt": { "type": "string" }, "tenantId": { "type": "string" } } }, "cancel_subscription.Result": { "type": "object", "properties": { "entitledUntil": { "type": "string" } } }, "confirm_unsubscribe.ConfirmUnsubscribeRequest": { "type": "object", "properties": { "token": { "type": "string" } } }, "confirm_unsubscribe.Response": { "type": "object", "properties": { "email": { "type": "string" }, "status": { "type": "string" } } }, "create_endpoint.CreateEndpointRequest": { "type": "object", "properties": { "description": { "type": "string" }, "eventTypes": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string" } } }, "create_endpoint.Result": { "type": "object", "properties": { "description": { "type": "string" }, "eventTypes": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string" }, "secret": { "description": "returned ONCE on creation; never again", "type": "string" }, "status": { "type": "string" }, "url": { "type": "string" } } }, "create_identity.CreateIdentityRequest": { "type": "object", "properties": { "name": { "type": "string" } } }, "create_identity.CreateIdentityResult": { "type": "object", "properties": { "bounceSubdomain": { "type": "string" }, "dkimSelector": { "type": "string" }, "identityId": { "type": "string" }, "name": { "type": "string" }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/create_identity.DNSRecord" } }, "smtpHostname": { "type": "string" } } }, "create_identity.DNSRecord": { "type": "object", "properties": { "host": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" } } }, "disable_address.DisableAddressResult": { "type": "object", "properties": { "identityId": { "type": "string" }, "localPart": { "type": "string" }, "status": { "type": "string" } } }, "disable_address.disableAddressRequest": { "type": "object", "properties": { "reason": { "type": "string" } } }, "domain.Plan": { "type": "object", "properties": { "currency": { "type": "string" }, "domainLimit": { "type": "integer" }, "includedEmails": { "type": "integer" }, "monthlyEmailQuota": { "type": "integer" }, "name": { "type": "string" }, "priceCents": { "type": "integer" } } }, "domain.TenantPlan": { "type": "object", "properties": { "currentPeriodEnd": { "type": "string" }, "currentPeriodStart": { "type": "string" }, "plan": { "$ref": "#/components/schemas/domain.Plan" }, "tenantId": { "type": "string" } } }, "domain.Variable": { "type": "object", "properties": { "name": { "type": "string" }, "required": { "type": "boolean" } } }, "downgrade_subscription.DowngradeRequest": { "type": "object", "properties": { "plan": { "description": "Plan is the smaller tier to move to at the next renewal.", "type": "string" } } }, "downgrade_subscription.Result": { "type": "object", "properties": { "effectiveAt": { "type": "string" }, "pendingPlanName": { "type": "string" } } }, "echo.HTTPError": { "type": "object", "properties": { "message": {} } }, "events.RecordCheck": { "type": "object", "properties": { "error": { "type": "string" }, "found": { "type": "boolean" }, "match": { "type": "boolean" } } }, "extract_brand.ExtractBrandRequest": { "type": "object", "properties": { "html": { "type": "string" }, "url": { "type": "string" } } }, "extract_brand.Response": { "type": "object", "properties": { "finalUrl": { "type": "string" }, "source": { "description": "\"url\" | \"html\"", "type": "string" }, "suggestion": { "$ref": "#/components/schemas/providers.Suggestion" } } }, "get_billing_state.State": { "type": "object", "properties": { "cancelAtPeriodEnd": { "description": "CancelAtPeriodEnd reports that future charges are stopped while the paid\nperiod still runs.", "type": "boolean" }, "currentPeriodEnd": { "type": "string" }, "currentPeriodStart": { "type": "string" }, "endsAt": { "description": "EndsAt is the deadline the tenant is still acting inside when a payment\nfailed. Empty once access has already stopped: there is no future date\nleft to promise.", "type": "string" }, "entitled": { "description": "Entitled reports whether the tenant may currently be served on their paid\ntier. A canceled subscription is still entitled until the period lapses.", "type": "boolean" }, "hasSubscription": { "description": "HasSubscription is false for a tenant who never paid. Never having\nsubscribed is not a payment problem.", "type": "boolean" }, "pendingPlanEffectiveAt": { "type": "string" }, "pendingPlanName": { "description": "PendingPlanName is a scheduled downgrade that has not fired. It grants\nnothing — it is a promise about the next period.", "type": "string" }, "planName": { "type": "string" }, "state": { "description": "State is one of healthy, payment_failed, suspended.", "type": "string" }, "status": { "description": "Status is the raw lifecycle status: active, past_due, canceled.", "type": "string" } } }, "get_usage.CurrentPeriodView": { "type": "object", "properties": { "byIdentity": { "type": "array", "items": { "$ref": "#/components/schemas/get_usage.IdentityBreakdown" } }, "includedEmails": { "description": "IncludedEmails is what the subscription price buys. On a plan with no\nhard cap it is the only number that tells a tenant where billing starts,\nsince Limit is -1 there.", "type": "integer" }, "limit": { "description": "-1 means unlimited", "type": "integer" }, "overageCents": { "type": "integer" }, "overageEmails": { "description": "OverageEmails is how much of SentCount sits past IncludedEmails, and\nOverageCents what it would cost. Reported, not yet invoiced — see the\nnote on Pro in plans/domain/catalog.go.", "type": "integer" }, "periodStart": { "type": "string" }, "plan": { "type": "string" }, "sentCount": { "type": "integer" } } }, "get_usage.HistoryEntry": { "type": "object", "properties": { "limit": { "type": "integer" }, "periodStart": { "type": "string" }, "sentCount": { "type": "integer" } } }, "get_usage.IdentityBreakdown": { "type": "object", "properties": { "identityId": { "type": "string" }, "identityName": { "type": "string" }, "sentCount": { "type": "integer" } } }, "get_usage.UsageResponse": { "type": "object", "properties": { "currentPeriod": { "$ref": "#/components/schemas/get_usage.CurrentPeriodView" }, "history": { "type": "array", "items": { "$ref": "#/components/schemas/get_usage.HistoryEntry" } } } }, "ingest_bounce.Response": { "type": "object", "properties": { "action": { "type": "string" }, "permanent": { "type": "boolean" }, "recipient": { "type": "string" }, "status": { "type": "string" }, "suppression": { "$ref": "#/components/schemas/add_suppression.Response" } } }, "list_endpoints.Result": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/repository.EndpointView" } } } }, "list_identities.Response": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/repository.IdentityView" } } } }, "list_messages.Result": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/repository.MessageView" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" } } }, "list_suppressions.Response": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/repository.SuppressionView" } } } }, "list_templates.Response": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/list_templates.View" } } } }, "list_templates.View": { "type": "object", "properties": { "defaultLocale": { "type": "string" }, "description": { "type": "string" }, "id": { "type": "string" }, "locales": { "type": "array", "items": { "type": "string" } }, "name": { "type": "string" }, "preview": { "type": "string" }, "variables": { "type": "array", "items": { "$ref": "#/components/schemas/domain.Variable" } } } }, "list_unsubscribes.Response": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/repository.UnsubscribeView" } } } }, "preview_template.PreviewTemplateRequest": { "type": "object", "properties": { "identityId": { "type": "string" }, "locale": { "type": "string" }, "variables": { "type": "object", "additionalProperties": { "type": "string" } } } }, "preview_template.Response": { "type": "object", "properties": { "bodyHtml": { "type": "string" }, "bodyText": { "type": "string" }, "locale": { "type": "string" }, "subject": { "type": "string" } } }, "providers.Suggestion": { "type": "object", "properties": { "appName": { "type": "string" }, "fontFamily": { "type": "string" }, "logoUrl": { "type": "string" }, "primaryColor": { "type": "string" }, "websiteUrl": { "type": "string" } } }, "repository.AddressView": { "type": "object", "properties": { "addedAt": { "type": "string" }, "label": { "type": "string" }, "localPart": { "type": "string" }, "status": { "type": "string" }, "updatedAt": { "type": "string" } } }, "repository.AttemptView": { "type": "object", "properties": { "attemptNum": { "type": "integer" }, "error": { "type": "string" }, "mtaResponse": { "type": "string" }, "occurredAt": { "type": "string" }, "outcome": { "type": "string" } } }, "repository.BrandView": { "type": "object", "properties": { "appName": { "type": "string" }, "createdAt": { "type": "string" }, "fontFamily": { "type": "string" }, "footerText": { "type": "string" }, "identityId": { "type": "string" }, "locale": { "type": "string" }, "logoUrl": { "type": "string" }, "primaryColor": { "type": "string" }, "supportEmail": { "type": "string" }, "tenantId": { "type": "string" }, "updatedAt": { "type": "string" }, "websiteUrl": { "type": "string" } } }, "repository.EndpointView": { "type": "object", "properties": { "createdAt": { "type": "string" }, "description": { "type": "string" }, "eventTypes": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string" }, "status": { "type": "string" }, "tenantId": { "type": "string" }, "updatedAt": { "type": "string" }, "url": { "type": "string" } } }, "repository.IdentityView": { "type": "object", "properties": { "addresses": { "type": "array", "items": { "$ref": "#/components/schemas/repository.AddressView" } }, "bounceSubdomain": { "type": "string" }, "createdAt": { "type": "string" }, "dkimPublicKey": { "type": "string" }, "dkimSelector": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "smtpHostname": { "type": "string" }, "status": { "type": "string" }, "tenantId": { "type": "string" }, "updatedAt": { "type": "string" } } }, "repository.MessageView": { "type": "object", "properties": { "attempts": { "type": "integer" }, "createdAt": { "type": "string" }, "failedAt": { "type": "string" }, "from": { "type": "string" }, "history": { "type": "array", "items": { "$ref": "#/components/schemas/repository.AttemptView" } }, "id": { "type": "string" }, "identityId": { "type": "string" }, "lastError": { "type": "string" }, "mtaResponse": { "type": "string" }, "rfc5322Id": { "type": "string" }, "sentAt": { "type": "string" }, "status": { "type": "string" }, "subject": { "type": "string" }, "tenantId": { "type": "string" }, "to": { "type": "array", "items": { "type": "string" } }, "updatedAt": { "type": "string" } } }, "repository.StateView": { "type": "object", "properties": { "belowMinVolume": { "type": "boolean" }, "bouncedCount": { "type": "integer" }, "frozenAt": { "type": "string" }, "frozenBounced": { "type": "integer" }, "frozenRate": { "type": "number" }, "frozenSent": { "type": "integer" }, "rate": { "type": "number" }, "sentCount": { "type": "integer" }, "state": { "type": "string" }, "tenantId": { "type": "string" }, "threshold": { "type": "number" }, "windowHours": { "type": "integer" } } }, "repository.SuppressionView": { "type": "object", "properties": { "createdAt": { "type": "string" }, "email": { "type": "string" }, "id": { "type": "string" }, "messageId": { "type": "string" }, "reason": { "type": "string" }, "smtpCode": { "type": "string" }, "source": { "type": "string" }, "status": { "type": "string" }, "tenantId": { "type": "string" }, "updatedAt": { "type": "string" } } }, "repository.UnsubscribeView": { "type": "object", "properties": { "category": { "type": "string" }, "createdAt": { "type": "string" }, "email": { "type": "string" }, "id": { "type": "string" }, "messageId": { "type": "string" }, "source": { "type": "string" }, "userAgent": { "type": "string" } } }, "rotate_secret.Result": { "type": "object", "properties": { "id": { "type": "string" }, "secret": { "description": "returned ONCE on rotation", "type": "string" } } }, "send_email.QuotaErrorBody": { "type": "object", "properties": { "current": { "type": "integer" }, "limit": { "type": "integer" }, "message": { "type": "string" }, "plan": { "type": "string" } } }, "send_email.SendEmailRequest": { "type": "object", "properties": { "from": { "type": "string" }, "html": { "type": "string" }, "identityId": { "description": "IdentityID is optional and deprecated. When omitted, the server\nresolves the identity from the domain of the From address — match the\nindustry baseline (Resend, SES, Postmark). When provided, it must\nagree with the From domain; otherwise the request is rejected.", "type": "string" }, "locale": { "type": "string" }, "subject": { "type": "string" }, "template": { "type": "string" }, "text": { "type": "string" }, "to": { "type": "array", "items": { "type": "string" } }, "unsubscribe": { "$ref": "#/components/schemas/send_email.UnsubscribeOptions" }, "variables": { "type": "object", "additionalProperties": { "type": "string" } } } }, "send_email.SendEmailResult": { "type": "object", "properties": { "messageId": { "description": "internal aggregate id", "type": "string" }, "rfc5322Id": { "description": "value of the RFC 5322 Message-ID header", "type": "string" }, "status": { "type": "string" } } }, "send_email.UnsubscribeOptions": { "type": "object", "properties": { "category": { "description": "free-form, e.g. \"marketing\", \"notifications\". Defaults to \"default\".", "type": "string" }, "enabled": { "type": "boolean" } } }, "send_test_email.SendTestEmailRequest": { "type": "object", "properties": { "from": { "type": "string" }, "identityId": { "type": "string" }, "to": { "type": "string" } } }, "send_test_email.SendTestEmailResult": { "type": "object", "properties": { "messageId": { "type": "string" }, "rfc5322Id": { "type": "string" }, "status": { "type": "string" } } }, "set_brand.Response": { "type": "object", "properties": { "appName": { "type": "string" }, "fontFamily": { "type": "string" }, "footerText": { "type": "string" }, "identityId": { "type": "string" }, "locale": { "type": "string" }, "logoUrl": { "type": "string" }, "primaryColor": { "type": "string" }, "supportEmail": { "type": "string" }, "tenantId": { "type": "string" }, "websiteUrl": { "type": "string" } } }, "set_brand.SetBrandRequest": { "type": "object", "properties": { "appName": { "type": "string" }, "fontFamily": { "type": "string" }, "footerText": { "type": "string" }, "locale": { "type": "string" }, "logoUrl": { "type": "string" }, "primaryColor": { "type": "string" }, "supportEmail": { "type": "string" }, "websiteUrl": { "type": "string" } } }, "set_tenant_plan.SetTenantPlanRequest": { "type": "object", "properties": { "plan": { "type": "string" }, "tenantId": { "type": "string" } } }, "start_checkout.Result": { "type": "object", "properties": { "checkoutUrl": { "type": "string" } } }, "start_checkout.StartCheckoutRequest": { "type": "object", "properties": { "email": { "description": "Email and Name are optional; the server resolves the billing contact when\nthey are absent.", "type": "string" }, "name": { "type": "string" }, "plan": { "description": "Plan is the tier being bought. Only purchasable tiers are accepted:\nreaching the free tier is a cancellation, not a purchase.", "type": "string" }, "successUrl": { "description": "SuccessURL overrides where the customer lands after paying.", "type": "string" } } }, "unfreeze.Response": { "type": "object", "properties": { "reason": { "type": "string" }, "state": { "type": "string" }, "tenantId": { "type": "string" }, "unfrozenAt": { "type": "string" } } }, "unfreeze.UnfreezeRequest": { "type": "object", "properties": { "actor": { "type": "string" }, "reason": { "type": "string" } } }, "update_endpoint.UpdateEndpointRequest": { "type": "object", "properties": { "description": { "type": "string" }, "disabled": { "type": "boolean" }, "eventTypes": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string" } } }, "upgrade_subscription.Quote": { "type": "object", "properties": { "currency": { "type": "string" }, "fromPlanName": { "type": "string" }, "periodEnd": { "description": "PeriodEnd is when the current period runs out, and therefore when the\nfull price of the new tier starts applying.", "type": "string" }, "proratedCents": { "type": "integer" }, "toPlanName": { "type": "string" } } }, "upgrade_subscription.QuoteRequest": { "type": "object", "properties": { "plan": { "type": "string" } } }, "upgrade_subscription.Result": { "type": "object", "properties": { "chargedCents": { "type": "integer" }, "currency": { "type": "string" }, "paymentId": { "type": "string" }, "planName": { "type": "string" } } }, "upgrade_subscription.UpgradeRequest": { "type": "object", "properties": { "acceptedCents": { "description": "AcceptedCents is the prorated amount the customer agreed to, from a prior\nquote. It is verified against a freshly computed amount: a stale quote\nmust not authorise a different charge.", "type": "integer" }, "consented": { "description": "Consented records that the amount was shown and agreed to. Required for\nany charge above the proration floor.", "type": "boolean" }, "plan": { "description": "Plan is the larger tier to move to.", "type": "string" } } }, "verify_identity.ChecksResult": { "type": "object", "properties": { "bounce": { "$ref": "#/components/schemas/events.RecordCheck" }, "dkim": { "$ref": "#/components/schemas/events.RecordCheck" }, "dmarc": { "$ref": "#/components/schemas/events.RecordCheck" }, "spf": { "$ref": "#/components/schemas/events.RecordCheck" } } }, "verify_identity.VerifyIdentityResult": { "type": "object", "properties": { "checks": { "$ref": "#/components/schemas/verify_identity.ChecksResult" }, "identityId": { "type": "string" }, "status": { "type": "string" } } } } } }