FOR DEVELOPERS

Email that sends in one typed call.

Install samva, pass your key, and call email.send. Requests and responses are typed end to end, webhooks are signed, and templates are versioned.

Start sending Read the docs

npm install samvaOpenAPI 3.0HOSTED MCP

import { createClient } from "samva";

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

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

POST /v1/messages202 · msg_01hv8kq2

#01 — THE API SURFACE

Send, verify, and generate against one contract.

SEND

POST /v1/messages
X-API-Key: samva_sk_live_...

{ "channel": "email",
  "to": [{ "email": "ada@example.com" }],
  "email": { "subject": "Your order shipped" } }

202  { "id": "msg_01hv8kq2", "status": "queued" }

One POST, or one typed call. Requests and responses are typed end to end, so the compiler catches a bad payload before production does.

SENDING AN EMAIL

WEBHOOKS & EVENTS

POST /webhooks/samva
X-Webhook-Signature: sha256=9f2ab1c4...
X-Webhook-Event: message.delivered

{ "event": "message.delivered", "messageId": "msg_01hv8kq2" }

verify: timingSafeEqual(sig, "sha256=" + hmacSha256(secret, body))

Delivery, bounce, and inbound events arrive as HMAC-SHA256 signed webhooks, retried with backoff. Verify the X-Webhook-Signature against the raw body in constant time.

WEBHOOK REFERENCE

OPENAPI 3.0 & SDKS

# the typed TypeScript SDK
npm install samva

# the whole API, as one spec
GET https://api.samva.app/v1/openapi.json
200 · openapi 3.0 · every endpoint, typed

Install the typed TypeScript SDK, or work from the OpenAPI 3.0 spec at /v1/openapi.json in any other language. Both describe the same contract.

OPENAPI SPEC

HOSTED MCP

{
  "mcpServers": {
    "samva": {
      "url": "https://mcp.samva.app/mcp",
      "headers": { "X-API-Key": "samva_sk_live_..." }
    }
  }
}

Point an OAuth-capable client at mcp.samva.app/mcp and your agent gets templates, contacts, and delivery status as tools. API key or OAuth, your call.

HOSTED MCP

#02 — EFFECT-NATIVE

There is an Effect-native client too.

Import from samva/effect and calls return Effects that compose into your program. Same email API, expressed in Effect v4 primitives.

import { Effect } from "effect";
import { createClient } from "samva/effect";

const send = Effect.gen(function* () {
  const samva = yield* createClient({ apiKey });
  return yield* samva.email.send({ to, subject, html });
}).pipe(
  Effect.catchTags({
    RateLimitedError: (e) => Effect.sleep(e.retryAfterSeconds),
    ValidationError: (e) => Effect.log(e.fields),
  }),
);

Typed errors: Failures arrive as tagged errors you narrow with catchTags. RateLimitedError carries retryAfterSeconds, ValidationError carries the offending fields.
Layer-based services: SamvaClient is a service. Build the layer once with SamvaClient.layerFetch and read the client wherever you need it.
Schema-driven: Requests and responses are decoded through Schema, so a malformed payload fails at the boundary, not three calls later.

EFFECT SDK GUIDE

#03 — AGENT TOOLING

Hand the integration to your agent.

Samva publishes machine-readable setup at /auth.md, so a coding agent picks the right credential before it acts. Point it at hosted MCP, or paste the brief below.

COPY FOR YOUR AGENT

$ Read samva.app/auth.md, create an API key, then follow the quickstart to integrate email.

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

( DOCUMENTATION )