samva10 KB
View saved version →
---
name: samva
description: >-
Integrate and operate Samva email and WhatsApp across the Promise and Effect
TypeScript SDKs, REST API, CLI, hosted MCP server, dashboard, and TSX
template editor. Use for sending and tracking email and WhatsApp messages,
domains and senders, inbound receiving, webhooks, templates, WhatsApp's
24-hour service window and setup links, schedules, campaigns, usage,
readiness, authentication, mailboxes for agents (threads, replies, approval
sends, quarantine, event streams, extensions), or choosing the right Samva
surface. Triggers on samva, samva.dev, the `samva` package, `@samva/cli`,
`samva/mailbox`, mcp.samva.dev, SAMVA_API_KEY, agent mailbox, Samva
WhatsApp, SML, Samva Markup Language, and template editor agent.
metadata:
version: 0.4.0
---
# Samva
Use Samva's organization-scoped email and WhatsApp surfaces for transactional sends,
templates, scheduled email, campaigns, inbound receiving, webhooks, mailboxes for agents, and
operational checks.
## Choose the surface
```text
What is the intent?
├─ Add Samva to async/await TypeScript code → Promise SDK (`samva` or `samva/promises`)
├─ Add Samva to an Effect application → Effect SDK (`samva/effect`)
├─ Call Samva from another runtime → REST (`https://api.samva.dev/v1`)
├─ Run or script terminal workflows → CLI (`@samva/cli`)
├─ Give an AI agent live Samva tools → hosted MCP (`https://mcp.samva.dev`)
├─ Configure or inspect resources visually → dashboard (`https://samva.dev`)
├─ Give an agent its own inbox to read and reply → mailbox (`samva.mailboxes`, `samva mailboxes`)
├─ Send or answer on WhatsApp → WhatsApp reference (`channel: "whatsapp"`)
├─ React to mailbox events with code Samva runs → mailbox extension (`samva/mailbox`)
└─ Author or repair a TSX email template → template authoring reference
```
Pick a mailbox when mail is a conversation: an agent or person reads threads and replies in
place. Pick a transactional send (`email.send`) for one-way mail from your application, and
inbound webhooks when your application only needs to be told that mail arrived on a verified
domain.
| Surface | Best for | Authentication |
| ----------- | ------------------------------------------ | -------------------------------- |
| Promise SDK | TypeScript with Promises | API key or OAuth bearer |
| Effect SDK | Native typed Effect programs | API key or OAuth bearer |
| REST | Non-TypeScript runtimes and direct HTTP | API key or OAuth bearer |
| CLI | Terminal automation and operator workflows | `SAMVA_API_KEY` or `samva login` |
| Hosted MCP | Agents taking live actions | API key or OAuth |
| Dashboard | Visual setup, inspection, and billing | Browser session |
Read only the reference needed for the selected surface:
- [SDK and REST](references/sdk.md): Promise SDK, Effect SDK, and direct HTTP.
- [CLI](references/cli.md): installation, authentication, and shipped command families.
- [Hosted MCP](references/mcp.md): endpoint, public tool families, resources, and safe retries.
- [Mailboxes](references/mailbox-extensions.md): approval sends, quarantine, the event stream, and
authoring extensions with `samva/mailbox`. The SDK, CLI, and MCP references cover the calls.
- [WhatsApp](references/whatsapp.md): the 24-hour service window, template and free-form sends,
WhatsApp threads in a mailbox, and setup links for customers' numbers.
- [Template authoring](references/template-authoring.md): the static TSX profile, the check-render-look loop, and revision-safe editing.
- [Authentication](references/auth.md): API keys, OAuth, and organization scoping.
- [Executor](references/executor.md): add Samva's MCP or REST surface to an Executor workspace.
## Common operating rules
1. Authen
Preview of the first 4,000 characters. Read full instructions →
Referenced files: 8 — file references are metadata, not package contents.