{ "openapi": "3.1.0", "info": { "title": "MailKaro Cloud API", "version": "3.0.0", "summary": "Render email designs and manage templates, sends, webhooks, and domains.", "description": "The MailKaro Cloud API (v3) lets your backend render structured email designs to inbox-safe HTML/MJML and manage templates, transactional sends, delivery events, suppressions, webhooks, and sending domains. Authenticate every request with a publishable embed token (`pk_live_…`) or a server key (`sk_live_…`) as a Bearer token. All data is scoped to the organization that owns the token. See the guides at https://docs.mailkaro.com.\n\n## Versioning & deprecation policy\n\nThe API is versioned in the URL path (`/v3/…`). Breaking changes ship under a new path version; the current major version is v3. When an endpoint or version is deprecated, responses carry a `Deprecation` header (an HTTP-date) and, once an end-of-life date is set, a `Sunset` header (RFC 8594) with a link to migration docs. We aim to give at least 6 months between a `Sunset` announcement and removal. Integrate against a path-versioned surface and watch for these headers.\n\n## Rate limits\n\nEvery response advertises RFC RateLimit headers so agents can self-throttle: `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` (seconds until the window resets), and `RateLimit-Policy` (quota;w=window-seconds). A `429 Too Many Requests` additionally returns `Retry-After`. Back off until the reset window elapses.\n\n## Errors\n\nEvery error response uses a consistent typed body: a machine-readable `error` code and a human-readable `message` (see the Error schema). 4xx and 5xx responses across all operations follow this shape.", "contact": { "name": "MailKaro Support", "email": "support@mailkaro.com", "url": "https://docs.mailkaro.com" }, "license": { "name": "Proprietary", "url": "https://mailkaro.com/terms" }, "x-api-lifecycle": { "version": "v3", "status": "active", "versioning": "url-path", "deprecationHeaders": [ "Deprecation", "Sunset" ], "policyUrl": "https://mailkaro.com/developers#versioning" } }, "servers": [ { "url": "https://api.mailkaro.com", "description": "Production" } ], "externalDocs": { "description": "MailKaro documentation", "url": "https://docs.mailkaro.com" }, "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Rendering", "description": "Turn a design into email-safe HTML, MJML, AMP, or plain text." }, { "name": "Templates", "description": "Store and retrieve saved email designs." }, { "name": "Email", "description": "Send transactional email and manage delivery events and suppressions." }, { "name": "Webhooks", "description": "Receive signed events for your organization." }, { "name": "Domains", "description": "Manage verified sending domains." }, { "name": "Status", "description": "Public service status and rate-limit header verification." } ], "paths": { "/v3/health": { "get": { "operationId": "getApiHealth", "tags": [ "Status" ], "summary": "API status", "description": "Public, unauthenticated status ping. Returns 200 with basic service info and carries the standard RateLimit headers, so agents can confirm the API is up and verify the rate-limit policy on a live response.", "security": [], "responses": { "200": { "description": "The API is up.", "headers": { "RateLimit-Limit": { "description": "Request quota for the current window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The active quota policy, e.g. \"600;w=60\".", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": ["status"], "properties": { "status": { "type": "string", "example": "ok" }, "service": { "type": "string" }, "version": { "type": "string" }, "docs": { "type": "string", "format": "uri" }, "openapi": { "type": "string", "format": "uri" } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v3/render": { "post": { "operationId": "renderDesign", "tags": [ "Rendering" ], "summary": "Render a design", "description": "Render a MailKaro design object to a chosen output format. This endpoint is stateless: it only renders the design you send and touches no stored data. Returns the rendered output as a string.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenderRequest" } } } }, "responses": { "200": { "description": "Rendered output.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenderResponse" } } }, "headers": { "RateLimit-Limit": { "description": "Request quota for the current window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The active quota policy, e.g. \"600;w=60\".", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v3/templates": { "get": { "operationId": "listTemplates", "tags": [ "Templates" ], "summary": "List templates", "description": "List every saved template (email design) owned by the authenticated organization.", "responses": { "200": { "description": "The organization's templates.", "content": { "application/json": { "schema": { "type": "object", "required": [ "templates" ], "properties": { "templates": { "type": "array", "items": { "$ref": "#/components/schemas/Template" } } } } } }, "headers": { "RateLimit-Limit": { "description": "Request quota for the current window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The active quota policy, e.g. \"600;w=60\".", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "createTemplate", "tags": [ "Templates" ], "summary": "Create a template", "description": "Save a new email design as a template for the authenticated organization.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "design" ], "properties": { "name": { "type": "string", "maxLength": 200, "description": "Human-readable template name.", "default": "Untitled" }, "design": { "$ref": "#/components/schemas/Design" } } } } } }, "responses": { "201": { "description": "The created template.", "content": { "application/json": { "schema": { "type": "object", "required": [ "template" ], "properties": { "template": { "$ref": "#/components/schemas/TemplateSummary" } } } } }, "headers": { "RateLimit-Limit": { "description": "Request quota for the current window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The active quota policy, e.g. \"600;w=60\".", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v3/templates/{id}": { "get": { "operationId": "getTemplate", "tags": [ "Templates" ], "summary": "Get a template", "description": "Retrieve a single saved template, including its full design, by id.", "parameters": [ { "$ref": "#/components/parameters/TemplateId" } ], "responses": { "200": { "description": "The requested template.", "content": { "application/json": { "schema": { "type": "object", "required": [ "template" ], "properties": { "template": { "$ref": "#/components/schemas/Template" } } } } }, "headers": { "RateLimit-Limit": { "description": "Request quota for the current window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The active quota policy, e.g. \"600;w=60\".", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v3/emails": { "post": { "operationId": "sendEmail", "tags": [ "Email" ], "summary": "Send an email", "description": "Render a design (inline or by template_id) and send it to one recipient through your configured email provider. Suppressed recipients are skipped and reported as `suppressed`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendEmailRequest" } } } }, "responses": { "202": { "description": "The message was accepted for delivery (or suppressed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendEmailResponse" } } }, "headers": { "RateLimit-Limit": { "description": "Request quota for the current window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The active quota policy, e.g. \"600;w=60\".", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v3/emails/stats": { "get": { "operationId": "getEmailStats", "tags": [ "Email" ], "summary": "Get email statistics", "description": "Return aggregate send and delivery-event counts (sent, delivered, bounced, complaints) for the authenticated organization.", "responses": { "200": { "description": "Aggregated email statistics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailStats" } } }, "headers": { "RateLimit-Limit": { "description": "Request quota for the current window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The active quota policy, e.g. \"600;w=60\".", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v3/emails/suppressions": { "get": { "operationId": "listSuppressions", "tags": [ "Email" ], "summary": "List suppressed addresses", "description": "List every address on the organization's do-not-send suppression list.", "responses": { "200": { "description": "The suppression list.", "content": { "application/json": { "schema": { "type": "object", "required": [ "suppressions" ], "properties": { "suppressions": { "type": "array", "items": { "$ref": "#/components/schemas/Suppression" } } } } } }, "headers": { "RateLimit-Limit": { "description": "Request quota for the current window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The active quota policy, e.g. \"600;w=60\".", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "addSuppression", "tags": [ "Email" ], "summary": "Suppress an address", "description": "Add an email address to the organization's do-not-send suppression list.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "description": "Address to suppress." } } } } } }, "responses": { "200": { "description": "The updated suppression entry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Suppression" } } }, "headers": { "RateLimit-Limit": { "description": "Request quota for the current window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The active quota policy, e.g. \"600;w=60\".", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v3/emails/suppressions/{email}": { "delete": { "operationId": "removeSuppression", "tags": [ "Email" ], "summary": "Un-suppress an address", "description": "Remove an address from the organization's suppression list so it can receive mail again.", "parameters": [ { "name": "email", "in": "path", "required": true, "description": "URL-encoded email address to remove from the suppression list.", "schema": { "type": "string", "format": "email" } } ], "responses": { "200": { "description": "The address was removed (idempotent).", "content": { "application/json": { "schema": { "type": "object", "properties": { "removed": { "type": "boolean" } } } } }, "headers": { "RateLimit-Limit": { "description": "Request quota for the current window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The active quota policy, e.g. \"600;w=60\".", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v3/webhooks": { "get": { "operationId": "listWebhooks", "tags": [ "Webhooks" ], "summary": "List webhooks", "description": "List the webhook endpoints registered for the authenticated organization.", "responses": { "200": { "description": "Registered webhooks.", "content": { "application/json": { "schema": { "type": "object", "required": [ "webhooks" ], "properties": { "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } } } } }, "headers": { "RateLimit-Limit": { "description": "Request quota for the current window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The active quota policy, e.g. \"600;w=60\".", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "createWebhook", "tags": [ "Webhooks" ], "summary": "Register a webhook", "description": "Register a URL to receive signed events (for example `template.created`). The signing secret is returned once at creation; deliveries carry an `x-mailkaro-signature` header.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "HTTPS endpoint that will receive event deliveries." }, "events": { "type": "array", "description": "Event types to subscribe to. Omit to receive all.", "items": { "type": "string" } } } } } } }, "responses": { "201": { "description": "The created webhook, including its signing secret (shown once).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookWithSecret" } } }, "headers": { "RateLimit-Limit": { "description": "Request quota for the current window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The active quota policy, e.g. \"600;w=60\".", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v3/webhooks/{id}": { "delete": { "operationId": "deleteWebhook", "tags": [ "Webhooks" ], "summary": "Delete a webhook", "description": "Remove a registered webhook endpoint by id.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } }, "headers": { "RateLimit-Limit": { "description": "Request quota for the current window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The active quota policy, e.g. \"600;w=60\".", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v3/domains": { "get": { "operationId": "listDomains", "tags": [ "Domains" ], "summary": "List sending domains", "description": "List the sending domains configured for the authenticated organization, including verification status.", "responses": { "200": { "description": "Configured domains.", "content": { "application/json": { "schema": { "type": "object", "required": [ "domains" ], "properties": { "domains": { "type": "array", "items": { "$ref": "#/components/schemas/Domain" } } } } } }, "headers": { "RateLimit-Limit": { "description": "Request quota for the current window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The active quota policy, e.g. \"600;w=60\".", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "createDomain", "tags": [ "Domains" ], "summary": "Add a sending domain", "description": "Register a new sending domain. The response includes the DNS records to add for DKIM and verification.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string", "description": "The domain to send from, e.g. mail.example.com." } } } } } }, "responses": { "201": { "description": "The created domain with DNS records to configure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } }, "headers": { "RateLimit-Limit": { "description": "Request quota for the current window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The active quota policy, e.g. \"600;w=60\".", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "A publishable embed token (`pk_live_…`) or server key (`sk_live_…`) passed as `Authorization: Bearer `. Requests are scoped to the token's organization." } }, "parameters": { "TemplateId": { "name": "id", "in": "path", "required": true, "description": "The template's unique id.", "schema": { "type": "string" } } }, "responses": { "BadRequest": { "description": "The request body failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Missing or invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "Too many requests — slow down and retry after the window resets.", "headers": { "RateLimit-Limit": { "description": "Request quota for the current window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The active quota policy, e.g. \"600;w=60\".", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ServerError": { "description": "An unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error": { "description": "A typed error response (machine-readable code + human message).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Design": { "type": "object", "description": "A MailKaro design document (rows of content blocks). Treated as an opaque, structured JSON object by the API; see the design-schema docs for its shape.", "additionalProperties": true }, "RenderRequest": { "type": "object", "required": [ "design" ], "properties": { "design": { "$ref": "#/components/schemas/Design" }, "format": { "type": "string", "description": "Output format.", "enum": [ "html", "mjml", "amp", "text", "document" ], "default": "html" }, "merge_tags": { "type": "object", "description": "Merge-tag values to substitute into the design, keyed by tag name.", "additionalProperties": { "type": "string" } } } }, "RenderResponse": { "type": "object", "required": [ "format", "output" ], "properties": { "format": { "type": "string", "description": "The format that was rendered." }, "output": { "type": "string", "description": "The rendered output as a string." } } }, "Template": { "type": "object", "required": [ "id", "name", "design" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "design": { "$ref": "#/components/schemas/Design" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "TemplateSummary": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "SendEmailRequest": { "type": "object", "required": [ "to" ], "description": "Provide either `design` or `template_id` as the content source.", "properties": { "to": { "type": "string", "format": "email", "description": "Recipient address." }, "subject": { "type": "string", "maxLength": 500, "description": "Email subject line." }, "from": { "type": "string", "format": "email", "description": "Sender address on a verified domain. Defaults to your configured sender." }, "template_id": { "type": "string", "description": "Id of a saved template to render." }, "design": { "$ref": "#/components/schemas/Design" } } }, "SendEmailResponse": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "queued", "suppressed" ], "description": "`queued` when accepted, `suppressed` when the recipient is on the suppression list." }, "id": { "type": "string", "description": "Provider message id, present when queued." } } }, "EmailStats": { "type": "object", "properties": { "sent": { "type": "integer" }, "delivered": { "type": "integer" }, "bounced": { "type": "integer" }, "complaints": { "type": "integer" } } }, "Suppression": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" }, "reason": { "type": "string", "description": "Why the address was suppressed (e.g. bounce, complaint, manual)." }, "created_at": { "type": "string", "format": "date-time" } } }, "Webhook": { "type": "object", "required": [ "id", "url" ], "properties": { "id": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" } } }, "WebhookWithSecret": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "type": "object", "properties": { "secret": { "type": "string", "description": "The signing secret, returned only once at creation." } } } ] }, "Domain": { "type": "object", "required": [ "id", "domain", "status" ], "properties": { "id": { "type": "string" }, "domain": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "verified", "failed" ] }, "dns_records": { "type": "array", "description": "DNS records to add for DKIM and verification.", "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" } } } } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation." } } } } } }