{ "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/import": { "post": { "operationId": "importHtml", "tags": ["Rendering"], "summary": "Import HTML into a design", "description": "Convert an existing email's HTML into an editable MailKaro design (rows, columns, blocks). Best-effort and stateless: layout tables become sections and columns (with their widths and background colors), and headings, paragraphs, lists, images, buttons, dividers and spacing become typed blocks in document order, keeping colors, sizes, alignment, the content width, the title and the preview line. Text that cannot be placed is kept as text; if nothing is found the HTML is preserved in a raw-html block. The returned design is valid design JSON you can save via /v3/templates or edit in the embedded editor.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["html"], "properties": { "html": { "type": "string", "description": "The source email HTML to import." }, "title": { "type": "string", "maxLength": 200, "description": "Optional title for the imported design." } } } } } }, "responses": { "200": { "description": "The imported design.", "content": { "application/json": { "schema": { "type": "object", "required": ["design", "block_count", "used_fallback"], "properties": { "design": { "$ref": "#/components/schemas/Design" }, "block_count": { "type": "integer", "description": "How many content blocks were extracted." }, "used_fallback": { "type": "boolean", "description": "True when nothing was recognized and the raw HTML was kept in one block." } } } } } }, "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" }, "locale": { "type": "string", "description": "Render this language (for example fr or pt-BR). The original is used when the design has no translation for it." }, "asset_domain": { "type": "object", "description": "Serve uploaded files from your own domain: every address that starts with `from` (an S3 address, say) is swapped for `to` in the output. `to` must be https. A request with an invalid asset_domain is refused.", "required": [ "from", "to" ], "properties": { "from": { "description": "The storage address or addresses to replace, for example https://my-bucket.s3.eu-north-1.amazonaws.com.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "to": { "type": "string", "description": "Your address, for example https://assets.yourbrand.com." } } }, "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." }, "asset_domain": { "type": "object", "description": "Serve uploaded files from your own domain: every address that starts with `from` (an S3 address, say) is swapped for `to` in the output. `to` must be https. A request with an invalid asset_domain is refused.", "required": [ "from", "to" ], "properties": { "from": { "description": "The storage address or addresses to replace, for example https://my-bucket.s3.eu-north-1.amazonaws.com.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "to": { "type": "string", "description": "Your address, for example https://assets.yourbrand.com." } } }, "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." } } } } } }