@mailkite/mcp 0.3.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mailkite/mcp",
-  "version": "0.3.0",
+  "version": "0.5.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": {
@@ -41,6 +41,6 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "ajv": "^8.17.1",
-    "mailkite": "^0.3.0"
+    "mailkite": "^0.5.0"
   }
 }

package/spec/api.json

@@ -1,6 +1,6 @@
 {
   "name": "mailkite",
-  "version": "0.3.0",
+  "version": "0.5.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": {
@@ -12,167 +12,409 @@
     {
       "name": "send",
       "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" }],
+      "http": {
+        "method": "POST",
+        "path": "/v1/send"
+      },
+      "args": [
+        {
+          "name": "message",
+          "in": "body",
+          "schema": "send-request"
+        }
+      ],
       "returns": "send-response"
     },
+    {
+      "name": "uploadAttachment",
+      "summary": "Upload a file to MailKite storage and get back a secure, time-limited URL. Reference the returned `url` as an attachment in send() (`{ filename, url }`) or link it inline in your HTML — instead of base64-inlining large files on every send. `content` is the file bytes, base64-encoded; `retentionDays` (7/30/90/365, default 7) sets how long the file and URL live.",
+      "http": {
+        "method": "POST",
+        "path": "/v1/attachments"
+      },
+      "args": [
+        {
+          "name": "file",
+          "in": "body",
+          "schema": "upload-attachment-request"
+        }
+      ],
+      "returns": "upload-attachment-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" },
+      "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" },
+      "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" }],
+      "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" }],
+      "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.",
-      "http": { "method": "GET", "path": "/api/domains" },
+      "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" }],
+      "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" }],
+      "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" }],
+      "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" }],
+      "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" },
+      "http": {
+        "method": "PUT",
+        "path": "/api/domains/{id}/webhook"
+      },
       "args": [
-        { "name": "id", "in": "path" },
-        { "name": "body", "in": "body", "schema": "set-webhook-request" }
+        {
+          "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" }],
+      "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" }],
+      "http": {
+        "method": "POST",
+        "path": "/api/domains/{id}/webhook/test"
+      },
+      "args": [
+        {
+          "name": "id",
+          "in": "path"
+        }
+      ],
       "returns": "any"
     },
     {
       "name": "checkDomainAvailability",
       "summary": "Check whether a domain is available to register, and at what price. Read-only — no charge.",
-      "http": { "method": "GET", "path": "/api/domains/register/check" },
-      "args": [{ "name": "domain", "in": "query" }],
+      "http": {
+        "method": "GET",
+        "path": "/api/domains/register/check"
+      },
+      "args": [
+        {
+          "name": "domain",
+          "in": "query"
+        }
+      ],
       "returns": "any"
     },
     {
       "name": "registerDomain",
       "summary": "Register (buy) a domain on the customer's behalf; provisions mail DNS and adds it to the account in one call. Charges the registrar.",
-      "http": { "method": "POST", "path": "/api/domains/register" },
-      "args": [{ "name": "body", "in": "body", "schema": "register-domain-request" }],
+      "http": {
+        "method": "POST",
+        "path": "/api/domains/register"
+      },
+      "args": [
+        {
+          "name": "body",
+          "in": "body",
+          "schema": "register-domain-request"
+        }
+      ],
       "returns": "any",
       "agentConfirm": true
     },
     {
       "name": "listRoutes",
       "summary": "List inbound routing rules.",
-      "http": { "method": "GET", "path": "/api/routes" },
+      "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" }],
+      "http": {
+        "method": "POST",
+        "path": "/api/routes"
+      },
+      "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" }],
+      "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" }],
+      "http": {
+        "method": "POST",
+        "path": "/v1/route"
+      },
+      "args": [
+        {
+          "name": "message",
+          "in": "body",
+          "schema": "route-message-request"
+        }
+      ],
       "returns": "route-response"
     },
     {
       "name": "listMessages",
       "summary": "List stored messages.",
-      "http": { "method": "GET", "path": "/api/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" }],
+      "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" }],
+      "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" }],
+      "args": [
+        {
+          "name": "body",
+          "in": "body",
+          "schema": "verify-webhook-request"
+        }
+      ],
       "returns": "boolean"
+    },
+    {
+      "name": "replyOk",
+      "summary": "The acknowledgement body a webhook consumer returns to confirm it processed the event — the string `{\"status\":\"ok\"}`. Send it with a 2xx when the route is in `ack` mode (or always — it's harmless in `lenient` mode). Local, no network call.",
+      "local": true,
+      "args": [],
+      "returns": "string",
+      "sdkOnly": true
+    },
+    {
+      "name": "replySpam",
+      "summary": "Control-mode reply a webhook consumer returns to tell MailKite to mark the message as spam — the string `{\"status\":\"spam\"}`. Local, no network call.",
+      "local": true,
+      "args": [],
+      "returns": "string",
+      "sdkOnly": true
+    },
+    {
+      "name": "replyDrop",
+      "summary": "Control-mode reply a webhook consumer returns to tell MailKite to drop (discard) the message — the string `{\"status\":\"drop\"}`. Local, no network call.",
+      "local": true,
+      "args": [],
+      "returns": "string",
+      "sdkOnly": true
+    },
+    {
+      "name": "replyBlockSender",
+      "summary": "Control-mode reply a webhook consumer returns to tell MailKite to block the sender — the string `{\"status\":\"ok\",\"actions\":[{\"type\":\"block-sender\"}]}`. Local, no network call.",
+      "local": true,
+      "args": [],
+      "returns": "string",
+      "sdkOnly": true
+    },
+    {
+      "name": "encrypt",
+      "summary": "Encrypt a UTF-8 string to a domain's RSA public key (SPKI/PEM), returning the at-rest envelope JSON (`{v,keyAlg,fp,enc,iv,wrappedKey,ciphertext}`). Hybrid scheme: a fresh AES-256-GCM content key wrapped with RSA-OAEP(SHA-256) — byte-compatible with MailKite's own at-rest encryption. Local, no network call.",
+      "local": true,
+      "args": [
+        {
+          "name": "body",
+          "in": "body",
+          "schema": "encrypt-request"
+        }
+      ],
+      "returns": "string",
+      "sdkOnly": true
+    },
+    {
+      "name": "decrypt",
+      "summary": "Decrypt a MailKite at-rest envelope JSON with your RSA private key (PKCS8/PEM), returning the original UTF-8 string. Reverses `encrypt` / MailKite's at-rest encryption (RSA-OAEP(SHA-256) unwrap → AES-256-GCM open). Local, no network call.",
+      "local": true,
+      "args": [
+        {
+          "name": "body",
+          "in": "body",
+          "schema": "decrypt-request"
+        }
+      ],
+      "returns": "string",
+      "sdkOnly": true
     }
   ]
 }