{"_id":"@mailsai/sdk","_rev":"7-ff615bd9a2d0f06d8ee1fa64d528577d","name":"@mailsai/sdk","dist-tags":{"latest":"0.2.4"},"versions":{"0.1.0":{"name":"@mailsai/sdk","version":"0.1.0","keywords":["email","ai","agent","mcp","mails.ai","agent-identity","sender-reputation","agent-email","prompt-injection","smtp","transactional-email"],"license":"MIT","_id":"@mailsai/sdk@0.1.0","maintainers":[{"name":"mailsai","email":"richard@mails.ai"}],"homepage":"https://mails.ai","bugs":{"url":"https://github.com/RolloutsAI/mails-api/issues"},"dist":{"shasum":"77d693e7902a3d82a09c8bd1b8dc243cb259b4b6","tarball":"https://registry.npmjs.org/@mailsai/sdk/-/sdk-0.1.0.tgz","fileCount":6,"integrity":"sha512-k5VmHM78+CLkT38v/KU9bb61FMOpnuMV9AjDgObB44P5WQXNfd3Co9f4y1olZD+aDKAamh2ZC1ugpOtQcMR+Vg==","signatures":[{"sig":"MEYCIQDa15f7Y04fGzwlMAtcFM17wJvP9lJBPm+6tktGBVt3UgIhAKwiNiSDqmZ6xUU2PgtV657K6Izrv4RIZPTdRgzzLCf4","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":66223},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"9a28c57fdcbdd17b135d26bda5e25dc476b0c4c3","scripts":{"build":"tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"mailsai","email":"richard@mails.ai"},"repository":{"url":"git+https://github.com/RolloutsAI/mails-api.git","type":"git","directory":"packages/sdk"},"_npmVersion":"10.9.4","description":"Email API for AI agents — TypeScript SDK. Per-agent email addresses on your domain, per-agent reputation, and prompt-injection scanning on every inbound. Send, receive structured inbound replies, and identify agents via REST. Intent + entity extraction is","directories":{},"_nodeVersion":"22.22.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5","@types/node":"^20"},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.1.0_1784538375786_0.049177256956789206","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@mailsai/sdk","version":"0.1.1","keywords":["email","ai","agent","mcp","mails.ai","agent-identity","sender-reputation","agent-email","prompt-injection","smtp","transactional-email"],"license":"MIT","_id":"@mailsai/sdk@0.1.1","maintainers":[{"name":"mailsai","email":"richard@mails.ai"}],"homepage":"https://mails.ai","bugs":{"url":"https://github.com/RolloutsAI/mails-api/issues"},"dist":{"shasum":"4e739871e1a4d37ee322a44dd35bb9d507ff7a21","tarball":"https://registry.npmjs.org/@mailsai/sdk/-/sdk-0.1.1.tgz","fileCount":6,"integrity":"sha512-YZQ9Q2w4sB3QxmB3EG1drCIaR8dvSm7j3MaKtPrzZlgYnn5Eky2d4xPJeoBb3gNnIdEVa407qe4PtOq01vWjVQ==","signatures":[{"sig":"MEUCIFyAwka1ngfmQimrXok2t3wcgMrARBpfR6JYZOIfAC18AiEAt1OLTEg3GZS9RV0RddBbKYOtYSck4VVR8ce1dupQ1jo=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":67152},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"99107ccc424a9403c7fb6fd1b7dd9f10118e82d5","scripts":{"build":"tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"mailsai","email":"richard@mails.ai"},"repository":{"url":"git+https://github.com/RolloutsAI/mails-api.git","type":"git","directory":"packages/sdk"},"_npmVersion":"11.11.0","description":"Email API for AI agents — TypeScript SDK. Per-agent email addresses on your domain, per-agent reputation, and prompt-injection scanning on every inbound. Send, receive structured inbound replies, and identify agents via REST. Intent + entity extraction is","directories":{},"_nodeVersion":"25.8.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5","@types/node":"^20"},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.1.1_1785243808168_0.5107557536795833","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@mailsai/sdk","version":"0.2.0","keywords":["email","ai","agent","mcp","mails.ai","agent-identity","sender-reputation","agent-email","prompt-injection","smtp","transactional-email"],"license":"MIT","_id":"@mailsai/sdk@0.2.0","maintainers":[{"name":"mailsai","email":"richard@mails.ai"}],"homepage":"https://mails.ai","bugs":{"url":"https://github.com/RolloutsAI/mailsai/issues"},"dist":{"shasum":"10d89ddfddb5f52bc829a55d572c663221d5c88b","tarball":"https://registry.npmjs.org/@mailsai/sdk/-/sdk-0.2.0.tgz","fileCount":6,"integrity":"sha512-w3YyF7QjyKnx9AgNaPxHIGHNpNfF1bLJbbOx4YXc3o9/Ah8GgSd/hQu2KfdPcLNu9T6eyWYVNR+V9X4SQduYGQ==","signatures":[{"sig":"MEQCIENBdT8qnIptzxgJ8dslZdLP3N7kzbFx+utOdOt/+lcOAiBKB/lpBmqCC4hwcEtpNw5G2ZkcYvWTLc6mdWM/qeWnfA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":71807},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"a853cb6d5cf4924c56b9d922516b50bb52a3b6d1","scripts":{"build":"tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"mailsai","email":"richard@mails.ai"},"repository":{"url":"git+https://github.com/RolloutsAI/mailsai.git","type":"git","directory":"packages/sdk"},"_npmVersion":"10.9.4","description":"Email API for AI agents — TypeScript SDK. Per-agent email addresses on your domain, per-agent reputation, and prompt-injection scanning on every inbound. Send, receive structured inbound replies, and identify agents via REST. Intent + entity extraction is","directories":{},"_nodeVersion":"22.22.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5","@types/node":"^20"},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.2.0_1786346719748_0.9178292574361793","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"@mailsai/sdk","version":"0.2.1","keywords":["email","ai","agent","mcp","mails.ai","agent-identity","sender-reputation","agent-email","prompt-injection","smtp","transactional-email"],"license":"MIT","_id":"@mailsai/sdk@0.2.1","maintainers":[{"name":"mailsai","email":"richard@mails.ai"}],"homepage":"https://mails.ai","bugs":{"url":"https://github.com/RolloutsAI/mailsai/issues"},"dist":{"shasum":"7251f7f365b27a49c729d5700a7473fd6c606509","tarball":"https://registry.npmjs.org/@mailsai/sdk/-/sdk-0.2.1.tgz","fileCount":6,"integrity":"sha512-cM8UcL0vVzGm+nO+LctlyXuExwqst0chXpH1DKe1JrW7lQ713bpPKWpZcTSwsgPpRkCoUExjZLqs0zrH+fpJ1A==","signatures":[{"sig":"MEUCIQD7f7zBWLPKd9Mhb/a71NxqVYCvDKPQ+1+TbU3eePCMqAIgW11cKy2Arf8q15qXtoE76Jr2ToAgG8oh238x/uQ3qiM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":72184},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"d82b375b5abe6a080b8eff119136bcc869c3fd3e","scripts":{"build":"tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"mailsai","email":"richard@mails.ai"},"repository":{"url":"git+https://github.com/RolloutsAI/mailsai.git","type":"git","directory":"packages/sdk"},"_npmVersion":"10.9.4","description":"Email API for AI agents — TypeScript SDK. Per-agent email addresses on your domain, per-agent reputation, and prompt-injection scanning on every inbound. Send, receive structured inbound replies, and identify agents via REST. Intent + entity extraction is","directories":{},"_nodeVersion":"22.22.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5","@types/node":"^20"},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.2.1_1786420943676_0.026153725911799874","host":"s3://npm-registry-packages-npm-production"}},"0.2.2":{"name":"@mailsai/sdk","version":"0.2.2","keywords":["email","ai","agent","mcp","mails.ai","agent-identity","sender-reputation","agent-email","prompt-injection","smtp","transactional-email"],"license":"MIT","_id":"@mailsai/sdk@0.2.2","maintainers":[{"name":"mailsai","email":"richard@mails.ai"}],"homepage":"https://mails.ai","bugs":{"url":"https://github.com/RolloutsAI/mailsai/issues"},"dist":{"shasum":"a17b463cee16d1acd548c08fab211cadef48feb4","tarball":"https://registry.npmjs.org/@mailsai/sdk/-/sdk-0.2.2.tgz","fileCount":6,"integrity":"sha512-A+0HsSa513w3yAzKRkaC279YpHDGOe5R2/A4Rhl/dpLw943zujkOESn/fuztPp1GYe/VMw611Asq2qcR7GfT2w==","signatures":[{"sig":"MEUCIQDiGBXP6ktIaYGtFrL4g4TsLzxKeaWXZELxKm3LenlWzgIgU37QCPG3HmY1NRJEHMdmKh6c81dxeyVOy156inpkuF8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":72692},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"d0c8a7fbe9190f61422cb08e9bf2e638744f9647","scripts":{"build":"tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"mailsai","email":"richard@mails.ai"},"repository":{"url":"git+https://github.com/RolloutsAI/mailsai.git","type":"git","directory":"packages/sdk"},"_npmVersion":"11.11.0","description":"Email API for AI agents — TypeScript SDK. Per-agent email addresses on your domain, per-agent reputation, and prompt-injection scanning on every inbound. Send, receive structured inbound replies, and identify agents via REST. Intent + entity extraction is","directories":{},"_nodeVersion":"25.8.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5","@types/node":"^20"},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.2.2_1786690344517_0.3470849920472412","host":"s3://npm-registry-packages-npm-production"}},"0.2.3":{"name":"@mailsai/sdk","version":"0.2.3","keywords":["email","ai","agent","mcp","mails.ai","agent-identity","sender-reputation","agent-email","prompt-injection","smtp","transactional-email"],"license":"MIT","_id":"@mailsai/sdk@0.2.3","maintainers":[{"name":"mailsai","email":"richard@mails.ai"}],"homepage":"https://mails.ai","bugs":{"url":"https://github.com/RolloutsAI/mailsai/issues"},"dist":{"shasum":"a7f3cbc8f0e160db4bc849c0f6d1a364603d6002","tarball":"https://registry.npmjs.org/@mailsai/sdk/-/sdk-0.2.3.tgz","fileCount":6,"integrity":"sha512-x3u/Kkc58HPr0Cf7AEUckOrCy8MJ/pVkB5qh0+sX62pXjQWxSdKMmbfzPLKMQGaKDqaRYhViz5tjBX1/ERkPgQ==","signatures":[{"sig":"MEQCIFy1NWhkVueZpXwU5m56XXz9JCOLdQt404acD/VSeSdWAiAh2o6iPu+m5VeWfSHJ4lw+pUYR840pRgnsaponntwqZQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":73882},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"d30467f2a92b243cfe4800d634db2b805a8963e8","scripts":{"build":"tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"mailsai","email":"richard@mails.ai"},"repository":{"url":"git+https://github.com/RolloutsAI/mailsai.git","type":"git","directory":"packages/sdk"},"_npmVersion":"11.11.0","description":"Email API for AI agents — TypeScript SDK. Per-agent email addresses on your domain, per-agent reputation, and prompt-injection scanning on every inbound. Send, receive structured inbound replies, and identify agents via REST. Intent + entity extraction is","directories":{},"_nodeVersion":"25.8.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5","@types/node":"^20"},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.2.3_1786690671659_0.6806704406146225","host":"s3://npm-registry-packages-npm-production"}},"0.2.4":{"_id":"@mailsai/sdk@0.2.4","bugs":{"url":"https://mails.ai/contact"},"dist":{"shasum":"77c53c9edccd6c69fc89c77256d3c4506a04aa3a","tarball":"https://registry.npmjs.org/@mailsai/sdk/-/sdk-0.2.4.tgz","fileCount":6,"integrity":"sha512-z2mAlfjw/nYitYqRCBCcpZIypOKlaiDSuzWoomNm2Gw2xnnzIcVxQbPy7wRZT9zeBjzgr8VMxt0qJoI/XXxJJA==","signatures":[{"sig":"MEYCIQC34dtMQSf6AKQAvhSBTCi4o+uS/ARWANLzDncLoLcUWQIhALtXU2n91oHbkvo1rcdGNa/OigWs5QUV4XiVBThrZ4IW","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDz/BQDF0Cki9SsQzXi7W6zGI2mIm0y6o3VFfigR9CfaAIgDp0s5g5M/zjN6NEWaLGz0K7OoDJGOn0ZQb2F2SchMgE="}],"unpackedSize":73722},"main":"./dist/index.js","name":"@mailsai/sdk","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"96d9b3209151df2a3a02270129a365a8c12d3d7a","license":"MIT","scripts":{"build":"tsc","prepublishOnly":"npm run build"},"version":"0.2.4","_npmUser":{"name":"mailsai","email":"richard@mails.ai"},"homepage":"https://mails.ai","keywords":["email","ai","agent","mcp","mails.ai","agent-identity","sender-reputation","agent-email","prompt-injection","smtp","transactional-email"],"_npmVersion":"10.9.4","description":"Email API for AI agents — TypeScript SDK. Per-agent email addresses on your domain, per-agent reputation, and prompt-injection scanning on every inbound. Send, receive structured inbound replies, and identify agents via REST. Intent + entity extraction is","directories":{},"maintainers":[{"name":"mailsai","email":"richard@mails.ai"}],"_nodeVersion":"22.22.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5","@types/node":"^20"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_0.2.4_1788509418273_0.4548527704599188"}}},"time":{"created":"2026-07-20T09:06:15.592Z","modified":"2026-09-04T08:10:18.515Z","0.1.0":"2026-07-20T09:06:15.924Z","0.1.1":"2026-07-28T13:03:28.317Z","0.2.0":"2026-08-10T07:25:19.892Z","0.2.1":"2026-08-11T04:02:23.903Z","0.2.2":"2026-08-14T06:52:24.670Z","0.2.3":"2026-08-14T06:57:51.797Z","0.2.4":"2026-09-04T08:10:18.367Z"},"bugs":{"url":"https://mails.ai/contact"},"license":"MIT","homepage":"https://mails.ai","keywords":["email","ai","agent","mcp","mails.ai","agent-identity","sender-reputation","agent-email","prompt-injection","smtp","transactional-email"],"description":"Email API for AI agents — TypeScript SDK. Per-agent email addresses on your domain, per-agent reputation, and prompt-injection scanning on every inbound. Send, receive structured inbound replies, and identify agents via REST. Intent + entity extraction is","maintainers":[{"name":"mailsai","email":"richard@mails.ai"}],"readme":"# @mailsai/sdk\n\nEmail API for AI agents — TypeScript / JavaScript SDK.\n\nPer-agent email addresses on your domain, per-agent reputation, and prompt-injection scanning on every inbound. Your agent reads the reply and decides what to say — intent + entity extraction is opt-in.\n\n```bash\nnpm install @mailsai/sdk\n```\n\nThe package is **ESM-only** — use `import`, not `require()`. In a plain `npm init -y`\nproject, add `\"type\": \"module\"` to your package.json first.\n\n## Quick start\n\nCreate the agent once (this mints its inbox address), then send from it. Skipping the\ncreate step is the most common first-run error — `mails.agent(\"sarah\")` only references\nan agent, it does not create one, so sending returns `404 agent_not_found`.\n\n```ts\nimport { mails, createClient } from \"@mailsai/sdk\";\n\n// One-time setup: create the agent. It gets sarah@<your-workspace>.mails.ai\nconst client = createClient(); // reads MAILS_API_KEY from env\nawait client.agents.create(\"sarah\");\n\n// Reads MAILS_API_KEY from env (or pass via mails.agent(name, { apiKey: \"mk_live_...\" }))\nconst sarah = mails.agent(\"sarah\");\n\n// Send transactional mail — something the recipient asked for. mails.ai firewalls\n// cold outreach: a \"just reaching out / looking forward to talking\" body is rejected\n// with 422 cold_email_prohibited, by design.\nawait sarah.send({\n  to: \"user@example.com\",\n  subject: \"Your password reset code\",\n  body: \"Your verification code is 481920. It expires in 10 minutes.\",\n});\n\nsarah.onReply((reply) => {\n  // Always present — the delivery + security + identity layer:\n  // reply.injection_score   → 0.02  (six-category prompt-injection scan)\n  // reply.sender_reputation → 0.91  (per-agent reputation)\n  //\n  // Present only when classification is enabled (opt-in, +$0.003/inbound):\n  // reply.intent            → \"schedule_demo\" | \"ask_question\" | \"decline\" | …\n  // reply.entities          → { date: \"2026-05-16\", time: \"10:00\", … }\n  // reply.urgency           → 0.8\n  //\n  // Your agent reads the reply and decides what to send next.\n  console.log(reply.injection_score, reply.sender_reputation);\n});\n```\n\n## Lower-level client\n\nFor full access to all resources (threads, drafts, events, agents, suppression, webhooks, reputation, billing, logs):\n\n```ts\nimport { createClient } from \"@mailsai/sdk\";\n\nconst client = createClient({ apiKey: process.env.MAILS_API_KEY! });\n\n// Send via any agent\nawait client.send(\"sarah\", { to: \"lead@example.com\", subject: \"Demo\", body: \"…\" });\n\n// Or call resources directly\nconst threads = await client.threads.list({ agent_id: \"agent_abc123\" });\nconst usage = await client.billing.usage();\nconst reputation = await client.reputation.get(\"agent_abc123\");\n\n// SSE stream of inbound events\nconst ctrl = client.events.stream({\n  event_types: [\"reply.received\", \"message.delivered\"],\n  onEvent: (e) => console.log(e.type, e),\n  onError: (err) => console.error(err),\n});\n// …later\nctrl.abort();\n```\n\n## Webhook verification\n\n```ts\nimport { mails } from \"@mailsai/sdk\";\n\n// In your webhook handler:\nconst event = mails.webhooks.verify(\n  rawBody,\n  req.headers[\"x-mails-signature\"]!,\n  process.env.MAILS_WEBHOOK_SECRET!\n);\nif (!event) return new Response(\"invalid signature\", { status: 400 });\n// event is the verified inbound event payload\n```\n\n## Configuration\n\n| Option | Env var | Default |\n|---|---|---|\n| `apiKey` | `MAILS_API_KEY` | none — required |\n| `baseUrl` | `MAILS_BASE_URL` | `https://api.mails.ai` |\n| `fetch` | — | global `fetch` |\n\n## Idempotency\n\n```ts\nawait sarah.send({\n  to: \"lead@example.com\",\n  subject: \"Demo\",\n  body: \"…\",\n  idempotency_key: \"weekly-followup-2026-05-14-lead-123\",\n});\n```\n\nReplays within 24 hours return the original response with `Idempotent-Replay: true` header.\n\n## Errors\n\nAll API errors throw `MailsError`:\n\n```ts\nimport { MailsError } from \"@mailsai/sdk\";\n\ntry {\n  await sarah.send({ to: \"blocked@example.com\", subject: \"…\", body: \"…\" });\n} catch (err) {\n  if (err instanceof MailsError) {\n    console.error(err.type, err.code, err.message, err.status, err.requestId);\n  }\n}\n```\n\n## Documentation\n\n- Full docs: [mails.ai/docs](https://mails.ai/docs)\n- API reference: [mails.ai/docs/api](https://mails.ai/docs)\n- Source: [github.com/RolloutsAI/mailsai](https://github.com/RolloutsAI/mailsai/tree/main/packages/sdk)\n\n## License\n\nMIT\n","readmeFilename":"README.md"}