{
  "openapi": "3.0.3",
  "info": {
    "title": "EmailUX API",
    "version": "1.0.0"
  },
  "paths": {
    "/v1/render": {
      "post": {
        "summary": "Render email HTML by template and sendgrid-domain",
        "parameters": [
          { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" } },
          { "name": "x-sendgrid-domain", "in": "header", "required": true, "schema": { "type": "string" } }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["experience_id", "data"],
                "properties": {
                  "experience_id": { "type": "string", "description": "Email template id" },
                  "version": { "type": "integer", "description": "Optional template version" },
                  "locale": { "type": "string" },
                  "data": { "type": "object", "additionalProperties": true }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Rendered HTML",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": { "type": "boolean" },
                    "html": { "type": "string" },
                    "subject": { "type": "string" }
                  }
                }
              }
            }
          },
          "400": { "description": "Validation error" },
          "401": { "description": "Unauthorized" },
          "404": { "description": "Not found" }
        }
      }
    },
    "/v1/deliver": {
      "post": {
        "summary": "Render and deliver an email via provider",
        "parameters": [
          { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" } },
          { "name": "x-sendgrid-domain", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. If omitted, include `tenant` in the JSON body, or the API will fall back to the API key's default sendgrid-domain when using sendgrid-domain keys." },
          { "name": "x-provider", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Force a delivery provider (e.g., 'gmail')." }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["experience_id", "channel_data", "data"],
                "properties": {
                  "experience_id": { "type": "string", "description": "Email template id" },
                  "tenant": { "type": "string", "description": "Optional domain name (same as x-sendgrid-domain). Required when using provider API keys without x-sendgrid-domain." },
                  "version": { "type": "integer", "description": "Optional template version" },
                  "locale": { "type": "string" },
                  "language": { "type": "string" },
                  "channel_data": {
                    "type": "object",
                    "required": ["to_email", "from_email"],
                    "properties": {
                      "to_email": { "type": "string", "format": "email" },
                      "to_email_name": { "type": "string" },
                      "from_email": { "type": "string", "format": "email" },
                      "from_email_name": { "type": "string" }
                    }
                  },
                  "data": { "type": "object", "additionalProperties": true }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Mail queued",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": { "type": "boolean" },
                    "message": { "type": "string" }
                  }
                }
              }
            }
          },
          "400": { "description": "Validation error" },
          "401": { "description": "Unauthorized" },
          "404": { "description": "Not found" },
          "502": { "description": "Provider error" }
        }
      }
    },
    "/health": {
      "get": { "summary": "Health", "responses": { "200": { "description": "OK" } } }
    }
  }
}