Order #1042 is on its way.
", }); ``` Python: ```python import requests resp = requests.post( "https://api.samva.dev/v1/messages", headers={"X-API-Key": SAMVA_API_KEY}, json={ "to": [{"email": "ada@example.com"}], "channel": "email", "email": { "subject": "Your order shipped", "html": "Order #1042 is on its way.
", }, }, ) ``` curl: ```sh curl -X POST https://api.samva.dev/v1/messages \ -H "X-API-Key: $SAMVA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "to": [{ "email": "ada@example.com" }], "channel": "email", "email": { "subject": "Your order shipped", "html": "Order #1042 is on its way.
" } }' ``` ## See a reply land in the same thread. Get a demo address and email it from your own account. Samva receives it as a signed webhook and replies in the same thread through the send API, the same calls your app makes. Get a demo address, email it from your own account, and Samva replies in the same thread. Each step shows as it happens. ## Send, verify, generate from one contract. #01 — The API #01 — The API SEND Code example: ``` POST /v1/messages X-API-Key: samva_sk_live_... { "channel": "email", "to": [{ "email": "ada@example.com" }], "email": { "subject": "Your order shipped" } } 201 { "id": "msg_7q2xk9mvt4znw8rh", "status": "pending" } ``` One typed call. The compiler catches a bad payload before it ships. SENDING AN EMAIL WEBHOOKS & EVENTS Code example: ``` POST /webhooks/samva webhook-id: whevt_7q2xk9mvt4znw8rh webhook-timestamp: 1783503734 webhook-signature: v1,SGVsbG8... { "type": "message.delivered", "timestamp": "2026-07-08T09:42:14Z", "data": { "messageId": "msg_7q2xk9mvt4znw8rh" } } verify({ body, id, timestamp, signature, secret }) ``` Delivery, bounce, and inbound events, signed. Retries with backoff. WEBHOOK REFERENCE OPENAPI 3.1 & SDKS Code example: ``` # the typed TypeScript SDK npm install samva # the whole API, as one spec GET https://api.samva.dev/v1/openapi.json 200 · openapi 3.1 · every endpoint, typed ``` Install the TypeScript SDK, or generate a client from OpenAPI 3.1. OPENAPI SPEC HOSTED MCP Code example: ``` { "mcpServers": { "samva": { "url": "https://mcp.samva.dev", "headers": { "X-API-Key": "samva_sk_live_..." } } } } ``` Point your agent at mcp.samva.dev. Your agent gets sending, replies, domains, templates, campaigns, and webhooks as tools. API key or OAuth. HOSTED MCP ## Replies come back to your app. Fig 1. Isometric drawing: the Samva API press sends a letter down the delivery rail to the customer's pigeonhole cabinet; the reply is filed in the inbound cabinet under its conversation, and a ticker prints the signed message.received webhook for your app. Fig 1. Samva sends the email and reports each delivery event. Your customer's reply is threaded into the conversation of the email it answers, and a signed webhook brings it back to your app. #02 — Replies #02 — Replies Turn on receiving for your domain. A reply to an email you sent arrives at your webhook as `message.received`, with the `conversationId` of the email it answers. Answer in the same thread by passing that id. Fig 4. Isometric drawing: a dispatcher signs an event with a v1 webhook-signature, retries it up to 8 times, and sends it through a duct to your endpoint, which answers 200. Fig 4. Each event is signed in the `webhook-signature` header and retried with backoff until your endpoint returns a successful 2xx response, up to 8 automatic attempts. INBOUND EMAIL ## Everything the one-way pipe leaves out. - [Send in one typed call](https://samva.dev/features/transactional-email): A POST to /v1/messages returns 201 Created with a message id. The message moves from queued to sent to delivered. One call returns a message id, and the email's status follows it from queued to sent to delivered. - [Replies come back to your app](https://samva.dev/features/inbound-email): A customer's reply carries an In-Reply-To header that matches the Message-ID of the email it answers, so it joins that conversation. Inbound email on your domain is parsed, threaded to the email it answers, and posted to your webhook. Answer in the same thread. - [Know what happened to every email](https://samva.dev/docs/platform/webhooks): A message.delivered webhook gets a 500 on attempt 1, backs off, and gets 200 OK on attempt 2. Its webhook-signature header verifies. Sent, delivered, bounced, complained, received: signed webhook events, retried with backoff. Opens, clicks, and a timeline per send in the dashboard. - [Change the email without a deploy](https://samva.dev/features/templates): Publishing version 4 of the receipt template makes it the version that sends. Version 3 stays in the list with a restore action. Versioned templates in a Git-backed project. Publish, roll back, or edit in the AI email editor. - [Send from your own domain](https://samva.dev/docs/channels/email/verify-your-domain): A domain's DKIM and SPF records go from pending to pass and the domain is ready to send. Its DMARC policy is read. Samva generates the DKIM and SPF records and checks your DMARC policy. On Cloudflare or Vercel, it adds them for you. - [Announcements from the same API](https://samva.dev/docs/channels/email/send-a-campaign): A campaign run goes from scheduled to dispatching to completed. Its dispatched count rises to 212 of 214 recipients, and two suppressed contacts are skipped. Campaigns send one email to a list of contacts, now or on a schedule, using the same templates, domain and events as your transactional mail. - [Your agent can run it](https://samva.dev/solutions/ai-agents): Through hosted MCP, an agent patches the receipt template and saves commit a41f9c2. A person publishes that same commit, and it becomes the version that sends. Hosted MCP and the CLI. Your agent edits a template, you review the diff, and you publish that exact version. - [Your own sending reputation](https://samva.dev/features/deliverability): Each account sends with its own reputation. Bounces and complaints are suppressed per account, and you can see and lift a suppression. - [A bill with a ceiling](https://samva.dev/pricing): Extra emails cost exactly $0.50 per 1,000, under a spend limit you set. - [An inbox for your agent](https://samva.dev/features/mailboxes): Give your app or your agent its own inbox on samva.email or your domain, like support@ or agent@. It reads, searches, and replies through the API, CLI, or MCP with a key that reaches only that mailbox. ## The SDK ships an Effect-native client too. #03 — Effect-native #03 — Effect-native Import Pascal-cased modules from `samva/effect/*` and call operations directly. Each operation composes into your Effect v4 program. Code example: ``` import { Effect } from "effect"; import * as Client from "samva/effect/client"; import * as Email from "samva/effect/email"; const program = Email.send({ to: "ada@example.com", subject: "Your order shipped", html: "It arrives Thursday.
", }).pipe( Effect.catchTags({ RateLimitedError: (e) => Effect.sleep(e.retryAfterSeconds * 1_000), ValidationError: (e) => Effect.log(e.fields), }), Effect.provide(Client.layerFetch({ apiKey: process.env.SAMVA_API_KEY! })), ); const message = await Effect.runPromise(program); ``` EFFECT SDK GUIDE ## Build it with your agent. #04 — Agent tooling #04 — Agent tooling Samva publishes setup at `/auth.md`, so your agent picks the credential and writes the integration. Point it at hosted MCP, or paste the brief below. COPY FOR YOUR AGENT $ Read samva.dev/auth.md, create an API key, then follow the quickstart to integrate email. Copy agent setup CREDENTIALS Read auth.md MCP.SAMVA.DEV/MCP Connect hosted MCP ## Samva for ChatGPT, Claude, Cursor, and Grok Open the Samva plugin in ChatGPT, connect one organization, and start with a read-only readiness check. [Get notified about Claude, Cursor, and Grok](https://samva.dev/contact?subject=connectors) - **Claude**: Claude logo Coming soon - **ChatGPT**: [Open in ChatGPT](https://chatgpt.com/plugins/plugin_asdk_app_6a8ebcc4c4c48191b5a3a53638f7b972) - **Cursor**: Cursor logo Coming soon - **Grok**: Grok logo Coming soon ## Numbers we publish, and the code that enforces them. Prices, limits, and retries are read from the code that enforces them. - **Free tier**: Every month, no card 500 emails - **Past your allowance**: Any paid plan, one rate $0.50 / 1,000 - **Webhook delivery**: Automatic attempts, then the log 8 attempts - **Signed events**: What reaches your endpoint for one email 09:41:02 message.sent msg\_8f2c1qd3hv6r0wxk 09:41:04 message.delivered msg\_8f2c1qd3hv6r0wxk 10:17:55 message.received conv\_5nz8qd3hv6r0wxkt - **Send latency**: p50, production, API to accepted 140 ms ## Read the docs, then send. - [Send an email](https://samva.dev/docs/channels/email/send-an-email): QUICKSTART API key to first send in one call. - [API reference](https://samva.dev/docs/api-reference): REFERENCE Every resource, verb, and payload. - [Webhooks](https://samva.dev/docs/platform/webhooks): EVENTS Register endpoints and verify signatures. - [TypeScript SDK](https://samva.dev/docs/developers/typescript-sdk): SDK Promise and Effect entrypoints, typed end to end. - [REST API](https://samva.dev/docs/developers/rest-api): HTTP Auth, pagination, and errors over raw HTTP. - [Hosted MCP](https://samva.dev/docs/developers/mcp): AGENTS Build with your agent over hosted MCP. ## Your customers' business email runs on it too. Small businesses use the same platform in Samva Mail: business email on their own domain, shared inboxes, and an AI assistant that answers the routine customer email. The conversations your API writes are the ones their team answers. Samva for small businesses ## Questions from developers. ### Which languages can I use? TypeScript has a typed SDK (\`npm install samva\`). Anything else calls REST, and the OpenAPI 3.1 spec generates a client in your language. ### How do I verify a webhook? Every event is signed and follows the Standard Webhooks spec. \`@samva/webhooks\` checks the signature for you in TypeScript. In other languages, verify with any Standard Webhooks library and your signing secret. ### Can my coding agent set it up? Yes. Point any MCP client that supports OAuth at \`mcp.samva.dev\`, or run \`samva login\`. A person approves the first credential. ### What does it cost? 500 emails a month free, no card. Paid plans start at $5 for 15,000. ## Send the first email from your editor. Install `samva`, pass your key, and call `email.send`. The response carries the message id you track from there. [Start sending](https://samva.dev/signup) Read the docs