@mailkite/mcp 0.1.0

package/README.md

@@ -0,0 +1,88 @@
+# @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.
+
+## 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.
+
+```json
+{
+  "mcpServers": {
+    "mailkite": {
+      "command": "npx",
+      "args": ["-y", "@mailkite/mcp"],
+      "env": { "MAILKITE_API_KEY": "mk_live_…" }
+    }
+  }
+}
+```
+
+| 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_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
+
+```
+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
+```
+
+See [`PLAN.md`](./PLAN.md) for the full design.
+
+## Develop
+
+```bash
+npm install
+npm test        # boots the server over stdio, lists tools, checks validation + wire bytes
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@mailkite/mcp",
+  "version": "0.1.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": {
+    "mailkite-mcp": "server.mjs"
+  },
+  "files": [
+    "server.mjs",
+    "spec",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prepack": "node prepack.mjs",
+    "postpack": "node -e \"require('node:fs').rmSync('spec',{recursive:true,force:true})\"",
+    "test": "node smoke.mjs && node wire-test.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mailkite",
+    "mcp",
+    "model-context-protocol",
+    "email",
+    "ai",
+    "agent",
+    "tools"
+  ],
+  "homepage": "https://mailkite.dev/docs/libraries",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fijiwebdesign/mailkite.git",
+    "directory": "sdks/mcp"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "ajv": "^8.17.1",
+    "mailkite": "^0.1.0"
+  }
+}

package/server.mjs

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+// MailKite MCP server.
+//
+// This is *only* the MCP layer. Everything else is reused:
+//   • Operation ↔ endpoint mapping → ../spec/api.json  (the canonical contract)
+//   • Input validation             → ../spec/schemas/*.json compiled with ajv
+//                                     (the same files + validator as conformance)
+//   • Transport / auth / errors    → the MailKite Node SDK (../node)
+//
+// We read api.json at startup and register one MCP tool per method. A call is
+// validated against the shared JSON Schema, then dispatched through the SDK's
+// low-level request(). No endpoint list, schema, or HTTP logic is duplicated.
+
+import { readFileSync, readdirSync, existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import Ajv from "ajv";
+import { MailKite, MailKiteError } from "mailkite";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+// Prefer a spec bundled into the package (copied in at publish time by prepack);
+// fall back to the sibling sdks/spec when running straight from the repo.
+const SPEC = existsSync(path.join(HERE, "spec")) ? path.join(HERE, "spec") : path.resolve(HERE, "..", "spec");
+
+// ---- load the canonical contract --------------------------------------------
+const api = JSON.parse(readFileSync(path.join(SPEC, "api.json"), "utf8"));
+
+// Compile one ajv validator per body schema — same config + files as
+// sdks/conformance/run.mjs, so the MCP rejects exactly what the SDKs reject.
+const ajv = new Ajv({ allErrors: true, strict: false });
+const schemas = {}; // id -> parsed schema
+const validators = {}; // id -> compiled validator
+for (const file of readdirSync(path.join(SPEC, "schemas"))) {
+  if (!file.endsWith(".json")) continue;
+  const id = file.replace(/\.json$/, "");
+  const schema = JSON.parse(readFileSync(path.join(SPEC, "schemas", file), "utf8"));
+  schemas[id] = schema;
+  validators[id] = ajv.compile(schema);
+}
+
+// ---- turn each api.json method into an MCP tool -----------------------------
+function toSnake(name) {
+  return name.replace(/([A-Z])/g, "_$1").toLowerCase();
+}
+const toolName = (method) => `mailkite_${toSnake(method.name)}`;
+
+// Build the flat input schema for a method: path params (as strings) merged with
+// the referenced body schema's properties, so the model sees real field names.
+function buildInputSchema(method) {
+  const properties = {};
+  const required = [];
+
+  for (const arg of method.args || []) {
+    if (arg.in === "path") {
+      properties[arg.name] = { type: "string", description: `Path parameter \`${arg.name}\`.` };
+      required.push(arg.name);
+    } else if (arg.in === "body" && arg.schema && schemas[arg.schema]) {
+      const body = schemas[arg.schema];
+      Object.assign(properties, body.properties || {});
+      for (const r of body.required || []) required.push(r);
+    }
+  }
+
+  return { type: "object", properties, required, additionalProperties: false };
+}
+
+const credentialNote = (method) => {
+  if (method.local) return "Runs locally (no API call) — no credentials needed.";
+  return method.http.path.startsWith("/v1/")
+    ? "Requires an API key (mk_live_…)."
+    : "Requires a management session token.";
+};
+
+const tools = api.methods.map((method) => ({
+  name: toolName(method),
+  description: `${method.summary} ${credentialNote(method)}`,
+  inputSchema: buildInputSchema(method),
+  _method: method, // kept server-side for dispatch; not sent to the client
+}));
+
+const byToolName = new Map(tools.map((t) => [t.name, t]));
+
+// ---- dispatch ---------------------------------------------------------------
+const apiKey = process.env.MAILKITE_API_KEY;
+const baseUrl = process.env.MAILKITE_BASE_URL;
+const mk = new MailKite(apiKey || "", baseUrl || undefined);
+
+// Split a tool's flat input into (resolved path, validated body).
+function resolveCall(method, input) {
+  input = input || {};
+  let urlPath = method.http.path;
+  let bodySchemaId = null;
+
+  for (const arg of method.args || []) {
+    if (arg.in === "path") {
+      const value = input[arg.name];
+      if (value == null || value === "") throw new Error(`Missing required path parameter: ${arg.name}`);
+      urlPath = urlPath.replace(`{${arg.name}}`, encodeURIComponent(String(value)));
+    } else if (arg.in === "body" && arg.schema) {
+      bodySchemaId = arg.schema;
+    }
+  }
+
+  let body;
+  if (bodySchemaId) {
+    // The body is exactly the schema's own properties (path params are excluded,
+    // since every body schema is additionalProperties:false).
+    const keys = Object.keys(schemas[bodySchemaId].properties || {});
+    body = {};
+    for (const k of keys) if (input[k] !== undefined) body[k] = input[k];
+
+    const validate = validators[bodySchemaId];
+    if (!validate(body)) {
+      throw new Error(`Invalid input for ${bodySchemaId}: ${ajv.errorsText(validate.errors)}`);
+    }
+  }
+
+  return { method: method.http.method, urlPath, body };
+}
+
+// ---- MCP server -------------------------------------------------------------
+const server = new Server(
+  { name: "mailkite", version: api.version || "0.1.0" },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: tools.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })),
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const tool = byToolName.get(req.params.name);
+  if (!tool) {
+    return { isError: true, content: [{ type: "text", text: `Unknown tool: ${req.params.name}` }] };
+  }
+
+  // Local methods (e.g. verifyWebhook) run in-process — no API key, no network.
+  // Validate against the same JSON Schema, then dispatch through the SDK.
+  if (tool._method.local) {
+    try {
+      const input = req.params.arguments || {};
+      const bodyArg = (tool._method.args || []).find((a) => a.in === "body");
+      if (bodyArg?.schema) {
+        const validate = validators[bodyArg.schema];
+        if (!validate(input)) {
+          return {
+            isError: true,
+            content: [{ type: "text", text: `Invalid input for ${bodyArg.schema}: ${ajv.errorsText(validate.errors)}` }],
+          };
+        }
+      }
+      if (tool._method.name !== "verifyWebhook") {
+        throw new Error(`No local handler for ${tool._method.name}`);
+      }
+      const valid = mk.verifyWebhook(input.signature, input.payload, input.secret, input.toleranceMs);
+      return { content: [{ type: "text", text: JSON.stringify({ valid }, null, 2) }] };
+    } catch (err) {
+      return { isError: true, content: [{ type: "text", text: `Error: ${err.message}` }] };
+    }
+  }
+
+  if (!apiKey) {
+    return {
+      isError: true,
+      content: [{ type: "text", text: "MAILKITE_API_KEY is not set. Provide it in the MCP server env." }],
+    };
+  }
+
+  try {
+    const { method, urlPath, body } = resolveCall(tool._method, req.params.arguments);
+    const result = await mk.request(method, urlPath, body);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+  } catch (err) {
+    const text =
+      err instanceof MailKiteError
+        ? `MailKite API error ${err.status}: ${err.message}`
+        : `Error: ${err.message}`;
+    return { isError: true, content: [{ type: "text", text }] };
+  }
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+// Note: stdout is the MCP transport — never console.log here. Use stderr.
+console.error(`mailkite mcp server ready — ${tools.length} tools, base ${mk.baseUrl}`);

package/spec/api.json

@@ -0,0 +1,121 @@
+{
+  "name": "mailkite",
+  "version": "0.1.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": {
+    "scheme": "bearer",
+    "header": "Authorization",
+    "note": "Send uses an API key (mk_live_…); management endpoints use a session token. Both are Bearer credentials, so the client takes one token."
+  },
+  "methods": [
+    {
+      "name": "send",
+      "summary": "Send a message over a verified domain.",
+      "http": { "method": "POST", "path": "/v1/send" },
+      "args": [{ "name": "message", "in": "body", "schema": "send-request" }],
+      "returns": "send-response"
+    },
+    {
+      "name": "listDomains",
+      "summary": "List your domains, each with its webhook URL.",
+      "http": { "method": "GET", "path": "/api/domains" },
+      "args": [],
+      "returns": "any"
+    },
+    {
+      "name": "createDomain",
+      "summary": "Add a domain. Returns the domain + DNS records.",
+      "http": { "method": "POST", "path": "/api/domains" },
+      "args": [{ "name": "body", "in": "body", "schema": "create-domain-request" }],
+      "returns": "any"
+    },
+    {
+      "name": "getDomain",
+      "summary": "Get one domain with DNS records + webhook.",
+      "http": { "method": "GET", "path": "/api/domains/{id}" },
+      "args": [{ "name": "id", "in": "path" }],
+      "returns": "any"
+    },
+    {
+      "name": "deleteDomain",
+      "summary": "Remove a domain.",
+      "http": { "method": "DELETE", "path": "/api/domains/{id}" },
+      "args": [{ "name": "id", "in": "path" }],
+      "returns": "any"
+    },
+    {
+      "name": "verifyDomain",
+      "summary": "Check DNS and update status.",
+      "http": { "method": "POST", "path": "/api/domains/{id}/verify" },
+      "args": [{ "name": "id", "in": "path" }],
+      "returns": "any"
+    },
+    {
+      "name": "setWebhook",
+      "summary": "Set or replace the domain's catch-all webhook.",
+      "http": { "method": "PUT", "path": "/api/domains/{id}/webhook" },
+      "args": [
+        { "name": "id", "in": "path" },
+        { "name": "body", "in": "body", "schema": "set-webhook-request" }
+      ],
+      "returns": "any"
+    },
+    {
+      "name": "deleteWebhook",
+      "summary": "Remove the domain's webhook.",
+      "http": { "method": "DELETE", "path": "/api/domains/{id}/webhook" },
+      "args": [{ "name": "id", "in": "path" }],
+      "returns": "any"
+    },
+    {
+      "name": "testWebhook",
+      "summary": "Send a signed test event to the domain's webhook.",
+      "http": { "method": "POST", "path": "/api/domains/{id}/webhook/test" },
+      "args": [{ "name": "id", "in": "path" }],
+      "returns": "any"
+    },
+    {
+      "name": "listRoutes",
+      "summary": "List inbound routing rules.",
+      "http": { "method": "GET", "path": "/api/routes" },
+      "args": [],
+      "returns": "any"
+    },
+    {
+      "name": "createRoute",
+      "summary": "Create a route (match, action, destination).",
+      "http": { "method": "POST", "path": "/api/routes" },
+      "args": [{ "name": "body", "in": "body", "schema": "create-route-request" }],
+      "returns": "any"
+    },
+    {
+      "name": "listMessages",
+      "summary": "List stored messages.",
+      "http": { "method": "GET", "path": "/api/messages" },
+      "args": [],
+      "returns": "any"
+    },
+    {
+      "name": "getMessage",
+      "summary": "Get a message with deliveries + attachments.",
+      "http": { "method": "GET", "path": "/api/messages/{id}" },
+      "args": [{ "name": "id", "in": "path" }],
+      "returns": "any"
+    },
+    {
+      "name": "retryDelivery",
+      "summary": "Re-deliver a stored message to its webhook.",
+      "http": { "method": "POST", "path": "/api/deliveries/{id}/retry" },
+      "args": [{ "name": "id", "in": "path" }],
+      "returns": "any"
+    },
+    {
+      "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.",
+      "local": true,
+      "args": [{ "name": "body", "in": "body", "schema": "verify-webhook-request" }],
+      "returns": "boolean"
+    }
+  ]
+}

package/spec/cases.json

@@ -0,0 +1,244 @@
+{
+  "comment": "Shared cross-language conformance cases. Each SDK's conformance runner reads this file, calls the named method with `args`, and reports the parsed result (or error). The Node harness in sdks/conformance asserts the outgoing HTTP request matches `request` (and validates the body against the referenced JSON Schema) and that the SDK's result matches `result`/`error`. Cases with `\"local\": true` make no HTTP call (e.g. verifyWebhook); for those the harness validates `args` against `argsSchema` and only checks the returned `result`.",
+  "apiKey": "test_key",
+  "cases": [
+    {
+      "name": "send_minimal",
+      "method": "send",
+      "args": { "from": "hello@app.mailkite.dev", "to": "ada@example.com", "subject": "Hi", "text": "It works." },
+      "request": {
+        "method": "POST",
+        "path": "/v1/send",
+        "bodySchema": "send-request",
+        "body": { "from": "hello@app.mailkite.dev", "to": "ada@example.com", "subject": "Hi", "text": "It works." }
+      },
+      "response": { "status": 202, "body": { "id": "msg_minimal", "status": "queued" } },
+      "result": { "id": "msg_minimal", "status": "queued" }
+    },
+    {
+      "name": "send_full",
+      "method": "send",
+      "args": {
+        "from": "hello@app.mailkite.dev",
+        "to": ["ada@example.com", "grace@example.com"],
+        "cc": "cc@example.com",
+        "subject": "Your invoice #1042",
+        "html": "<p>Thanks!</p>",
+        "text": "Thanks!",
+        "replyTo": "support@app.mailkite.dev",
+        "inReplyTo": "<a1b2@mail.example.com>",
+        "attachments": [{ "filename": "receipt.pdf", "url": "https://files.app.com/receipt.pdf" }]
+      },
+      "request": {
+        "method": "POST",
+        "path": "/v1/send",
+        "bodySchema": "send-request",
+        "body": {
+          "from": "hello@app.mailkite.dev",
+          "to": ["ada@example.com", "grace@example.com"],
+          "cc": "cc@example.com",
+          "subject": "Your invoice #1042",
+          "html": "<p>Thanks!</p>",
+          "text": "Thanks!",
+          "replyTo": "support@app.mailkite.dev",
+          "inReplyTo": "<a1b2@mail.example.com>",
+          "attachments": [{ "filename": "receipt.pdf", "url": "https://files.app.com/receipt.pdf" }]
+        }
+      },
+      "response": { "status": 202, "body": { "id": "msg_full", "status": "queued" } },
+      "result": { "id": "msg_full", "status": "queued" }
+    },
+    {
+      "name": "list_domains",
+      "method": "listDomains",
+      "args": {},
+      "request": { "method": "GET", "path": "/api/domains" },
+      "response": { "status": 200, "body": [{ "id": "dom_1", "domain": "app.mailkite.dev" }] },
+      "result": [{ "id": "dom_1", "domain": "app.mailkite.dev" }]
+    },
+    {
+      "name": "create_domain",
+      "method": "createDomain",
+      "args": { "domain": "app.mailkite.dev" },
+      "request": {
+        "method": "POST",
+        "path": "/api/domains",
+        "bodySchema": "create-domain-request",
+        "body": { "domain": "app.mailkite.dev" }
+      },
+      "response": { "status": 200, "body": { "domain": { "id": "dom_1", "status": "pending" }, "dns": [] } },
+      "result": { "domain": { "id": "dom_1", "status": "pending" }, "dns": [] }
+    },
+    {
+      "name": "get_domain",
+      "method": "getDomain",
+      "args": { "id": "dom_1" },
+      "request": { "method": "GET", "path": "/api/domains/dom_1" },
+      "response": { "status": 200, "body": { "id": "dom_1", "domain": "app.mailkite.dev" } },
+      "result": { "id": "dom_1", "domain": "app.mailkite.dev" }
+    },
+    {
+      "name": "delete_domain",
+      "method": "deleteDomain",
+      "args": { "id": "dom_1" },
+      "request": { "method": "DELETE", "path": "/api/domains/dom_1" },
+      "response": { "status": 200, "body": { "ok": true } },
+      "result": { "ok": true }
+    },
+    {
+      "name": "verify_domain",
+      "method": "verifyDomain",
+      "args": { "id": "dom_1" },
+      "request": { "method": "POST", "path": "/api/domains/dom_1/verify" },
+      "response": { "status": 200, "body": { "id": "dom_1", "status": "verified" } },
+      "result": { "id": "dom_1", "status": "verified" }
+    },
+    {
+      "name": "set_webhook",
+      "method": "setWebhook",
+      "args": { "id": "dom_1", "url": "https://app.com/hooks/mailkite" },
+      "request": {
+        "method": "PUT",
+        "path": "/api/domains/dom_1/webhook",
+        "bodySchema": "set-webhook-request",
+        "body": { "url": "https://app.com/hooks/mailkite" }
+      },
+      "response": { "status": 200, "body": { "ok": true, "url": "https://app.com/hooks/mailkite" } },
+      "result": { "ok": true, "url": "https://app.com/hooks/mailkite" }
+    },
+    {
+      "name": "delete_webhook",
+      "method": "deleteWebhook",
+      "args": { "id": "dom_1" },
+      "request": { "method": "DELETE", "path": "/api/domains/dom_1/webhook" },
+      "response": { "status": 200, "body": { "ok": true } },
+      "result": { "ok": true }
+    },
+    {
+      "name": "test_webhook",
+      "method": "testWebhook",
+      "args": { "id": "dom_1" },
+      "request": { "method": "POST", "path": "/api/domains/dom_1/webhook/test" },
+      "response": { "status": 200, "body": { "ok": true } },
+      "result": { "ok": true }
+    },
+    {
+      "name": "list_routes",
+      "method": "listRoutes",
+      "args": {},
+      "request": { "method": "GET", "path": "/api/routes" },
+      "response": { "status": 200, "body": [] },
+      "result": []
+    },
+    {
+      "name": "create_route",
+      "method": "createRoute",
+      "args": { "match": "*@app.mailkite.dev", "action": "webhook", "destination": "https://app.com/hooks" },
+      "request": {
+        "method": "POST",
+        "path": "/api/routes",
+        "bodySchema": "create-route-request",
+        "body": { "match": "*@app.mailkite.dev", "action": "webhook", "destination": "https://app.com/hooks" }
+      },
+      "response": { "status": 200, "body": { "id": "rte_1" } },
+      "result": { "id": "rte_1" }
+    },
+    {
+      "name": "list_messages",
+      "method": "listMessages",
+      "args": {},
+      "request": { "method": "GET", "path": "/api/messages" },
+      "response": { "status": 200, "body": [{ "id": "msg_1" }] },
+      "result": [{ "id": "msg_1" }]
+    },
+    {
+      "name": "get_message",
+      "method": "getMessage",
+      "args": { "id": "msg_1" },
+      "request": { "method": "GET", "path": "/api/messages/msg_1" },
+      "response": { "status": 200, "body": { "id": "msg_1", "deliveries": [], "attachments": [] } },
+      "result": { "id": "msg_1", "deliveries": [], "attachments": [] }
+    },
+    {
+      "name": "retry_delivery",
+      "method": "retryDelivery",
+      "args": { "id": "dlv_1" },
+      "request": { "method": "POST", "path": "/api/deliveries/dlv_1/retry" },
+      "response": { "status": 200, "body": { "ok": true } },
+      "result": { "ok": true }
+    },
+    {
+      "name": "get_message_not_found",
+      "method": "getMessage",
+      "args": { "id": "msg_missing" },
+      "request": { "method": "GET", "path": "/api/messages/msg_missing" },
+      "response": { "status": 404, "body": { "error": "not found" } },
+      "error": { "status": 404, "message": "not found" }
+    },
+    {
+      "name": "send_upstream_error",
+      "method": "send",
+      "args": { "from": "hello@app.mailkite.dev", "to": "ada@example.com", "subject": "Hi", "text": "x" },
+      "request": {
+        "method": "POST",
+        "path": "/v1/send",
+        "bodySchema": "send-request",
+        "body": { "from": "hello@app.mailkite.dev", "to": "ada@example.com", "subject": "Hi", "text": "x" }
+      },
+      "response": { "status": 502, "body": { "error": "an upstream send failed" } },
+      "error": { "status": 502, "message": "an upstream send failed" }
+    },
+    {
+      "name": "verify_webhook_valid",
+      "method": "verifyWebhook",
+      "local": true,
+      "argsSchema": "verify-webhook-request",
+      "args": {
+        "signature": "t=1750000000000,v1=3d790f831e170ddba4d001f27532bf2c1fc68ebed52eef72fe453dfa1196b03c",
+        "payload": "{\"type\":\"email.received\",\"id\":\"evt_123\",\"message\":\"It works.\"}",
+        "secret": "whsec_mailkite_test",
+        "toleranceMs": 0
+      },
+      "result": true
+    },
+    {
+      "name": "verify_webhook_tampered_body",
+      "method": "verifyWebhook",
+      "local": true,
+      "argsSchema": "verify-webhook-request",
+      "args": {
+        "signature": "t=1750000000000,v1=3d790f831e170ddba4d001f27532bf2c1fc68ebed52eef72fe453dfa1196b03c",
+        "payload": "{\"type\":\"email.received\",\"id\":\"evt_123\",\"message\":\"It WORKS.\"}",
+        "secret": "whsec_mailkite_test",
+        "toleranceMs": 0
+      },
+      "result": false
+    },
+    {
+      "name": "verify_webhook_wrong_secret",
+      "method": "verifyWebhook",
+      "local": true,
+      "argsSchema": "verify-webhook-request",
+      "args": {
+        "signature": "t=1750000000000,v1=3d790f831e170ddba4d001f27532bf2c1fc68ebed52eef72fe453dfa1196b03c",
+        "payload": "{\"type\":\"email.received\",\"id\":\"evt_123\",\"message\":\"It works.\"}",
+        "secret": "whsec_wrong",
+        "toleranceMs": 0
+      },
+      "result": false
+    },
+    {
+      "name": "verify_webhook_malformed_header",
+      "method": "verifyWebhook",
+      "local": true,
+      "argsSchema": "verify-webhook-request",
+      "args": {
+        "signature": "not-a-valid-signature",
+        "payload": "{\"type\":\"email.received\",\"id\":\"evt_123\",\"message\":\"It works.\"}",
+        "secret": "whsec_mailkite_test",
+        "toleranceMs": 0
+      },
+      "result": false
+    }
+  ]
+}

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

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

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

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

package/spec/schemas/send-request.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "send-request",
+  "title": "Send request body",
+  "type": "object",
+  "required": ["from", "to", "subject"],
+  "additionalProperties": false,
+  "properties": {
+    "from": { "type": "string", "description": "An address on a verified domain." },
+    "to": {
+      "description": "One recipient or a list.",
+      "oneOf": [
+        { "type": "string" },
+        { "type": "array", "items": { "type": "string" }, "minItems": 1 }
+      ]
+    },
+    "subject": { "type": "string" },
+    "html": { "type": "string" },
+    "text": { "type": "string" },
+    "cc": { "oneOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }] },
+    "bcc": { "oneOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }] },
+    "replyTo": { "type": "string" },
+    "inReplyTo": { "type": "string" },
+    "attachments": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["filename"],
+        "properties": {
+          "filename": { "type": "string" },
+          "url": { "type": "string" },
+          "content": { "type": "string" },
+          "contentType": { "type": "string" }
+        }
+      }
+    }
+  }
+}

package/spec/schemas/send-response.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "send-response",
+  "title": "Send response body",
+  "type": "object",
+  "required": ["id", "status"],
+  "properties": {
+    "id": { "type": "string" },
+    "status": { "type": "string" }
+  }
+}

package/spec/schemas/set-webhook-request.json

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

package/spec/schemas/verify-webhook-request.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "verify-webhook-request",
+  "title": "Verify webhook request",
+  "description": "Inputs to verifyWebhook — a local HMAC check, no API call.",
+  "type": "object",
+  "required": ["payload", "signature", "secret"],
+  "additionalProperties": false,
+  "properties": {
+    "payload": {
+      "type": "string",
+      "description": "The raw, unparsed webhook request body — the exact bytes you received."
+    },
+    "signature": {
+      "type": "string",
+      "description": "The `x-mailkite-signature` header value, e.g. `t=1750000000000,v1=4f1a9c…`."
+    },
+    "secret": {
+      "type": "string",
+      "description": "Your webhook signing secret (from the dashboard)."
+    },
+    "toleranceMs": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Reject events whose timestamp is more than this many milliseconds old, to block replays. Defaults to 300000 (5 minutes). Pass 0 to disable the freshness check."
+    }
+  }
+}