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
webhook-id: whev_01hv8kq2
webhook-timestamp: 1783503734
webhook-signature: v1,SGVsbG8...

{ "type": "message.delivered", "timestamp": "2026-07-08T09:42:14Z",
  "data": { "messageId": "msg_01hv8kq2" } }

verify({ body, id, timestamp, signature, secret })

Delivery, bounce, and inbound events use Standard Webhooks signing and retry with backoff. Verify the raw body with webhook-id, webhook-timestamp, and webhook-signature.

WEBHOOK REFERENCE

OPENAPI 3.0 & 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.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.dev/mcp",
      "headers": { "X-API-Key": "samva_sk_live_..." }
    }
  }
}

Point an OAuth-capable client at mcp.samva.dev/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 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

#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.dev/auth.md, create an API key, then follow the quickstart to integrate email.

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

Read the docs before you write a line.

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

Give an OAuth-capable client the tools.

Send the first email from your editor.

Install samva, pass your key, and call email.send. The first email goes out in minutes.

Start sending Read the docs