{ "openapi": "3.1.0", "info": { "title": "MakiSend API", "version": "0.1.0", "summary": "Serverless transactional email API on Cloudflare Workers.", "description": "MakiSend accepts transactional emails over HTTP, stores their content encrypted in D1, and delivers them asynchronously through Cloudflare Queues, Workflows, and SMTP.\n\n**Authentication.** `POST /send-email` uses a per-tenant API key from the dashboard, sent as `x-api-key` or `Authorization: Bearer `. Dashboard endpoints use the Better Auth session cookie created by `POST /api/auth/sign-in/email`; open the dashboard and sign in before trying those routes here.\n\n**Delivery is asynchronous.** `POST /send-email` returns `202 Accepted` once the email is persisted and queued. Delivery status is available through `GET /email-logs` and the dashboard endpoints.\n\n**This page documents the email API of a self-hosted MakiSend instance.** Replace `your-instance.workers.dev` with your Worker's address. Each instance also serves its full reference, dashboard routes included, at `/docs`.", "license": { "name": "MIT" } }, "servers": [ { "url": "https://{instance}", "description": "Your MakiSend instance", "variables": { "instance": { "default": "your-instance.workers.dev", "description": "Your Worker's host name" } } } ], "tags": [ { "name": "Emails", "description": "Queue transactional emails for delivery." }, { "name": "Email Logs", "description": "Inspect delivery logs and history." }, { "name": "Templates", "description": "Reusable email templates with variables." } ], "paths": { "/send-email": { "post": { "tags": [ "Emails" ], "summary": "Queue a transactional email", "operationId": "sendEmail", "description": "Accepts either inline content (`subject`, `text`, `html`) or a `templateId` plus `variables`. The two shapes are mutually exclusive. HTML is sanitized before delivery. Send the optional `Idempotency-Key` header to make retries safe.", "security": [ { "ApiKey": [] }, { "Bearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key for safe retries. Replaying the same key and body returns the stored response for 24 hours; reusing it with a different body returns 409.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendEmailPayload" } } } }, "responses": { "202": { "description": "Email persisted and queued for asynchronous delivery.", "headers": { "Idempotency-Replayed": { "description": "`true` when this response was replayed from a previous request with the same idempotency key.", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendEmailAccepted" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "The referenced template does not exist for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "description": "Only when the instance sets `SEND_RATE_LIMIT`: this API key reached its send quota. `Retry-After` gives the seconds until the window restarts.", "headers": { "Retry-After": { "description": "Seconds until the quota window restarts.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/email-logs": { "get": { "tags": [ "Email Logs" ], "summary": "List email logs", "operationId": "listEmailLogs", "description": "Newest first, cursor-paginated. The recipient filter is applied to the decrypted current page, so a page can contain fewer rows than `limit` when filtering by `to`.", "security": [ { "SessionCookie": [] } ], "parameters": [ { "name": "smtpConfigId", "in": "query", "description": "The emails sent with this configuration's keys, plus its test sends.", "schema": { "type": "string", "maxLength": 128 } }, { "name": "apiKeyId", "in": "query", "description": "Only the emails sent with this API key.", "schema": { "type": "string", "maxLength": 128 } }, { "name": "to", "in": "query", "description": "Case-insensitive substring match on the decrypted recipient.", "schema": { "type": "string", "maxLength": 320 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "received", "processing", "cleaned", "sent", "failed" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "description": "Opaque `nextCursor` from the previous page.", "schema": { "type": "string", "maxLength": 512 } } ], "responses": { "200": { "description": "Page of email logs with their history.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailLogPage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/email-logs/{id}": { "get": { "tags": [ "Email Logs" ], "summary": "Get an email log", "operationId": "getEmailLog", "security": [ { "SessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource identifier.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Email log with its full history.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailLogEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/templates": { "get": { "tags": [ "Templates" ], "summary": "List templates", "operationId": "listTemplates", "security": [ { "SessionCookie": [] } ], "responses": { "200": { "description": "Templates owned by the session user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "tags": [ "Templates" ], "summary": "Create a template", "operationId": "createTemplate", "description": "Use `{{variable}}` placeholders in the subject, HTML, or text. Variables are supplied at send time.", "security": [ { "SessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTemplate" } } } }, "responses": { "201": { "description": "Template created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/templates/{id}": { "get": { "tags": [ "Templates" ], "summary": "Get a template", "operationId": "getTemplate", "security": [ { "SessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource identifier.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "tags": [ "Templates" ], "summary": "Update a template", "operationId": "updateTemplate", "security": [ { "SessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource identifier.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTemplate" } } } }, "responses": { "200": { "description": "Template updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "tags": [ "Templates" ], "summary": "Delete a template", "operationId": "deleteTemplate", "security": [ { "SessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource identifier.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Template deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/templates/{id}/preview": { "post": { "tags": [ "Templates" ], "summary": "Preview a template", "operationId": "previewTemplate", "description": "Renders the saved subject, HTML, and text with the supplied variables. Missing variables, line breaks, and length limits are reported exactly as they would be by `POST /send-email`.", "security": [ { "SessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource identifier.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewTemplate" } } } }, "responses": { "200": { "description": "Rendered template preview.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplatePreviewEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } } }, "components": { "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Per-tenant API key created in the dashboard under API Keys." }, "Bearer": { "type": "http", "scheme": "bearer", "description": "The same API key sent as `Authorization: Bearer `." }, "SessionCookie": { "type": "apiKey", "in": "cookie", "name": "better-auth.session_token", "description": "Better Auth session cookie created by `POST /api/auth/sign-in/email`. Sign in through the dashboard, then use the same browser origin for these routes." } }, "schemas": { "SendEmailPayload": { "anyOf": [ { "type": "object", "properties": { "to": { "type": "string", "maxLength": 320, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "subject": { "type": "string", "minLength": 3, "maxLength": 500 }, "text": { "type": "string", "minLength": 10, "maxLength": 20000 }, "html": { "type": "string", "minLength": 1, "maxLength": 100000 }, "attachments": { "maxItems": 5, "type": "array", "items": { "type": "object", "properties": { "filename": { "type": "string", "minLength": 1, "maxLength": 200 }, "content": { "type": "string", "minLength": 1 }, "content_type": { "type": "string", "maxLength": 255 } }, "required": [ "filename", "content" ], "additionalProperties": false } } }, "required": [ "to", "subject", "text", "html" ], "additionalProperties": false }, { "type": "object", "properties": { "to": { "type": "string", "maxLength": 320, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "templateId": { "type": "string", "minLength": 1, "maxLength": 128 }, "variables": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 64 }, "additionalProperties": { "type": [ "string", "number", "boolean" ] } }, "attachments": { "maxItems": 5, "type": "array", "items": { "type": "object", "properties": { "filename": { "type": "string", "minLength": 1, "maxLength": 200 }, "content": { "type": "string", "minLength": 1 }, "content_type": { "type": "string", "maxLength": 255 } }, "required": [ "filename", "content" ], "additionalProperties": false } } }, "required": [ "to", "templateId" ], "additionalProperties": false } ], "description": "Inline email content, or a template reference. The shapes are mutually exclusive." }, "CreateTemplate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "subject": { "type": "string", "minLength": 1, "maxLength": 500 }, "format": { "default": "legacy", "type": "string", "enum": [ "legacy", "react-email", "react-email-code" ] }, "editorJson": { "type": "string", "minLength": 2, "maxLength": 250000 }, "source": { "type": "string", "minLength": 1, "maxLength": 100000 }, "html": { "type": "string", "minLength": 1, "maxLength": 100000 }, "text": { "type": "string", "minLength": 1, "maxLength": 20000 } }, "required": [ "name", "subject", "html", "text" ], "additionalProperties": false, "description": "New reusable email template." }, "UpdateTemplate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "subject": { "type": "string", "minLength": 1, "maxLength": 500 }, "format": { "type": "string", "enum": [ "legacy", "react-email", "react-email-code" ] }, "editorJson": { "anyOf": [ { "type": "string", "minLength": 2, "maxLength": 250000 }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100000 }, { "type": "null" } ] }, "html": { "type": "string", "minLength": 1, "maxLength": 100000 }, "text": { "type": "string", "minLength": 1, "maxLength": 20000 } }, "additionalProperties": false, "description": "Partial template update." }, "PreviewTemplate": { "type": "object", "properties": { "variables": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 64 }, "additionalProperties": { "type": [ "string", "number", "boolean" ] } } }, "additionalProperties": false, "description": "Variable values used to render a saved template preview." }, "SendEmailAccepted": { "type": "object", "required": [ "success", "message", "emailId" ], "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string", "const": "Email queued" }, "emailId": { "type": "string", "description": "Internal email id used by logs and the dashboard." } } }, "EmailHistory": { "type": "object", "required": [ "id", "emailId", "status", "error", "attempts", "createdAt" ], "properties": { "id": { "type": "string" }, "emailId": { "type": "string" }, "status": { "type": "string", "enum": [ "received", "processing", "cleaned", "sent", "failed" ] }, "error": { "type": [ "string", "null" ] }, "attempts": { "type": [ "integer", "null" ] }, "createdAt": { "type": "string", "format": "date-time" } } }, "EmailLog": { "type": "object", "required": [ "internalId", "userId", "apiKeyId", "to", "subject", "smtpId", "sentAt", "emailProcessingTimeMs", "source", "smtpConfigId", "createdAt", "history" ], "properties": { "internalId": { "type": "string" }, "userId": { "type": "string" }, "apiKeyId": { "type": [ "string", "null" ] }, "to": { "type": "string", "format": "email", "description": "Decrypted recipient." }, "subject": { "type": "string" }, "smtpId": { "type": [ "string", "null" ] }, "sentAt": { "type": [ "string", "null" ], "format": "date-time" }, "emailProcessingTimeMs": { "type": [ "integer", "null" ] }, "source": { "type": "string", "enum": [ "api", "test" ], "description": "`test` for the dashboard's manual test send, `api` for POST /send-email." }, "smtpConfigId": { "type": [ "string", "null" ], "description": "The configuration a test went through; null for an API send." }, "createdAt": { "type": "string", "format": "date-time" }, "history": { "type": "array", "items": { "$ref": "#/components/schemas/EmailHistory" } } } }, "EmailLogEnvelope": { "type": "object", "required": [ "log" ], "properties": { "log": { "$ref": "#/components/schemas/EmailLog" } } }, "EmailLogPage": { "type": "object", "required": [ "logs", "nextCursor" ], "properties": { "logs": { "type": "array", "items": { "$ref": "#/components/schemas/EmailLog" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to fetch the next page; null at the end." } } }, "Template": { "type": "object", "required": [ "id", "userId", "name", "subject", "format", "source", "html", "text", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "userId": { "type": "string" }, "name": { "type": "string" }, "subject": { "type": "string" }, "format": { "type": "string", "enum": [ "legacy", "react-email", "react-email-code" ] }, "editorJson": { "type": [ "string", "null" ], "description": "Serialized builder envelope ({ version, theme, content }) for react-email templates. Legacy raw TipTap documents are still accepted." }, "source": { "type": [ "string", "null" ], "description": "Pasted TSX source for react-email-code templates. The Worker never executes it." }, "html": { "type": "string" }, "text": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "TemplatePreview": { "type": "object", "required": [ "subject", "html", "text" ], "properties": { "subject": { "type": "string" }, "html": { "type": "string" }, "text": { "type": "string" } } }, "TemplatePreviewEnvelope": { "type": "object", "required": [ "preview" ], "properties": { "preview": { "$ref": "#/components/schemas/TemplatePreview" } } }, "TemplateEnvelope": { "type": "object", "required": [ "template" ], "properties": { "template": { "$ref": "#/components/schemas/Template" } } }, "TemplateList": { "type": "object", "required": [ "templates" ], "properties": { "templates": { "type": "array", "items": { "$ref": "#/components/schemas/Template" } } } }, "SuccessResponse": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean", "const": true } } }, "Error": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "string" } } }, "ValidationError": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "details": { "type": "object", "properties": { "fieldErrors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "formErrors": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "Unauthorized": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "Credentials are valid but the resource is not accessible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ValidationError": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "Conflict": { "description": "Idempotency key conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ServerError": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }