{
  "openapi": "3.1.0",
  "info": { "title": "AllStackd Transactional Email API", "version": "0.4.0", "description": "Durable Control-mode sending through a project-scoped customer Amazon SES connection." },
  "servers": [{ "url": "https://allstackd.com" }],
  "security": [{ "bearerAuth": [] }],
  "paths": {
    "/api/v1/emails": {
      "post": {
        "summary": "Queue a transactional email",
        "parameters": [{ "in": "header", "name": "Idempotency-Key", "schema": { "type": "string", "maxLength": 255 }, "description": "Stable key for safely retrying the same logical send." }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailRequest" } } } },
        "responses": {
          "202": { "description": "Durably queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueuedMessage" } } } },
          "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/v1/emails/{messageId}": {
      "get": {
        "summary": "Get normalized message status",
        "parameters": [{ "in": "path", "name": "messageId", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": { "200": { "description": "Message, recipient, and event status without raw content" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/api/v1/templates": {
      "get": {
        "summary": "List templates available to this API key",
        "responses": { "200": { "description": "Template list" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" } }
      },
      "post": {
        "summary": "Create a template from HTML or a starter",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateCreate" } } } },
        "responses": { "201": { "description": "Created" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/api/v1/templates/{idOrAlias}": {
      "get": {
        "summary": "Get a template by id or alias",
        "parameters": [{ "in": "path", "name": "idOrAlias", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Template" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }
      },
      "patch": {
        "summary": "Update a template",
        "parameters": [{ "in": "path", "name": "idOrAlias", "required": true, "schema": { "type": "string" } }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateUpdate" } } } },
        "responses": { "200": { "description": "Updated" }, "400": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" } }
      },
      "delete": {
        "summary": "Archive a template",
        "parameters": [{ "in": "path", "name": "idOrAlias", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Archived" }, "404": { "$ref": "#/components/responses/Error" } }
      },
      "post": {
        "summary": "Publish or preview a template",
        "parameters": [
          { "in": "path", "name": "idOrAlias", "required": true, "schema": { "type": "string" } },
          { "in": "query", "name": "action", "required": true, "schema": { "type": "string", "enum": ["publish", "preview"] } }
        ],
        "responses": { "200": { "description": "Action result" }, "400": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }
      }
    }
  },
  "components": {
    "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "AllStackd as_ API key" } },
    "schemas": {
      "EmailRequest": {
        "type": "object",
        "required": ["from", "to"],
        "properties": {
          "from": { "type": "string", "format": "email" },
          "to": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "format": "email" } },
          "subject": { "type": "string", "maxLength": 998 },
          "html": { "type": "string" },
          "text": { "type": "string" },
          "templateId": { "type": "string", "format": "uuid" },
          "templateAlias": { "type": "string" },
          "template": {
            "type": "object",
            "properties": {
              "id": { "type": "string", "format": "uuid" },
              "alias": { "type": "string" },
              "variables": { "type": "object", "additionalProperties": { "type": "string" } }
            }
          },
          "variables": { "type": "object", "additionalProperties": { "type": "string" } },
          "metadata": { "type": "object", "additionalProperties": true },
          "idempotencyKey": { "type": "string", "maxLength": 255, "deprecated": true, "description": "Prefer the Idempotency-Key header." }
        },
        "anyOf": [
          { "required": ["templateId"] },
          { "required": ["templateAlias"] },
          { "required": ["template"] },
          { "required": ["subject"], "anyOf": [{ "required": ["html"] }, { "required": ["text"] }] }
        ]
      },
      "TemplateCreate": {
        "type": "object",
        "properties": {
          "starterId": { "type": "string", "description": "welcome | verify-email | password-reset | magic-link | receipt" },
          "name": { "type": "string" },
          "alias": { "type": "string" },
          "subject": { "type": "string" },
          "previewText": { "type": "string" },
          "html": { "type": "string" },
          "text": { "type": "string" },
          "publish": { "type": "boolean" },
          "variablesSchema": { "type": "object", "additionalProperties": { "type": "string" } }
        }
      },
      "TemplateUpdate": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "alias": { "type": "string" },
          "subject": { "type": "string" },
          "previewText": { "type": "string", "nullable": true },
          "html": { "type": "string" },
          "text": { "type": "string", "nullable": true },
          "publish": { "type": "boolean" },
          "variablesSchema": { "type": "object", "additionalProperties": { "type": "string" } }
        }
      },
      "QueuedMessage": { "type": "object", "required": ["id", "status", "mode", "contentExpiresAt"], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "const": "queued" }, "queued": { "type": "boolean" }, "mode": { "const": "control" }, "contentExpiresAt": { "type": "string", "format": "date-time" } } },
      "ApiError": { "type": "object", "required": ["error"], "properties": { "error": { "type": "object", "required": ["code", "message"], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }
    },
    "responses": { "Error": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }
  }
}