Samva

Packages, examples, cookbooks, and agent plugins for building on Samva, email and WhatsApp for AI agents.

Samva gives an agent its own email address and WhatsApp number. It sends and receives on both through one API, hosted MCP, or the CLI, gets every reply back threaded to its conversation, and works under rules that hold what a person should approve. Use this repository to send transactional email, connect auth email flows, work with templates, receive replies and delivery events as signed webhooks, and give an agent its own mailbox. Ask questions about the code on DeepWiki.

Start here

From an MCP client. Samva's hosted MCP server is at https://mcp.samva.dev and signs in with OAuth. In Claude Code:

claude mcp add --transport http samva https://mcp.samva.dev

Setup guides: Claude Code, Codex, Cursor, and opencode.

From code. Create a mailbox on a hosted address, which needs no DNS setup, and send from it:

import { createClient } from "samva";

const samva = createClient({ apiKey: process.env.SAMVA_API_KEY! });

const mailbox = await samva.mailboxes.create({
  endpoint: { channel: "email", address: "support@acme.samva.email" },
  name: "Support",
});

await samva.mailboxes.sendMessage({
  id: mailbox.id,
  to: ["customer@example.com"],
  subject: "Your support request",
  text: "We are looking into your request.",
});

From a terminal.

npm install -g @samva/cli
samva login
samva org use <slug>   # `samva org list` shows your organizations
samva mailboxes create --address support@acme.samva.email --name Support
samva mailboxes events mbx_...

Replies come back as signed webhooks or over the mailbox event stream. The mailbox-agent example is a complete agent that follows that stream and replies in approval mode, and Give an agent an inbox is the full tutorial. The free plan needs no card and includes one mailbox; WhatsApp is on paid plans.

Structure

• packages/* — package integrations (@samva/*).
• examples/* — complete, runnable example apps.
• cookbooks/*.md — documentation-first, copy-pasteable recipes.
• plugins/* — coding-agent plugins and public documentation.

While Samva is 0.x, the maintained integrations support only the current SDK minor: 0.43. Workspace packages require samva@^0.43.0 as a peer and test against 0.43.0. Examples use samva@^0.43.0; copyable external import maps pin samva@0.43.0.

Package integrations

• @samva/better-auth — Better Auth email callbacks powered by Samva.
• @samva/email-sdk — Provider-owned Samva community adapter for Email SDK.

Agent plugins

• samva — OpenAI Codex and Cursor packaging for the canonical hosted MCP server and Samva agent skill.
• Samva in ChatGPT — the published ChatGPT plugin is a separate listing from the Codex and Cursor package; the guide covers connecting one organization and a read-only first check.

Cookbooks

Agents and mailboxes:

• Mailboxes
• Inbound email replies

Agent frameworks:

• Claude Agent SDK
• Vercel AI SDK
• Eve
• OpenAI Agents SDK
• LangGraph

Frameworks and auth:

• Astro
• Auth.js
• Better Auth
• Clerk
• Effect SDK
• Email SDK
• Hono on Cloudflare Workers
• Next.js
• Prisma
• Supabase Auth
• SvelteKit
• TanStack Start

Templates:

• React Email
• TSX templates

Integrations land as individual pull requests. See CONTRIBUTING.md to propose or build one.

Examples

Agents and mailboxes:

• mailbox-agent — an agent that follows a mailbox event stream and answers email and WhatsApp in approval mode, plus the same behavior as an @samva/mailbox webhook extension.
• mailbox-agent-claude — an agent that asks Claude to draft each reply to a mailbox's email and WhatsApp messages and sends it held for a person's approval.
• mailbox-agent-claude-agent-sdk — the same agent on the Claude Agent SDK, replying through two tools.
• mailbox-agent-ai-sdk — the same agent on the Vercel AI SDK.
• mailbox-agent-eve — the same agent on Eve, with a channel that starts one run per message.
• mailbox-agent-openai-agents — the same agent on the OpenAI Agents SDK.
• mailbox-agent-langgraph — the same agent on LangGraph.
• inbound-email-replies — receives an inbound reply, verifies the signed webhook, and answers in-thread.

Frameworks, auth, and templates:

• astro-email — Astro Action and JSON endpoint on Cloudflare Workers.
• better-auth-nextjs — Better Auth callbacks in a Next.js App Router application.
• clerk-webhook — Clerk webhook verification and transactional email in Next.js.
• effect-sdk — Email sends through the samva/effect SDK entrypoint.
• email-sdk — Email SDK sends through the provider-owned Samva community adapter.
• hono-cloudflare-workers — Hono Worker with a JSON email endpoint.
• nextjs-transactional — App Router contact form plus /api/send route handler using the Samva SDK.
• react-email-samva — React Email rendering and delivery through Samva.
• supabase-auth-hook — Supabase Auth Send Email Hook implemented as an Edge Function.
• sveltekit-transactional — SvelteKit form action and raw email endpoint.
• tanstack-start-transactional — TanStack Start server function and server route.
• tsx-template-samva — a defineTemplate email project: check, render, preview, and publish with the Samva CLI.

Getting started

This is a Bun + Turborepo monorepo.

bun install
bun run build
bun run typecheck
bun run test
bun run lint
bun run format:check

Related open source

• SML — the markup, Vite plugin, and editor behind Samva's TSX templates.
• DomainKit — Samva sets up customer domains with DomainKit. See how it works.

Contributing

Contributions are welcome — see CONTRIBUTING.md for local setup, package conventions, and how to propose a new integration. Maintainers use the Tegami release flow for package versions, changelogs, npm publication, tags, and GitHub Releases. GitHub Actions publishes; merging the Version Packages pull request is the human gate.

Security

To report a vulnerability, see SECURITY.md. Please do not file public issues for security reports.

License

MIT © Arya Labs, Inc.