Install samva. Send in one call.

Install samva, pass your key, and call email.send. Then get back to the product. Or copy the setup brief and let your agent write the integration.

npm install samvaOpenAPI 3.1HOSTED MCP

import { createClient } from "samva";

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

const message = await samva.email.send({
  to: "ada@example.com",
  subject: "Your order shipped",
  html: "<p>Order #1042 is on its way.</p>",
});

POST /v1/messages201 · msg_7q2xk9mvt4znw8rh

#01 — The API

Send, verify, generate from one contract.

SEND

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

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

# 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

{
  "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

#02 — Replies

Replies come back to your app.

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.

POST /webhooks/samva

{ "type": "message.received",
  "data": {
    "from": "ada@example.com",
    "subject": "Re: Your order shipped",
    "conversationId": "conv_01j8k5p7q9r2s4t6v8wx" } }

await samva.email.send({
  to: "ada@example.com",
  conversationId: "conv_01j8k5p7q9r2s4t6v8wx",
  subject: "Re: Your order shipped",
  html: "<p>It arrives Thursday.</p>",
});

SIGNEDwebhook-signature: v1 on every request
RETRIESup to 8 attempts, with backoff
YOUR ENDPOINTanswers 200, the event is done

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

#03 — Effect-native

The SDK ships an Effect-native client too.

Import Pascal-cased modules from samva/effect/* and call operations directly. Each operation composes into your Effect v4 program.

import { Effect } from "effect";
import * as Client from "samva/effect/client";
import * as Email from "samva/effect/email";

const send = Email.send({ to, subject, html }).pipe(
  Effect.catchTags({
    RateLimitedError: (e) => Effect.sleep(e.retryAfterSeconds * 1_000),
    ValidationError: (e) => Effect.log(e.fields),
  }),
  Effect.provide(Client.layerFetch({ apiKey })),
);

Typed errors: Failures arrive as tagged errors you narrow with catchTags. RateLimitedError carries retryAfterSeconds, ValidationError carries the offending fields.
Layer-based services: Domain operations require Client.Service. Build Client.layerFetch once and provide it around the part of your program that calls Samva.
Schema-driven: Requests and responses are decoded through Schema, so a malformed payload fails at the boundary, not three calls later.

EFFECT SDK GUIDE

#04 — Agent tooling

Build it with your agent.

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.

CREDENTIALSRead auth.md MCP.SAMVA.DEV/MCPConnect hosted MCP

Samva inside your AI assistant

Open the Samva plugin in ChatGPT, connect one organization, and start with a read-only readiness check.

ClaudeComing soon
ChatGPT
CursorComing soon
GrokComing soon

Read the docs, then send.

QUICKSTARTSend an email

API key to first send in one call.

REFERENCEAPI reference

Every resource, verb, and payload.

EVENTSWebhooks

SDKTypeScript SDK

Promise and Effect entrypoints, typed end to end.

HTTPREST API

Auth, pagination, and errors over raw HTTP.

AGENTSHosted MCP

Build with your agent over hosted MCP.

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?

3,000 emails a month free, no card. Paid plans start at $5 for 15,000.