@mailkite/mcp 0.6.0 → 0.9.0

package/README.md

@@ -1,33 +1,30 @@
-# @mailkite/mcp
-
-[Model Context Protocol](https://modelcontextprotocol.io) server for
-[MailKite](https://mailkite.dev). It exposes the MailKite API to LLM agents
-(Claude Desktop, Claude Code, Cursor, …) as tools — send mail, manage domains,
-webhooks, routes, and inbound messages, all from a chat.
-
-It's a **thin layer**. The tools, their input schemas, and validation all come
-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
-token is the same one the SDKs take: an `mk_live_…` API key (for sending) or a
-management session token.
+<p align="center">
+  <a href="https://mailkite.dev">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://mailkite.dev/brand/logo-email-dark.png">
+      <img src="https://mailkite.dev/brand/logo-email.png" alt="MailKite" height="56">
+    </picture>
+  </a>
+</p>
+
+<h1 align="center">@mailkite/mcp</h1>
+
+<p align="center">
+  <b>Email for every product you ship</b> — receive email as a webhook, send over a verified domain, give an AI agent its own inbox.
+  <br>The official <a href="https://mailkite.dev">MailKite</a> library for AI agents (MCP).
+</p>
+
+<p align="center">
+  <a href="https://mailkite.dev/docs">Docs</a> ·
+  <a href="https://mailkite.dev/docs/libraries#mcp">Library guide</a> ·
+  <a href="https://mailkite.dev">mailkite.dev</a> ·
+  <a href="https://mailkite.dev/docs/ai-agents">AI agents</a>
+</p>
+<p align="center"><a href="https://www.npmjs.com/package/@mailkite/mcp"><img src="https://img.shields.io/npm/v/@mailkite/mcp?color=2563eb&label=npm" alt="npm"></a></p>
+
+> **Read-only mirror.** This repo is a generated, release-time mirror of the MailKite monorepo (the private source of truth) — development doesn't happen here. Install from npm and open issues against the [MailKite docs](https://mailkite.dev/docs).
+
+## Install
 
 ```json
 {
@@ -41,63 +38,63 @@ management session token.
 }
 ```
 
-| Env var | Required | Default | Notes |
-| --- | --- | --- | --- |
-| `MAILKITE_API_KEY` | yes | — | Bearer credential (`mk_live_…` API key or session token) |
-| `MAILKITE_BASE_URL` | no | `https://api.mailkite.dev` | Override for local/staging |
-
 ## Tools
 
-One tool per MailKite API operation (generated from [`../spec/api.json`](../spec/api.json)):
-
-| 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 |
-| `mailkite_delete_domain` | Remove a domain |
-| `mailkite_verify_domain` | Check DNS and update status |
-| `mailkite_set_webhook` | Set/replace the domain catch-all webhook |
-| `mailkite_delete_webhook` | Remove the domain webhook |
-| `mailkite_test_webhook` | Send a signed test event to the webhook |
-| `mailkite_list_routes` | List inbound routing rules |
-| `mailkite_create_route` | Create a route (match, action, destination) |
-| `mailkite_list_messages` | List stored messages |
-| `mailkite_get_message` | Get a message with deliveries + attachments |
-| `mailkite_retry_delivery` | Re-deliver a stored message to its webhook |
-| `mailkite_verify_webhook` | Verify an `x-mailkite-signature` header (local — no API call) |
-
-`mailkite_verify_webhook` is a **local** tool: it runs the SDK's `verifyWebhook`
-in-process (no credential, no network) and returns `{ "valid": true | false }`.
-Every other tool is one MailKite API operation.
-
-Each tool's input is a flat object with the real field names (e.g.
-`mailkite_send` takes `from`, `to`, `subject`, `html`, `text`, …). Required
-fields and types are enforced with [`ajv`](https://ajv.js.org) against the same
-JSON Schemas in [`../spec/schemas`](../spec/schemas) that the SDKs and
-conformance harness use — invalid calls are rejected before any HTTP request.
-
-## How it works
+One tool per MailKite API method, generated from the shared contract — including `mailkite_send`, `mailkite_semantic_search`, `mailkite_agent`, domain/route/webhook management, and more. Full list + schemas: **https://mailkite.dev/docs/libraries#mcp**.
 
-```
-api.json  ──▶  one MCP tool per method (name, description, input schema)
-schemas/* ──▶  ajv validators (validate the call before dispatch)
-Node SDK  ──▶  MailKite.request(method, path, body)  (auth, HTTP, errors)
-              local methods (verifyWebhook) dispatch in-process — no HTTP
-```
+## Use it from an AI agent — MCP + Agent connectors
 
-See [`PLAN.md`](./PLAN.md) for the full design.
+MailKite speaks the [Model Context Protocol](https://modelcontextprotocol.io): every API method is a tool your AI assistant (Claude, Cursor, …) can call — send mail, manage domains, search the docs, and give an agent its own inbox. Full guide: **[https://mailkite.dev/docs/ai-agents](https://mailkite.dev/docs/ai-agents)**.
 
-## Develop
+**Hosted (recommended) — one-click OAuth, no key to copy:**
 
 ```bash
-npm install
-npm test        # boots the server over stdio, lists tools, checks validation + wire bytes
+claude mcp add --transport http mailkite https://mcp.mailkite.dev/mcp
+```
+
+In Claude Code you can also install the plugin:
+
+```text
+/plugin marketplace add mailkite/claude-code
+/plugin install mailkite@mailkite
 ```
 
-## License
+Any chat/UI agent: *"Add the MCP server at https://mcp.mailkite.dev/mcp and authenticate in the browser when prompted."*
+
+**Local (static key, offline / CI):**
+
+```json
+{ "mcpServers": { "mailkite": { "command": "npx", "args": ["-y", "@mailkite/mcp"], "env": { "MAILKITE_API_KEY": "mk_live_…" } } } }
+```
 
-MIT
+**Give an agent its own inbox.** Route inbound mail to a built-in **inbox agent** (the `agent` route action) and it answers, files, or escalates on its own — see [https://mailkite.dev/docs/ai-agents](https://mailkite.dev/docs/ai-agents).
+
+## All MailKite libraries
+
+Same contract, every language — pick the one for your stack (full list: [https://mailkite.dev/docs/libraries](https://mailkite.dev/docs/libraries)):
+
+| Library | Repo | Distribution |
+| --- | --- | --- |
+| MailKite for Node.js | [`mailkite-node`](https://github.com/mailkite/mailkite-node) | npm |
+| MailKite for Python | [`mailkite-python`](https://github.com/mailkite/mailkite-python) | PyPI |
+| MailKite for Ruby | [`mailkite-ruby`](https://github.com/mailkite/mailkite-ruby) | RubyGems |
+| MailKite for Java | [`mailkite-java`](https://github.com/mailkite/mailkite-java) | Maven Central |
+| MailKite for PHP | [`mailkite-php`](https://github.com/mailkite/mailkite-php) | Packagist |
+| MailKite for Go | [`mailkite-go`](https://github.com/mailkite/mailkite-go) | Go modules |
+| @mailkite/cli | [`mailkite-cli`](https://github.com/mailkite/mailkite-cli) | npm |
+| @mailkite/mcp **(this repo)** | [`mailkite-mcp`](https://github.com/mailkite/mailkite-mcp) | npm |
+| @mailkite/client | [`mailkite-js`](https://github.com/mailkite/mailkite-js) | npm |
+| @mailkite/expo | [`mailkite-expo`](https://github.com/mailkite/mailkite-expo) | npm |
+| MailKiteClient | [`mailkite-swift`](https://github.com/mailkite/mailkite-swift) | Swift Package Manager |
+| dev.mailkite:mailkite-client | [`mailkite-kotlin`](https://github.com/mailkite/mailkite-kotlin) | Maven Central |
+| mailkite_client | [`mailkite-flutter`](https://github.com/mailkite/mailkite-flutter) | pub.dev |
+
+## Docs & links
+
+- 📚 **Documentation:** https://mailkite.dev/docs
+- 📦 **This library's guide:** https://mailkite.dev/docs/libraries#mcp
+- 🤖 **AI agents (MCP + inbox agents):** https://mailkite.dev/docs/ai-agents
+- 🌐 **Website:** https://mailkite.dev
+- 🧭 **All libraries:** https://mailkite.dev/docs/libraries
+
+<sub>Generated from the shared MailKite API contract. © MailKite.</sub>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mailkite/mcp",
-  "version": "0.6.0",
+  "version": "0.9.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,12 @@
   "homepage": "https://mailkite.dev/docs/libraries",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/mailkite/mailkite.git",
-    "directory": "sdks/mcp"
+    "url": "git+https://github.com/mailkite/mailkite-mcp.git"
   },
   "license": "MIT",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "ajv": "^8.17.1",
-    "mailkite": "^0.6.0"
+    "mailkite": "^0.9.0"
   }
 }

package/spec/api.json

@@ -1,6 +1,6 @@
 {
   "name": "mailkite",
-  "version": "0.6.0",
+  "version": "0.9.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": {
@@ -343,6 +343,233 @@
       ],
       "returns": "any"
     },
+    {
+      "name": "listLists",
+      "summary": "List your contact lists (static, curated broadcast audiences), each with its member count.",
+      "http": {
+        "method": "GET",
+        "path": "/api/lists"
+      },
+      "args": [],
+      "returns": "any"
+    },
+    {
+      "name": "createList",
+      "summary": "Create a contact list. Returns the list with its id (lst_…); add contacts with addListContacts.",
+      "http": {
+        "method": "POST",
+        "path": "/api/lists"
+      },
+      "args": [
+        {
+          "name": "body",
+          "in": "body",
+          "schema": "create-list-request"
+        }
+      ],
+      "returns": "any"
+    },
+    {
+      "name": "getList",
+      "summary": "Get one contact list with its member count.",
+      "http": {
+        "method": "GET",
+        "path": "/api/lists/{id}"
+      },
+      "args": [
+        {
+          "name": "id",
+          "in": "path"
+        }
+      ],
+      "returns": "any"
+    },
+    {
+      "name": "updateList",
+      "summary": "Rename a contact list.",
+      "http": {
+        "method": "PATCH",
+        "path": "/api/lists/{id}"
+      },
+      "args": [
+        {
+          "name": "id",
+          "in": "path"
+        },
+        {
+          "name": "body",
+          "in": "body",
+          "schema": "update-list-request"
+        }
+      ],
+      "returns": "any"
+    },
+    {
+      "name": "deleteList",
+      "summary": "Delete a contact list. The list is removed; the contacts themselves are kept.",
+      "http": {
+        "method": "DELETE",
+        "path": "/api/lists/{id}"
+      },
+      "args": [
+        {
+          "name": "id",
+          "in": "path"
+        }
+      ],
+      "returns": "any"
+    },
+    {
+      "name": "listListContacts",
+      "summary": "List the contacts that are members of a list.",
+      "http": {
+        "method": "GET",
+        "path": "/api/lists/{id}/contacts"
+      },
+      "args": [
+        {
+          "name": "id",
+          "in": "path"
+        }
+      ],
+      "returns": "any"
+    },
+    {
+      "name": "addListContacts",
+      "summary": "Add contacts (by id, ctr_…) to a list. Returns how many were newly added; contacts already on the list are ignored.",
+      "http": {
+        "method": "POST",
+        "path": "/api/lists/{id}/contacts"
+      },
+      "args": [
+        {
+          "name": "id",
+          "in": "path"
+        },
+        {
+          "name": "body",
+          "in": "body",
+          "schema": "add-list-contacts-request"
+        }
+      ],
+      "returns": "any"
+    },
+    {
+      "name": "removeListContact",
+      "summary": "Remove one contact from a list (the contact itself is kept).",
+      "http": {
+        "method": "DELETE",
+        "path": "/api/lists/{id}/contacts/{contactId}"
+      },
+      "args": [
+        {
+          "name": "id",
+          "in": "path"
+        },
+        {
+          "name": "contactId",
+          "in": "path"
+        }
+      ],
+      "returns": "any"
+    },
+    {
+      "name": "listBroadcasts",
+      "summary": "List your broadcasts (one-to-many sends) with status and send stats.",
+      "http": {
+        "method": "GET",
+        "path": "/api/broadcasts"
+      },
+      "args": [],
+      "returns": "any"
+    },
+    {
+      "name": "createBroadcast",
+      "summary": "Create a broadcast draft. `from` is required; set `audience` to { type: \"all\" } or { type: \"list\", id: \"lst_…\" }. Returns the broadcast with its id (bct_…). Send it with sendBroadcast.",
+      "http": {
+        "method": "POST",
+        "path": "/api/broadcasts"
+      },
+      "args": [
+        {
+          "name": "body",
+          "in": "body",
+          "schema": "create-broadcast-request"
+        }
+      ],
+      "returns": "any"
+    },
+    {
+      "name": "getBroadcast",
+      "summary": "Get one broadcast with its status and recipient summary.",
+      "http": {
+        "method": "GET",
+        "path": "/api/broadcasts/{id}"
+      },
+      "args": [
+        {
+          "name": "id",
+          "in": "path"
+        }
+      ],
+      "returns": "any"
+    },
+    {
+      "name": "updateBroadcast",
+      "summary": "Edit a draft broadcast (any of from/subject/audience/html/… ). Drafts only.",
+      "http": {
+        "method": "PATCH",
+        "path": "/api/broadcasts/{id}"
+      },
+      "args": [
+        {
+          "name": "id",
+          "in": "path"
+        },
+        {
+          "name": "body",
+          "in": "body",
+          "schema": "update-broadcast-request"
+        }
+      ],
+      "returns": "any"
+    },
+    {
+      "name": "deleteBroadcast",
+      "summary": "Delete a broadcast draft.",
+      "http": {
+        "method": "DELETE",
+        "path": "/api/broadcasts/{id}"
+      },
+      "args": [
+        {
+          "name": "id",
+          "in": "path"
+        }
+      ],
+      "returns": "any"
+    },
+    {
+      "name": "sendBroadcast",
+      "summary": "Send a broadcast now, or pass an ISO 8601 `scheduledAt` to schedule it. A one-click unsubscribe is always added. Returns the status and resolved audience count.",
+      "http": {
+        "method": "POST",
+        "path": "/api/broadcasts/{id}/send"
+      },
+      "args": [
+        {
+          "name": "id",
+          "in": "path"
+        },
+        {
+          "name": "body",
+          "in": "body",
+          "schema": "send-broadcast-request"
+        }
+      ],
+      "returns": "any",
+      "agentConfirm": true
+    },
     {
       "name": "verifyWebhook",
       "summary": "Verify the `x-mailkite-signature` header on an inbound webhook delivery. Runs entirely locally (HMAC-SHA256 over `${t}.${payload}`) — no network call. Returns true only when the signature matches and the event is within the freshness window.",
@@ -415,6 +642,21 @@
       ],
       "returns": "string",
       "sdkOnly": true
+    },
+    {
+      "name": "semanticSearch",
+      "summary": "Semantic search over the MailKite documentation — returns the most relevant doc sections for a natural-language query (hybrid vector + keyword search over https://mailkite.dev/docs). Public; no authentication required.",
+      "http": {
+        "method": "GET",
+        "path": "/v1/docs/search"
+      },
+      "args": [
+        {
+          "name": "query",
+          "in": "query"
+        }
+      ],
+      "returns": "semantic-search-response"
     }
   ]
 }

package/spec/cases.json

@@ -693,13 +693,386 @@
         "ok": true
       }
     },
+    {
+      "name": "list_lists",
+      "method": "listLists",
+      "args": {},
+      "request": {
+        "method": "GET",
+        "path": "/api/lists"
+      },
+      "response": {
+        "status": 200,
+        "body": [
+          {
+            "id": "lst_1",
+            "name": "Beta testers",
+            "member_count": 2
+          }
+        ]
+      },
+      "result": [
+        {
+          "id": "lst_1",
+          "name": "Beta testers",
+          "member_count": 2
+        }
+      ]
+    },
+    {
+      "name": "create_list",
+      "method": "createList",
+      "args": {
+        "name": "Beta testers"
+      },
+      "request": {
+        "method": "POST",
+        "path": "/api/lists",
+        "bodySchema": "create-list-request",
+        "body": {
+          "name": "Beta testers"
+        }
+      },
+      "response": {
+        "status": 201,
+        "body": {
+          "id": "lst_1",
+          "name": "Beta testers",
+          "member_count": 0
+        }
+      },
+      "result": {
+        "id": "lst_1",
+        "name": "Beta testers",
+        "member_count": 0
+      }
+    },
+    {
+      "name": "get_list",
+      "method": "getList",
+      "args": {
+        "id": "lst_1"
+      },
+      "request": {
+        "method": "GET",
+        "path": "/api/lists/lst_1"
+      },
+      "response": {
+        "status": 200,
+        "body": {
+          "id": "lst_1",
+          "name": "Beta testers",
+          "member_count": 2
+        }
+      },
+      "result": {
+        "id": "lst_1",
+        "name": "Beta testers",
+        "member_count": 2
+      }
+    },
+    {
+      "name": "update_list",
+      "method": "updateList",
+      "args": {
+        "id": "lst_1",
+        "name": "VIPs"
+      },
+      "request": {
+        "method": "PATCH",
+        "path": "/api/lists/lst_1",
+        "bodySchema": "update-list-request",
+        "body": {
+          "name": "VIPs"
+        }
+      },
+      "response": {
+        "status": 200,
+        "body": {
+          "id": "lst_1",
+          "name": "VIPs",
+          "member_count": 2
+        }
+      },
+      "result": {
+        "id": "lst_1",
+        "name": "VIPs",
+        "member_count": 2
+      }
+    },
+    {
+      "name": "delete_list",
+      "method": "deleteList",
+      "args": {
+        "id": "lst_1"
+      },
+      "request": {
+        "method": "DELETE",
+        "path": "/api/lists/lst_1"
+      },
+      "response": {
+        "status": 200,
+        "body": {
+          "ok": true
+        }
+      },
+      "result": {
+        "ok": true
+      }
+    },
+    {
+      "name": "list_list_contacts",
+      "method": "listListContacts",
+      "args": {
+        "id": "lst_1"
+      },
+      "request": {
+        "method": "GET",
+        "path": "/api/lists/lst_1/contacts"
+      },
+      "response": {
+        "status": 200,
+        "body": [
+          {
+            "id": "ctr_1",
+            "email": "jane@acme.com",
+            "name": "Jane Doe"
+          }
+        ]
+      },
+      "result": [
+        {
+          "id": "ctr_1",
+          "email": "jane@acme.com",
+          "name": "Jane Doe"
+        }
+      ]
+    },
+    {
+      "name": "add_list_contacts",
+      "method": "addListContacts",
+      "args": {
+        "id": "lst_1",
+        "contactIds": [
+          "ctr_1",
+          "ctr_2"
+        ]
+      },
+      "request": {
+        "method": "POST",
+        "path": "/api/lists/lst_1/contacts",
+        "bodySchema": "add-list-contacts-request",
+        "body": {
+          "contactIds": [
+            "ctr_1",
+            "ctr_2"
+          ]
+        }
+      },
+      "response": {
+        "status": 200,
+        "body": {
+          "added": 2
+        }
+      },
+      "result": {
+        "added": 2
+      }
+    },
+    {
+      "name": "remove_list_contact",
+      "method": "removeListContact",
+      "args": {
+        "id": "lst_1",
+        "contactId": "ctr_1"
+      },
+      "request": {
+        "method": "DELETE",
+        "path": "/api/lists/lst_1/contacts/ctr_1"
+      },
+      "response": {
+        "status": 200,
+        "body": {
+          "ok": true
+        }
+      },
+      "result": {
+        "ok": true
+      }
+    },
+    {
+      "name": "list_broadcasts",
+      "method": "listBroadcasts",
+      "args": {},
+      "request": {
+        "method": "GET",
+        "path": "/api/broadcasts"
+      },
+      "response": {
+        "status": 200,
+        "body": [
+          {
+            "id": "bct_1",
+            "subject": "Launch week",
+            "status": "draft"
+          }
+        ]
+      },
+      "result": [
+        {
+          "id": "bct_1",
+          "subject": "Launch week",
+          "status": "draft"
+        }
+      ]
+    },
+    {
+      "name": "create_broadcast",
+      "method": "createBroadcast",
+      "args": {
+        "from": "news@app.mailkite.dev",
+        "subject": "Launch week",
+        "audience": {
+          "type": "all"
+        },
+        "html": "<h1>We shipped</h1>"
+      },
+      "request": {
+        "method": "POST",
+        "path": "/api/broadcasts",
+        "bodySchema": "create-broadcast-request",
+        "body": {
+          "from": "news@app.mailkite.dev",
+          "subject": "Launch week",
+          "audience": {
+            "type": "all"
+          },
+          "html": "<h1>We shipped</h1>"
+        }
+      },
+      "response": {
+        "status": 201,
+        "body": {
+          "id": "bct_1",
+          "subject": "Launch week",
+          "status": "draft"
+        }
+      },
+      "result": {
+        "id": "bct_1",
+        "subject": "Launch week",
+        "status": "draft"
+      }
+    },
+    {
+      "name": "get_broadcast",
+      "method": "getBroadcast",
+      "args": {
+        "id": "bct_1"
+      },
+      "request": {
+        "method": "GET",
+        "path": "/api/broadcasts/bct_1"
+      },
+      "response": {
+        "status": 200,
+        "body": {
+          "id": "bct_1",
+          "subject": "Launch week",
+          "status": "draft"
+        }
+      },
+      "result": {
+        "id": "bct_1",
+        "subject": "Launch week",
+        "status": "draft"
+      }
+    },
+    {
+      "name": "update_broadcast",
+      "method": "updateBroadcast",
+      "args": {
+        "id": "bct_1",
+        "subject": "Launch week (final)"
+      },
+      "request": {
+        "method": "PATCH",
+        "path": "/api/broadcasts/bct_1",
+        "bodySchema": "update-broadcast-request",
+        "body": {
+          "subject": "Launch week (final)"
+        }
+      },
+      "response": {
+        "status": 200,
+        "body": {
+          "id": "bct_1",
+          "subject": "Launch week (final)",
+          "status": "draft"
+        }
+      },
+      "result": {
+        "id": "bct_1",
+        "subject": "Launch week (final)",
+        "status": "draft"
+      }
+    },
+    {
+      "name": "delete_broadcast",
+      "method": "deleteBroadcast",
+      "args": {
+        "id": "bct_1"
+      },
+      "request": {
+        "method": "DELETE",
+        "path": "/api/broadcasts/bct_1"
+      },
+      "response": {
+        "status": 200,
+        "body": {
+          "ok": true
+        }
+      },
+      "result": {
+        "ok": true
+      }
+    },
+    {
+      "name": "send_broadcast",
+      "method": "sendBroadcast",
+      "args": {
+        "id": "bct_1",
+        "scheduledAt": "2026-07-01T15:00:00Z"
+      },
+      "request": {
+        "method": "POST",
+        "path": "/api/broadcasts/bct_1/send",
+        "bodySchema": "send-broadcast-request",
+        "body": {
+          "scheduledAt": "2026-07-01T15:00:00Z"
+        }
+      },
+      "response": {
+        "status": 200,
+        "body": {
+          "id": "bct_1",
+          "status": "scheduled",
+          "audienceCount": 2
+        }
+      },
+      "result": {
+        "id": "bct_1",
+        "status": "scheduled",
+        "audienceCount": 2
+      }
+    },
     {
       "name": "send_with_template",
       "method": "send",
       "args": {
         "from": "hello@app.mailkite.dev",
         "to": "ada@example.com",
-        "templateId": "base_welcome-dark",
+        "templateId": "base_welcome",
         "templateData": {
           "name": "Ada"
         }
@@ -711,7 +1084,7 @@
         "body": {
           "from": "hello@app.mailkite.dev",
           "to": "ada@example.com",
-          "templateId": "base_welcome-dark",
+          "templateId": "base_welcome",
           "templateData": {
             "name": "Ada"
           }
@@ -771,8 +1144,8 @@
         "status": 200,
         "body": [
           {
-            "id": "base_welcome-dark",
-            "name": "Welcome — Dark",
+            "id": "base_welcome",
+            "name": "Welcome",
             "category": "Welcome",
             "subject": "Welcome to MailKite",
             "is_base": 1
@@ -781,8 +1154,8 @@
       },
       "result": [
         {
-          "id": "base_welcome-dark",
-          "name": "Welcome — Dark",
+          "id": "base_welcome",
+          "name": "Welcome",
           "category": "Welcome",
           "subject": "Welcome to MailKite",
           "is_base": 1
@@ -817,7 +1190,7 @@
       "name": "create_template",
       "method": "createTemplate",
       "args": {
-        "baseId": "base_welcome-dark",
+        "baseId": "base_welcome",
         "name": "My Welcome"
       },
       "request": {
@@ -825,7 +1198,7 @@
         "path": "/api/templates",
         "bodySchema": "create-template-request",
         "body": {
-          "baseId": "base_welcome-dark",
+          "baseId": "base_welcome",
           "name": "My Welcome"
         }
       },
@@ -994,6 +1367,42 @@
         "privateKey": "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC9E2ll8K9E314m\njPfFkDBmImKFyvnqBJnqHukcAteqs99kK5QSx5wmg7PUw/9Ti/HTOr2V6lgXy6d+\nXbZl3XjCaFkmgTgKF9Zz8TtIQVUJNlmw1ztKEFr+yILoFovNxnND5WR+Nd5BUC6W\nW8sOAjswB21WthjDyVfEVSOHHRdYHcKAiF6e7yISDL5p9rcLFGjV37dvmH0DcskJ\nuYNwuAXlsEi4NIC3u4hK23pP9BEkDEmf0rmbSHugTl/VyzAlUiN/wUEcGu9Rl5iD\npIar+Vnbyr8ze6RNChWKcNjCZdGgI1mLDItbPEtW1IPvtyP6ymGuUqwl+C553q2t\nhuCURvlrAgMBAAECggEAWua+QXhZi28oQLh9VspfunrFizVuuYfEx75crE7hiPw5\nZltdMTouZIXlK2Gfm3coqDkRdMXZ3HbY6/P6ATddG3o3gj+VxaR4Qf20VqSyUV+D\n93VC1/TNCrkz1okgZaoHOJlMmzEizZvTCg7PrMh91DV957ZcaaSfQZD9J7RgyMeS\nC393/TI2IBR3nFQQMuNt0Rx0uXy2/T18hNQl2eSL+L2V+oCMERRetWzn9rQMDXI7\niLmh/dxE4gcTdSIflAUonWSFH6e9o8p+yJja4J966wP+B7j2dqmFr/09gBa3djHv\nEy+nhTYpfTrfYKnnE2pcXpFHWhd1iyRls93+Mb/RwQKBgQDqCyTLa8hjeeAun7fq\n2piRrFVr8NRVrFQwLmA8/3lcjXhCC80FG+SdSaZBJPD7EFDT3xePl/OnQmSHSnpR\nD+vklHVPAO4n3aMa/HKFgpxasxpUqRddzL6bBFNHpBgQR9Wv6hPiDP42SS7//uQF\nkrduS20kKsnrpGogy48zJQLfYwKBgQDO0E+PMmshHWbWDEE7Fjoe0dZtPx7CSG0B\nKXj5G+njHltUxPxodAYb95dUHQl/sFy3JpNcyBk8P+qlc/fhqojR/fE3+qK+EHjw\nKW/Ka4vEegtwdTXIeG4WgpTtFOjY7qsGHSFk2rFFjDrYtCMq6IBIClqk+dueCg52\nQsEHXQRwWQKBgQDBDNQa3xr5wswCaUhhdlImxsnnMU1UJcODwp0rc2d9ykuJ3wYL\n0sguXVO/pGMKFJk3Smu6zBH0wzT8y5g9SS7A6xwgQJoxVAZ3+gfUzLl/rwBnGNrn\nSj1mzJiNHXOj6jz+z8v6x9DgolkcW/lmB3E6jwjFrm3D62iHCKFkBIFsFQKBgAGq\ni/mLXnGV2w4+awge1bkJ18BpkcXe74Hi46aeIvRBelrke2QcCzCOfhmfYkQ1F4oi\nNW257vodSbariIO47AFFGnxo+Iave0n0C4KF+0pJ8W2mhBhpX/muc6S1VmrpAVe7\nRFmbqXH1/0NfsCjYVrA95R0PJkXPru4k+4kjprWBAoGAHtU/VXiOqSagIo3J/Bm5\nyUcJdbbguV/T9PPVu/Lq8SypCd5vqmwgYRmG+mIJEd/VYRkCZn3gbqNCn5OfbJh5\nG4Xatr7aofxyz2Qon/nix8Ut1+s1Npg1ugkz/atr4CZ4QArk8JmwsCReWJXCjKLX\n2WObKEWjGhgwths3MrC/CDw=\n-----END PRIVATE KEY-----"
       },
       "result": "Hello from MailKite — encrypted at rest. 🔒"
+    },
+    {
+      "name": "semantic_search",
+      "method": "semanticSearch",
+      "args": {
+        "query": "domains"
+      },
+      "request": {
+        "method": "GET",
+        "path": "/v1/docs/search"
+      },
+      "response": {
+        "status": 200,
+        "body": {
+          "query": "domains",
+          "matches": [
+            {
+              "slug": "domains",
+              "title": "Domains & DNS",
+              "section": "website",
+              "snippet": "Add a domain, set DNS, and verify."
+            }
+          ]
+        }
+      },
+      "result": {
+        "query": "domains",
+        "matches": [
+          {
+            "slug": "domains",
+            "title": "Domains & DNS",
+            "section": "website",
+            "snippet": "Add a domain, set DNS, and verify."
+          }
+        ]
+      }
     }
   ]
 }

package/spec/schemas/add-list-contacts-request.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "add-list-contacts-request",
+  "title": "Add contacts to list request body",
+  "type": "object",
+  "required": ["contactIds"],
+  "additionalProperties": false,
+  "properties": {
+    "contactIds": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  }
+}

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

@@ -0,0 +1,28 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "create-broadcast-request",
+  "title": "Create broadcast request body",
+  "type": "object",
+  "required": ["from"],
+  "additionalProperties": false,
+  "properties": {
+    "name": { "type": "string" },
+    "from": { "type": "string" },
+    "replyTo": { "type": "string" },
+    "subject": { "type": "string" },
+    "preview": { "type": "string" },
+    "audience": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "type": { "type": "string", "enum": ["all", "list", "filter"] },
+        "id": { "type": "string" },
+        "query": { "type": "string" }
+      }
+    },
+    "templateId": { "type": "string" },
+    "html": { "type": "string" },
+    "text": { "type": "string" },
+    "footerAddress": { "type": "string" }
+  }
+}

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

@@ -0,0 +1,11 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "create-list-request",
+  "title": "Create list request body",
+  "type": "object",
+  "required": ["name"],
+  "additionalProperties": false,
+  "properties": {
+    "name": { "type": "string" }
+  }
+}

package/spec/schemas/semantic-search-response.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "semantic-search-response",
+  "title": "Semantic docs search response",
+  "type": "object",
+  "required": ["query", "matches"],
+  "properties": {
+    "query": { "type": "string", "description": "The query that was searched." },
+    "matches": {
+      "type": "array",
+      "description": "Most-relevant documentation sections, best first.",
+      "items": {
+        "type": "object",
+        "required": ["slug", "title", "snippet"],
+        "properties": {
+          "slug": { "type": "string", "description": "Doc slug — the page lives at https://mailkite.dev/docs/<slug> (e.g. \"quickstart\", \"domains\")." },
+          "title": { "type": "string", "description": "Human page title." },
+          "section": { "type": "string", "description": "Doc section/category." },
+          "snippet": { "type": "string", "description": "A relevant excerpt from the matched section." },
+          "score": { "type": "number", "description": "Relevance score (higher is closer); absent for lexical-only matches." }
+        }
+      }
+    }
+  }
+}

package/spec/schemas/send-broadcast-request.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "send-broadcast-request",
+  "title": "Send broadcast request body",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "scheduledAt": { "type": "string" }
+  }
+}

package/spec/schemas/update-broadcast-request.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "update-broadcast-request",
+  "title": "Update broadcast request body (draft edits; all fields optional)",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "name": { "type": "string" },
+    "from": { "type": "string" },
+    "replyTo": { "type": "string" },
+    "subject": { "type": "string" },
+    "preview": { "type": "string" },
+    "audience": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "type": { "type": "string", "enum": ["all", "list", "filter"] },
+        "id": { "type": "string" },
+        "query": { "type": "string" }
+      }
+    },
+    "templateId": { "type": "string" },
+    "html": { "type": "string" },
+    "text": { "type": "string" },
+    "footerAddress": { "type": "string" }
+  }
+}

package/spec/schemas/update-list-request.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "update-list-request",
+  "title": "Update list request body",
+  "type": "object",
+  "required": ["name"],
+  "additionalProperties": false,
+  "properties": {
+    "name": { "type": "string" }
+  }
+}