{ "openapi": "3.1.0", "info": { "title": "Spoolway API", "version": "v1", "summary": "Send transactional mail through your own SMTP server or provider, and keep a searchable archive of what was sent.", "description": "Every endpoint takes an API key whose abilities were fixed when it was minted. `messages:send` and `messages:read-content` are mutually exclusive by design, so a key that can send can never read a body.\n\nAccepting a message is not delivering it. `POST /api/v1/messages` answers 202 with an id once the message is archived and queued; what happened next is on the message itself.\n\nErrors carry a `type` you can branch on, alongside a `message` written for a person.", "contact": { "url": "https://spoolway.com/contact" } }, "servers": [ { "url": "https://spoolway.com", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Messages", "description": "Sending, and the archive of what was sent." }, { "name": "Suppressions", "description": "Addresses this account will not send to." }, { "name": "Applications", "description": "Which of your products sent this." }, { "name": "Templates", "description": "Read-only here; authored in the panel or in git." }, { "name": "Domains", "description": "Sending domains and their DNS evidence." }, { "name": "Transports", "description": "Your own SMTP servers and providers." }, { "name": "Usage", "description": "Counters for the current period." } ], "paths": { "/api/v1/applications": { "get": { "operationId": "listApplications", "summary": "List Applications", "tags": [ "Applications" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationList" } } } }, "403": { "description": "The key lacks the ability this call needs, or the account cannot send.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-ability": "applications:read" }, "post": { "operationId": "createApplication", "summary": "Create an Application", "tags": [ "Applications" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApplicationRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Application" } } } }, "403": { "description": "The key lacks the ability this call needs, or the account cannot send.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request is well-formed but cannot be carried out. The body says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-ability": "applications:write" } }, "/api/v1/applications/{id}": { "get": { "operationId": "getApplication", "summary": "Get one Application", "tags": [ "Applications" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Application" } } } }, "403": { "description": "The key lacks the ability this call needs, or the account cannot send.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-ability": "applications:read" } }, "/api/v1/dmarc-reports": { "get": { "operationId": "listDmarcReports", "summary": "What the reports say", "tags": [ "Domains" ], "description": "Aggregate counts per reporting period. A report row names a sending IP; the format carries no recipient addresses.", "parameters": [ { "name": "domain", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DmarcReportList" } } } }, "403": { "description": "The key lacks the ability this call needs, or the account cannot send.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-ability": "domains:read" }, "post": { "operationId": "submitDmarcReport", "summary": "Hand us a DMARC aggregate report", "tags": [ "Domains" ], "description": "The request body is the report file itself \u2014 gzip, zip or plain XML \u2014 or a multipart field named `report`. Providers send these to the address in a domain's rua= tag; forward the attachment here from your own reporting mailbox. Submitting the same report twice replaces it rather than doubling its numbers.", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DmarcReportAccepted" } } } }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DmarcReportAccepted" } } } }, "403": { "description": "The key lacks the ability this call needs, or the account cannot send.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The file is larger than any real report.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request is well-formed but cannot be carried out. The body says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-ability": "domains:read" } }, "/api/v1/domains": { "get": { "operationId": "listDomains", "summary": "List sending domains", "tags": [ "Domains" ], "description": "A verification older than 24 hours reads as \"correct at last check\" rather than verified \u2014 an indicator never outlives its evidence.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainList" } } } }, "403": { "description": "The key lacks the ability this call needs, or the account cannot send.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-ability": "domains:read" } }, "/api/v1/domains/{id}": { "get": { "operationId": "getDomain", "summary": "Get one sending domain", "tags": [ "Domains" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } } }, "403": { "description": "The key lacks the ability this call needs, or the account cannot send.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-ability": "domains:read" } }, "/api/v1/messages": { "get": { "operationId": "listMessages", "summary": "List messages", "tags": [ "Messages" ], "description": "Newest first, cursor-paginated. Filters narrow by application, template, status, recipient, tag, trigger and date range.", "parameters": [ { "name": "application", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "template", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "recipient", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "tag", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "trigger", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageList" } } } }, "403": { "description": "The key lacks the ability this call needs, or the account cannot send.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request is well-formed but cannot be carried out. The body says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-ability": "messages:read" }, "post": { "operationId": "sendMessage", "summary": "Send a message", "tags": [ "Messages" ], "description": "Accepts the message and returns immediately with an id. Delivery happens on a worker, so a 202 means accepted and archived, never delivered \u2014 ask the message's own endpoint for that. A template with a variables schema refuses here, listing every missing name at once.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMessageRequest" } } } }, "responses": { "202": { "description": "Accepted and archived. Not delivered \u2014 delivery happens on a worker.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptedMessage" } } } }, "403": { "description": "The key lacks the ability this call needs, or the account cannot send.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request is well-formed but cannot be carried out. The body says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "A limit bound. The body names which one and in what unit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A dependency this call needs is unavailable. Retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-ability": "messages:send" } }, "/api/v1/messages/{id}": { "get": { "operationId": "getMessage", "summary": "Get one message with its attempts and events", "tags": [ "Messages" ], "description": "Metadata only. The body lives behind its own endpoint so that opening it is a distinct, audited act.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "403": { "description": "The key lacks the ability this call needs, or the account cannot send.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-ability": "messages:read" } }, "/api/v1/messages/{id}/content": { "get": { "operationId": "getMessageContent", "summary": "Open the stored body", "tags": [ "Messages" ], "description": "A separate, audit-logged act, counted against the content-view quota. Answers 410 once the retention window has passed, because the body is gone rather than hidden.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageContent" } } } }, "403": { "description": "The key lacks the ability this call needs, or the account cannot send.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "It existed and is gone \u2014 the retention window has passed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "A limit bound. The body names which one and in what unit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-ability": "messages:read-content" } }, "/api/v1/suppressions": { "get": { "operationId": "listSuppressions", "summary": "List suppressed addresses", "tags": [ "Suppressions" ], "parameters": [ { "name": "reason", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuppressionList" } } } }, "403": { "description": "The key lacks the ability this call needs, or the account cannot send.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-ability": "suppressions:read" }, "post": { "operationId": "createSuppression", "summary": "Suppress an address", "tags": [ "Suppressions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSuppressionRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Suppression" } } } }, "403": { "description": "The key lacks the ability this call needs, or the account cannot send.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request is well-formed but cannot be carried out. The body says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-ability": "suppressions:write" } }, "/api/v1/suppressions/lookup": { "get": { "operationId": "lookupSuppression", "summary": "Ask whether one address is suppressed", "tags": [ "Suppressions" ], "description": "Matches an erased identity as well as a plain address, so an address erased under Article 17 still reads as suppressed.", "parameters": [ { "name": "email", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuppressionLookup" } } } }, "403": { "description": "The key lacks the ability this call needs, or the account cannot send.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request is well-formed but cannot be carried out. The body says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-ability": "suppressions:read" } }, "/api/v1/suppressions/{id}": { "delete": { "operationId": "deleteSuppression", "summary": "Lift a suppression", "tags": [ "Suppressions" ], "description": "Refuses with 409 on a row whose identity was erased: the address is gone, and re-adding it would write it back.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Done. No body." }, "403": { "description": "The key lacks the ability this call needs, or the account cannot send.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Refused because of the resource's own state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-ability": "suppressions:write" }, "get": { "operationId": "getSuppression", "summary": "Get one suppression", "tags": [ "Suppressions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Suppression" } } } }, "403": { "description": "The key lacks the ability this call needs, or the account cannot send.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-ability": "suppressions:read" } }, "/api/v1/templates": { "get": { "operationId": "listTemplates", "summary": "List templates", "tags": [ "Templates" ], "description": "Read-only. Templates are authored in the panel or in a connected git repository; the API never mints a version.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateList" } } } }, "403": { "description": "The key lacks the ability this call needs, or the account cannot send.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-ability": "templates:read" } }, "/api/v1/templates/by-slug/{slug}": { "get": { "operationId": "getTemplateBySlug", "summary": "Get a template by slug", "tags": [ "Templates" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Template" } } } }, "403": { "description": "The key lacks the ability this call needs, or the account cannot send.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-ability": "templates:read" } }, "/api/v1/templates/{id}": { "get": { "operationId": "getTemplate", "summary": "Get a template by id", "tags": [ "Templates" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Template" } } } }, "403": { "description": "The key lacks the ability this call needs, or the account cannot send.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-ability": "templates:read" } }, "/api/v1/transports": { "get": { "operationId": "listTransports", "summary": "List transports", "tags": [ "Transports" ], "description": "Credentials are never returned. A health check older than 24 hours reads unknown rather than healthy.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransportList" } } } }, "403": { "description": "The key lacks the ability this call needs, or the account cannot send.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-ability": "transports:read" } }, "/api/v1/transports/{id}": { "get": { "operationId": "getTransport", "summary": "Get one transport", "tags": [ "Transports" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transport" } } } }, "403": { "description": "The key lacks the ability this call needs, or the account cannot send.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-ability": "transports:read" } }, "/api/v1/usage": { "get": { "operationId": "getUsage", "summary": "Current period counters", "tags": [ "Usage" ], "description": "The monthly allowance is a signal and never refuses a send; the daily cap does refuse, and names the layer that bound.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" } } } }, "403": { "description": "The key lacks the ability this call needs, or the account cannot send.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-ability": "usage:read" } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "An API key, as `Authorization: Bearer spw_\u2026`. `X-Api-Key` is accepted too. Abilities are chosen when the key is minted and can never be widened." } }, "schemas": { "Error": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "Written for a person to read." }, "type": { "type": "string", "description": "Branch on this rather than on the message.", "enum": [ "forbidden_ability", "sealed_body_denied", "limit_exceeded", "no_usable_transport", "dependency_unavailable", "body_unreadable", "content_view_quota_exceeded", "cursor_expired", "erasure_locked", "edge_rate_limited", "empty_report", "unreadable_report", "report_too_large" ] }, "required_ability": { "type": "string" } } }, "SendMessageRequest": { "type": "object", "required": [ "to" ], "description": "Either a template or an html/text body. Not both halves of the same thing.", "properties": { "to": { "oneOf": [ { "oneOf": [ { "type": "string", "format": "email" }, { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string" } } } ] }, { "type": "array", "items": { "oneOf": [ { "type": "string", "format": "email" }, { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string" } } } ] } } ] }, "cc": { "type": "array", "items": { "oneOf": [ { "type": "string", "format": "email" }, { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string" } } } ] } }, "bcc": { "type": "array", "items": { "oneOf": [ { "type": "string", "format": "email" }, { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string" } } } ] } }, "template": { "type": "string", "description": "Template slug." }, "template_version_id": { "type": "integer", "description": "Pin an exact version instead of the current one." }, "locale": { "type": "string", "description": "The recipient's locale. `welcome` with `de-AT` tries `welcome.de-AT`, then `welcome.de`, then `welcome`, so the send always goes out.", "examples": [ "de-AT", "pt-BR" ] }, "variables": { "type": "object", "additionalProperties": true }, "subject": { "type": "string" }, "html": { "type": "string" }, "text": { "type": "string" }, "from": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string" } } }, "reply_to": { "type": "string", "format": "email" }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Headers the transport reserves are refused here rather than at delivery." }, "attachments": { "type": "array", "items": { "type": "object", "required": [ "filename", "content" ], "properties": { "filename": { "type": "string" }, "content": { "type": "string", "contentEncoding": "base64" }, "content_type": { "type": "string" } } } }, "transport": { "type": "string" }, "application": { "type": "string", "description": "Required when the key is not scoped to one." }, "tags": { "type": "array", "items": { "type": "string" } }, "trigger": { "type": "string" }, "idempotency_key": { "type": "string", "description": "Also accepted as the `Idempotency-Key` header." } } }, "AcceptedMessage": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "application_id": { "type": "integer" }, "over_monthly_quota": { "type": "boolean", "description": "A signal. It never refuses the send." }, "attachments_captured": { "type": "integer" } } }, "Message": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "subject": { "type": [ "string", "null" ], "description": "Null when the template is sensitive." }, "application": { "type": [ "string", "null" ] }, "template": { "type": [ "string", "null" ] }, "transport": { "type": [ "string", "null" ] }, "recipients": { "type": "array", "items": { "type": "object" } }, "attempts": { "type": "array", "items": { "type": "object" } }, "events": { "type": "array", "items": { "type": "object" } }, "queued_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "MessageContent": { "type": "object", "properties": { "html": { "type": [ "string", "null" ] }, "text": { "type": [ "string", "null" ] }, "variables": { "type": [ "object", "null" ], "additionalProperties": true } } }, "MessageList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "Suppression": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string", "description": "An erased identity reads as an opaque token, not an address." }, "reason": { "type": "string" }, "source": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "SuppressionList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Suppression" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "SuppressionLookup": { "type": "object", "properties": { "suppressed": { "type": "boolean" }, "suppression": { "oneOf": [ { "$ref": "#/components/schemas/Suppression" }, { "type": "null" } ] } } }, "CreateSuppressionRequest": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" }, "reason": { "type": "string" } } }, "Application": { "type": "object", "properties": { "id": { "type": "integer" }, "slug": { "type": "string" }, "name": { "type": "string" }, "environment": { "type": "string" } } }, "ApplicationList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Application" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "CreateApplicationRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "environment": { "type": "string" } } }, "Template": { "type": "object", "properties": { "id": { "type": "integer" }, "slug": { "type": "string" }, "name": { "type": "string" }, "source": { "type": "string", "enum": [ "git", "panel", "api" ] }, "engine": { "type": [ "string", "null" ], "enum": [ "twig", "liquid", null ] }, "version": { "type": [ "integer", "null" ] }, "git_sha": { "type": [ "string", "null" ] }, "variables_schema": { "type": [ "object", "null" ], "additionalProperties": true, "description": "The variable contract. A send missing any required name is refused with all of them listed." } } }, "TemplateList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Template" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "Domain": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "state": { "type": "string", "enum": [ "verified", "failing", "pending" ], "description": "`failing` while failed_at is set and later than verified_at, or set on a domain that never verified." }, "status_label": { "type": "string", "description": "The sentence the panel prints for this domain, such as \"correct at last check \u2014 not yet re-verified\". Written for a person; branch on state." }, "check_is_stale": { "type": "boolean", "description": "True when the latest check is 24 hours old or more, or there has been none. A stale check is not a live green tick." }, "verified_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the ownership check last passed. A later failure does not clear it." }, "failed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the ownership check last failed. The next check that passes clears it." }, "last_checked_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The most recent check of any of its records." }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/DomainRecord" } } } }, "DomainRecord": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "purpose": { "type": "string" }, "name": { "type": "string" }, "expected": { "type": [ "string", "null" ] }, "observed": { "type": [ "string", "null" ] }, "state": { "type": "string", "enum": [ "unchecked", "missing", "ok", "observed", "drifted" ], "description": "`observed` is a record we read and do not prescribe, such as a DMARC policy." }, "checked_at": { "type": [ "string", "null" ], "format": "date-time" }, "verified_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "DomainList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Domain" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "Transport": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "type": { "type": "string" }, "health": { "type": "string" }, "health_checked_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "TransportList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Transport" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "DmarcReport": { "type": "object", "properties": { "id": { "type": "integer" }, "domain": { "type": "string" }, "org_name": { "type": "string", "description": "Who sent the report \u2014 google.com, outlook.com." }, "report_id": { "type": "string" }, "range_begin": { "type": "string", "format": "date-time" }, "range_end": { "type": "string", "format": "date-time" }, "policy_p": { "type": [ "string", "null" ], "enum": [ "none", "quarantine", "reject", null ], "description": "The policy the reporter found published. `none` means receivers were asked to do nothing about failures." }, "messages": { "type": "integer" }, "passed": { "type": "integer", "description": "DMARC passes when EITHER SPF or DKIM aligns, not both." }, "failed": { "type": "integer" } } }, "DmarcReportList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DmarcReport" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "DmarcReportAccepted": { "type": "object", "properties": { "id": { "type": "integer" }, "domain": { "type": "string" }, "org_name": { "type": "string" }, "rows": { "type": "integer" }, "messages": { "type": "integer" }, "passed": { "type": "integer" }, "failed": { "type": "integer" }, "replaced": { "type": "boolean", "description": "True when this replaced a report already held under the same id." } } }, "Usage": { "type": "object", "properties": { "daily": { "type": "object", "additionalProperties": true }, "monthly": { "type": "object", "additionalProperties": true } } } } } }