@mailkite/mcp 0.2.0 → 0.3.0

package/README.md

@@ -10,6 +10,19 @@ from the shared SDK contract in [`../spec`](../spec); transport, auth, and error
 handling come from the [MailKite Node SDK](../node). Nothing about the API is
 duplicated here — update the spec and the MCP follows.
 
+> ### Hosted vs local — which should I use?
+>
+> Most users should connect to the **hosted remote MCP** instead of running this
+> package: `https://mcp.mailkite.dev/mcp` (Streamable HTTP, one-click **OAuth** — no
+> key to copy, no local process). In Claude Code that's the **plugin**
+> (`/plugin marketplace add mailkite/claude-code` → `/plugin install mailkite@mailkite`)
+> or `claude mcp add --transport http mailkite https://mcp.mailkite.dev/mcp`. See
+> <https://mailkite.dev/docs/ai-agents>.
+>
+> Run **this local server** when you want a **static key** (no browser OAuth), **offline /
+> CI** use, a stdio-only client, a custom `MAILKITE_BASE_URL`, or `verifyWebhook` to run
+> fully locally. Both expose the exact same tools (same `../spec`).
+
 ## Install / configure
 
 Point your MCP client at the server and give it your MailKite credential. The
@@ -40,6 +53,8 @@ One tool per MailKite API operation (generated from [`../spec/api.json`](../spec
 | Tool | Operation |
 | --- | --- |
 | `mailkite_send` | Send a message over a verified domain |
+| `mailkite_agent` | Send a message to an inbox agent and get its reply |
+| `mailkite_route` | Route a message to a registered route and run its action |
 | `mailkite_list_domains` | List your domains |
 | `mailkite_create_domain` | Add a domain (returns DNS records) |
 | `mailkite_get_domain` | Get one domain with DNS + webhook |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mailkite/mcp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Model Context Protocol server for MailKite — exposes the MailKite API to LLM agents as tools. A thin layer over the MailKite Node SDK and the shared sdks/spec contract.",
   "type": "module",
   "bin": {
@@ -34,13 +34,13 @@
   "homepage": "https://mailkite.dev/docs/libraries",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/fijiwebdesign/mailkite.git",
+    "url": "git+https://github.com/mailkite/mailkite.git",
     "directory": "sdks/mcp"
   },
   "license": "MIT",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "ajv": "^8.17.1",
-    "mailkite": "^0.2.0"
+    "mailkite": "^0.3.0"
   }
 }

package/spec/api.json

@@ -1,6 +1,6 @@
 {
   "name": "mailkite",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Canonical interface contract for every MailKite SDK. One low-level request() plus one function per endpoint. All languages expose the same shape; only naming adapts to each language's convention (e.g. Go exports PascalCase).",
   "baseUrl": "https://api.mailkite.dev",
   "auth": {
@@ -11,11 +11,39 @@
   "methods": [
     {
       "name": "send",
-      "summary": "Send a message over a verified domain.",
+      "summary": "Send a message over a verified domain. Pass `templateId` (+ optional `templateData`) to send from a saved or base template.",
       "http": { "method": "POST", "path": "/v1/send" },
       "args": [{ "name": "message", "in": "body", "schema": "send-request" }],
       "returns": "send-response"
     },
+    {
+      "name": "listTemplates",
+      "summary": "List your saved email templates (light metadata only — no body). Use getTemplate for the full template.",
+      "http": { "method": "GET", "path": "/api/templates" },
+      "args": [],
+      "returns": "any"
+    },
+    {
+      "name": "listBaseTemplates",
+      "summary": "List the premade base templates (light metadata). Clone one with createTemplate({ baseId }) or send from it directly via send({ templateId }).",
+      "http": { "method": "GET", "path": "/api/templates/base" },
+      "args": [],
+      "returns": "any"
+    },
+    {
+      "name": "getTemplate",
+      "summary": "Get one template (full: subject, html, text, theme). Works for your templates (tpl_…) and base templates (base_…).",
+      "http": { "method": "GET", "path": "/api/templates/{id}" },
+      "args": [{ "name": "id", "in": "path" }],
+      "returns": "any"
+    },
+    {
+      "name": "createTemplate",
+      "summary": "Create a template. Pass `baseId` to clone a base template into your own, or provide name/subject/html/text/theme directly.",
+      "http": { "method": "POST", "path": "/api/templates" },
+      "args": [{ "name": "body", "in": "body", "schema": "create-template-request" }],
+      "returns": "any"
+    },
     {
       "name": "listDomains",
       "summary": "List your domains, each with its webhook URL.",
@@ -104,6 +132,20 @@
       "args": [{ "name": "body", "in": "body", "schema": "create-route-request" }],
       "returns": "any"
     },
+    {
+      "name": "agent",
+      "summary": "Send a message to one of your inbox agents and get its reply. Defaults to the account's default agent; pass `routeId` or `address` to target a specific agent, or `model` to override the model. This is separate from inbound routing — it does not match or override routes.",
+      "http": { "method": "POST", "path": "/v1/agent" },
+      "args": [{ "name": "message", "in": "body", "schema": "agent-request" }],
+      "returns": "agent-response"
+    },
+    {
+      "name": "route",
+      "summary": "Route a message to one of your registered routes (by `routeId` or `address`), running that route's action — agent, webhook, or forward. The route must already exist on your account; arbitrary destinations are not allowed.",
+      "http": { "method": "POST", "path": "/v1/route" },
+      "args": [{ "name": "message", "in": "body", "schema": "route-message-request" }],
+      "returns": "route-response"
+    },
     {
       "name": "listMessages",
       "summary": "List stored messages.",

package/spec/cases.json

@@ -218,6 +218,58 @@
       "response": { "status": 200, "body": { "id": "rte_1" } },
       "result": { "id": "rte_1" }
     },
+    {
+      "name": "agent_default",
+      "method": "agent",
+      "args": { "text": "What's my current balance?" },
+      "request": {
+        "method": "POST",
+        "path": "/v1/agent",
+        "bodySchema": "agent-request",
+        "body": { "text": "What's my current balance?" }
+      },
+      "response": { "status": 200, "body": { "ok": true, "text": "Your balance is $0.00.", "messageId": "msg_agent" } },
+      "result": { "ok": true, "text": "Your balance is $0.00.", "messageId": "msg_agent" }
+    },
+    {
+      "name": "agent_by_route",
+      "method": "agent",
+      "args": { "text": "ping", "routeId": "rte_1", "model": "claude-sonnet-4-6" },
+      "request": {
+        "method": "POST",
+        "path": "/v1/agent",
+        "bodySchema": "agent-request",
+        "body": { "text": "ping", "routeId": "rte_1", "model": "claude-sonnet-4-6" }
+      },
+      "response": { "status": 200, "body": { "ok": true, "text": "pong", "messageId": "msg_agent2" } },
+      "result": { "ok": true, "text": "pong", "messageId": "msg_agent2" }
+    },
+    {
+      "name": "route_by_id",
+      "method": "route",
+      "args": { "routeId": "rte_1", "from": "ops@example.com", "subject": "Process this", "text": "Please handle." },
+      "request": {
+        "method": "POST",
+        "path": "/v1/route",
+        "bodySchema": "route-message-request",
+        "body": { "routeId": "rte_1", "from": "ops@example.com", "subject": "Process this", "text": "Please handle." }
+      },
+      "response": { "status": 202, "body": { "id": "msg_r1", "routed": true, "action": "webhook" } },
+      "result": { "id": "msg_r1", "routed": true, "action": "webhook" }
+    },
+    {
+      "name": "route_by_address",
+      "method": "route",
+      "args": { "address": "support@app.mailkite.dev", "from": "ops@example.com", "text": "hey there" },
+      "request": {
+        "method": "POST",
+        "path": "/v1/route",
+        "bodySchema": "route-message-request",
+        "body": { "address": "support@app.mailkite.dev", "from": "ops@example.com", "text": "hey there" }
+      },
+      "response": { "status": 202, "body": { "id": "msg_r2", "routed": true, "action": "agent" } },
+      "result": { "id": "msg_r2", "routed": true, "action": "agent" }
+    },
     {
       "name": "list_messages",
       "method": "listMessages",
@@ -242,6 +294,56 @@
       "response": { "status": 200, "body": { "ok": true } },
       "result": { "ok": true }
     },
+    {
+      "name": "send_with_template",
+      "method": "send",
+      "args": { "from": "hello@app.mailkite.dev", "to": "ada@example.com", "templateId": "base_welcome-dark", "templateData": { "name": "Ada" } },
+      "request": {
+        "method": "POST",
+        "path": "/v1/send",
+        "bodySchema": "send-request",
+        "body": { "from": "hello@app.mailkite.dev", "to": "ada@example.com", "templateId": "base_welcome-dark", "templateData": { "name": "Ada" } }
+      },
+      "response": { "status": 202, "body": { "id": "msg_tpl", "status": "queued" } },
+      "result": { "id": "msg_tpl", "status": "queued" }
+    },
+    {
+      "name": "list_templates",
+      "method": "listTemplates",
+      "args": {},
+      "request": { "method": "GET", "path": "/api/templates" },
+      "response": { "status": 200, "body": [{ "id": "tpl_1", "name": "Welcome", "category": "", "subject": "Hi", "is_base": 0 }] },
+      "result": [{ "id": "tpl_1", "name": "Welcome", "category": "", "subject": "Hi", "is_base": 0 }]
+    },
+    {
+      "name": "list_base_templates",
+      "method": "listBaseTemplates",
+      "args": {},
+      "request": { "method": "GET", "path": "/api/templates/base" },
+      "response": { "status": 200, "body": [{ "id": "base_welcome-dark", "name": "Welcome — Dark", "category": "Welcome", "subject": "Welcome to MailKite", "is_base": 1 }] },
+      "result": [{ "id": "base_welcome-dark", "name": "Welcome — Dark", "category": "Welcome", "subject": "Welcome to MailKite", "is_base": 1 }]
+    },
+    {
+      "name": "get_template",
+      "method": "getTemplate",
+      "args": { "id": "tpl_1" },
+      "request": { "method": "GET", "path": "/api/templates/tpl_1" },
+      "response": { "status": 200, "body": { "id": "tpl_1", "name": "Welcome", "html": "<p>hi</p>" } },
+      "result": { "id": "tpl_1", "name": "Welcome", "html": "<p>hi</p>" }
+    },
+    {
+      "name": "create_template",
+      "method": "createTemplate",
+      "args": { "baseId": "base_welcome-dark", "name": "My Welcome" },
+      "request": {
+        "method": "POST",
+        "path": "/api/templates",
+        "bodySchema": "create-template-request",
+        "body": { "baseId": "base_welcome-dark", "name": "My Welcome" }
+      },
+      "response": { "status": 201, "body": { "id": "tpl_2", "name": "My Welcome" } },
+      "result": { "id": "tpl_2", "name": "My Welcome" }
+    },
     {
       "name": "get_message_not_found",
       "method": "getMessage",

package/spec/check-docs.mjs

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+// ---------------------------------------------------------------------------
+// check-docs — validate that the website docs match our request SCHEMAS.
+//
+// "Our schema" = sdks/spec/schemas/*.json (the JSON Schemas every SDK + the MCP
+// server validate against). The website docs (website/src/pages/docs/*.astro)
+// are hand-written, so their field tables and request examples can drift from
+// the schema. This script is the agent-runnable guard: run it, read the report.
+//
+//   node sdks/spec/check-docs.mjs        # human/agent: prints ✓/✗, exits 1 on drift
+//   import { runChecks } from './check-docs.mjs'   # CI: see api/test/docs-schema.test.ts
+//
+// It checks, per schema-backed operation:
+//   1. the doc "Request fields" table lists exactly the schema's properties,
+//      with the same required set;
+//   2. every JSON request example in the docs uses only schema fields and
+//      includes the required ones;
+//   3. the SDK code samples include the required fields and use no wrong alias.
+// ---------------------------------------------------------------------------
+
+import { readFileSync, readdirSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SPEC_DIR = dirname(fileURLToPath(import.meta.url)); // sdks/spec
+const ROOT = resolve(SPEC_DIR, '../..'); // repo root
+const read = (p) => readFileSync(p, 'utf8');
+const readJson = (p) => JSON.parse(read(p));
+
+const DOCS_DIR = resolve(ROOT, 'website/src/pages/docs');
+const docText = Object.fromEntries(
+  readdirSync(DOCS_DIR)
+    .filter((f) => f.endsWith('.astro'))
+    .map((f) => [f, read(resolve(DOCS_DIR, f))]),
+);
+const samplesTs = read(resolve(ROOT, 'website/src/lib/samples.ts'));
+
+const schema = (name) => readJson(resolve(SPEC_DIR, 'schemas', `${name}.json`));
+const eqSet = (a, b) => a.size === b.size && [...a].every((x) => b.has(x));
+
+// ---- helpers --------------------------------------------------------------
+
+// All quoted keys (`"key":`) inside a JSON-ish block — includes nested keys,
+// which is what we want (attachment sub-fields are valid send fields).
+const jsonKeys = (block) => new Set([...block.matchAll(/"([a-zA-Z]+)"\s*:/g)].map((m) => m[1]));
+
+// Every backtick template literal in a file (docs put JSON examples in these).
+const templateLiterals = (src) => [...src.matchAll(/`([^`]*)`/g)].map((m) => m[1]);
+
+// ---- the checks -----------------------------------------------------------
+
+// Each entry ties a doc-visible operation to its schema + how to spot its
+// request examples among the docs' JSON blocks.
+const OPS = [
+  {
+    label: 'send',
+    schema: 'send-request',
+    // The "Request fields" table lives in sending.astro under this heading.
+    fieldTable: { file: 'sending.astro', heading: 'Request fields' },
+    // A send body has from+subject. Exclude inbound webhook payloads (which also
+    // carry from/subject but add type/auth/threadId) and responses (status).
+    isRequestExample: (k) =>
+      k.has('from') &&
+      k.has('subject') &&
+      !k.has('status') &&
+      !k.has('type') &&
+      !k.has('auth') &&
+      !k.has('threadId'),
+    nestedSchemaKeys: ['filename', 'url', 'content', 'contentType'], // attachments[].*
+    sample: { source: samplesTs, slice: ['sendSamples', 'initSamples'] },
+    wrongAliases: ['reply_to', 'in_reply_to', 'html_body', 'text_body', 'from_addr', 'to_addr'],
+  },
+  {
+    label: 'createRoute',
+    schema: 'create-route-request',
+    isRequestExample: (k) => k.has('match') && k.has('action'),
+  },
+  {
+    label: 'createDomain',
+    schema: 'create-domain-request',
+    isRequestExample: (k) => k.has('domain') && k.size <= 2,
+  },
+];
+
+function runChecks() {
+  const results = [];
+  const ok = (name) => results.push({ name, ok: true });
+  const fail = (name, detail) => results.push({ name, ok: false, detail });
+
+  for (const op of OPS) {
+    const s = schema(op.schema);
+    const props = new Set(Object.keys(s.properties));
+    const required = new Set(s.required ?? []);
+    const allowed = new Set([...props, ...(op.nestedSchemaKeys ?? [])]);
+
+    // ── Check 1: the "Request fields" table mirrors the schema exactly ──────
+    if (op.fieldTable) {
+      const src = docText[op.fieldTable.file] ?? '';
+      const table = src.match(
+        new RegExp(`<h2>${op.fieldTable.heading}</h2>([\\s\\S]*?)</table>`),
+      );
+      if (!table) {
+        fail(`${op.label}: fields table present`, `no "${op.fieldTable.heading}" table in ${op.fieldTable.file}`);
+      } else {
+        const docFields = new Set();
+        const docRequired = new Set();
+        for (const row of table[1].matchAll(/<tr>([\s\S]*?)<\/tr>/g)) {
+          const firstCell = row[1].match(/<td>([\s\S]*?)<\/td>/);
+          if (!firstCell) continue; // header row (uses <th>)
+          const names = [...firstCell[1].matchAll(/<code>([a-zA-Z]+)<\/code>/g)].map((m) => m[1]);
+          const isRequired = /Required\./.test(row[1]);
+          for (const n of names) {
+            docFields.add(n);
+            if (isRequired) docRequired.add(n);
+          }
+        }
+        if (eqSet(docFields, props)) ok(`${op.label}: fields table = schema properties`);
+        else
+          fail(
+            `${op.label}: fields table = schema properties`,
+            `table=${[...docFields].sort()} schema=${[...props].sort()}`,
+          );
+        if (eqSet(docRequired, required)) ok(`${op.label}: fields table required = schema required`);
+        else
+          fail(
+            `${op.label}: fields table required = schema required`,
+            `table=${[...docRequired].sort()} schema=${[...required].sort()}`,
+          );
+      }
+    }
+
+    // ── Check 2: every JSON request example uses only schema fields ─────────
+    let examplesSeen = 0;
+    for (const [file, src] of Object.entries(docText)) {
+      for (const block of templateLiterals(src)) {
+        const keys = jsonKeys(block);
+        if (keys.size === 0 || !op.isRequestExample(keys)) continue;
+        examplesSeen++;
+        const unknown = [...keys].filter((k) => !allowed.has(k));
+        if (unknown.length)
+          fail(`${op.label}: JSON example fields ⊆ schema (${file})`, `unknown: ${unknown}`);
+        const missing = [...required].filter((r) => !keys.has(r));
+        if (missing.length)
+          fail(`${op.label}: JSON example has required fields (${file})`, `missing: ${missing}`);
+      }
+    }
+    if (examplesSeen) ok(`${op.label}: ${examplesSeen} JSON request example(s) validated`);
+
+    // ── Check 3: SDK code samples include required fields, no wrong aliases ──
+    if (op.sample) {
+      // Pull each named sample object's body out of samples.ts.
+      for (const name of op.sample.slice) {
+        const m = op.sample.source.match(new RegExp(`export const ${name}[\\s\\S]*?\\n};`));
+        if (!m) continue;
+        const body = m[0].toLowerCase();
+        for (const alias of op.wrongAliases ?? []) {
+          if (body.includes(alias))
+            fail(`${op.label}: sample uses wrong alias (${name})`, `found "${alias}" — use the schema field`);
+        }
+      }
+    }
+  }
+  return results;
+}
+
+// ---- CLI ------------------------------------------------------------------
+
+const isMain = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  const results = runChecks();
+  const failures = results.filter((r) => !r.ok);
+  for (const r of results) {
+    console.log(`${r.ok ? '✓' : '✗'} ${r.name}${r.detail ? `\n    ${r.detail}` : ''}`);
+  }
+  console.log(`\n${results.length - failures.length}/${results.length} checks passed.`);
+  if (failures.length) {
+    console.error(`\n${failures.length} doc/schema mismatch(es) — fix the .astro doc or the schema.`);
+    process.exit(1);
+  }
+}
+
+export { runChecks };

package/spec/schemas/agent-request.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "agent-request",
+  "title": "Send-to-agent request body",
+  "type": "object",
+  "required": ["text"],
+  "additionalProperties": false,
+  "properties": {
+    "text": { "type": "string", "description": "The message for the agent — it reads this as the incoming email body and decides what to do." },
+    "subject": { "type": "string", "description": "Optional subject line the agent sees on the message." },
+    "from": { "type": "string", "description": "Optional sender address the agent sees as the originator. Defaults to the account's API caller address." },
+    "html": { "type": "string", "description": "Optional HTML body. `text` is still required — the agent reasons over the plain-text content." },
+    "routeId": { "type": "string", "description": "Target a specific agent by its route id (rte_…). Omit to use the account's default agent (its most recently created agent route)." },
+    "address": { "type": "string", "description": "Target the agent whose route matches this address. Alternative to routeId." },
+    "model": { "type": "string", "description": "Override the model the agent runs on for this call (e.g. claude-sonnet-4-6)." }
+  }
+}

package/spec/schemas/agent-response.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "agent-response",
+  "title": "Send-to-agent response body",
+  "type": "object",
+  "required": ["ok"],
+  "properties": {
+    "ok": { "type": "boolean", "description": "Whether the agent ran to completion." },
+    "text": { "type": "string", "description": "The agent's reply — its final message after running." },
+    "messageId": { "type": "string", "description": "Id of the stored message the agent processed (msg_…)." },
+    "error": { "type": "string", "description": "Error detail when `ok` is false." }
+  }
+}

package/spec/schemas/create-route-request.json

@@ -3,11 +3,16 @@
   "$id": "create-route-request",
   "title": "Create route request body",
   "type": "object",
-  "required": ["match", "action", "destination"],
+  "required": ["match"],
   "additionalProperties": false,
   "properties": {
-    "match": { "type": "string" },
-    "action": { "type": "string" },
-    "destination": { "type": "string" }
+    "match": { "type": "string", "description": "Address pattern: exact, *@domain, addr+*@domain, or /regex/." },
+    "action": {
+      "type": "string",
+      "enum": ["webhook", "forward", "store", "drop", "agent"],
+      "description": "What to do with matching mail. Defaults to webhook."
+    },
+    "destination": { "type": "string", "description": "Required for action webhook (URL) or forward (address)." },
+    "agentPrompt": { "type": "string", "description": "Required for action agent — instructions for the inbox agent." }
   }
 }

package/spec/schemas/create-template-request.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "create-template-request",
+  "title": "Create template request body",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "baseId": { "type": "string", "description": "Clone this base template (base_…) into your own. When set, name is optional (defaults to the base's name)." },
+    "name": { "type": "string", "description": "Template name. Required unless baseId is given." },
+    "subject": { "type": "string", "description": "Default subject line for sends." },
+    "html": { "type": "string", "description": "Rendered, send-ready HTML." },
+    "text": { "type": "string", "description": "Plaintext fallback." },
+    "json": { "type": "string", "description": "Editor (TipTap) JSON source, for re-editing in the dashboard." },
+    "theme": { "type": "string", "description": "Brand tokens JSON (bg, surface, primary, text, logo, …)." }
+  }
+}

package/spec/schemas/route-message-request.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "route-message-request",
+  "title": "Route-message request body",
+  "type": "object",
+  "required": ["from"],
+  "additionalProperties": false,
+  "anyOf": [{ "required": ["routeId"] }, { "required": ["address"] }],
+  "properties": {
+    "routeId": { "type": "string", "description": "Target route by id (rte_…). One of routeId or address is required. The route must already be registered on this account." },
+    "address": { "type": "string", "description": "Target route by the address it matches. One of routeId or address is required." },
+    "from": { "type": "string", "description": "Sender address recorded on the message." },
+    "subject": { "type": "string", "description": "Optional subject line." },
+    "text": { "type": "string", "description": "Plain-text body." },
+    "html": { "type": "string", "description": "HTML body." }
+  }
+}

package/spec/schemas/route-response.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "route-response",
+  "title": "Route-message response body",
+  "type": "object",
+  "required": ["id", "routed", "action"],
+  "properties": {
+    "id": { "type": "string", "description": "Stored message id (msg_…)." },
+    "routed": { "type": "boolean", "description": "Whether the message was handed to the route's action." },
+    "action": { "type": "string", "description": "The action the matched route performed: webhook, forward, agent, store, or drop." }
+  }
+}

package/spec/schemas/send-request.json

@@ -3,7 +3,7 @@
   "$id": "send-request",
   "title": "Send request body",
   "type": "object",
-  "required": ["from", "to", "subject"],
+  "required": ["from", "to"],
   "additionalProperties": false,
   "properties": {
     "from": { "type": "string", "description": "An address on a verified domain." },
@@ -14,9 +14,18 @@
         { "type": "array", "items": { "type": "string" }, "minItems": 1 }
       ]
     },
-    "subject": { "type": "string" },
+    "subject": { "type": "string", "description": "Required unless supplied by a template." },
     "html": { "type": "string" },
     "text": { "type": "string" },
+    "templateId": {
+      "type": "string",
+      "description": "Send using a saved template — a user template (tpl_…) or a base template (base_…). Its subject/html/text seed the message; explicit subject/html/text here override them."
+    },
+    "templateData": {
+      "type": "object",
+      "description": "Values substituted into the template's {{merge_tags}} (e.g. {\"name\":\"Ann\"} fills {{name}}). HTML values are auto-escaped.",
+      "additionalProperties": { "type": ["string", "number", "boolean", "null"] }
+    },
     "cc": { "oneOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }] },
     "bcc": { "oneOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }] },
     "replyTo": { "type": "string" },