TypeScript SDK

The samva package is the official TypeScript/JavaScript SDK for the Samva email API. It is generated from the OpenAPI specification, so its surface mirrors the REST API exactly.

This page is a reference. For a step-by-step walkthrough of sending your first email, see Send an email.

Installation

npm install samva

yarn add samva

pnpm add samva

bun add samva

Entrypoints

The samva package ships three entrypoints from a single install. They are all generated from the same OpenAPI surface, so they stay in sync with the REST API; pick the one that matches your runtime style.

The rest of this page documents the Promise client. For the Effect client, see Native Effect client below.

Client

createClient(config)

Creates a configured client instance. The organization context is derived from the API key; no organization slug or ID is required.

import { createClient } from "samva";

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

Config options

Pass exactly one of apiKey or authToken. Use apiKey for servers (the organization is derived from the key); use authToken for first-party or OAuth tooling, where the session is user-scoped, and pass the active organization with headers: { "x-org-slug": "<slug>" }. See API keys and OAuth sessions.

Additional fields from the underlying generated HTTP client Config (such as headers and fetch) are also accepted.

Return shape

createClient returns a SamvaClient exposing the live services below plus client, the underlying HTTP client.

Calling convention

Methods take flat request parameters as the first argument. Request options such as throwOnError, headers, and signal are passed as an optional second argument.

Every method resolves to a result object:

const result = await samva.email.send({
  to: "ada@example.com",
  cc: "grace@example.com",
  replyTo: "support@example.com",
  subject: "Welcome to Samva",
  html: "<h1>Welcome!</h1>",
});

if (result.error) {
  console.error("Send failed:", result.error);
} else {
  console.log("Sent:", result.data?.id);
}

samva.email

The canonical surface for email.

email.send(input, options?)

The simplest way to send email. It is an SDK-only ergonomic wrapper over messages.send() - there is no email.send REST endpoint. Email fields are flattened directly into the input object (not nested under an email key).

const result = await samva.email.send({
  to: "ada@example.com",
  subject: "Welcome to Samva",
  html: "<h1>Welcome!</h1>",
});

Input fields

Recipients

to, cc, and bcc accept a single value or an array of any of:

Email helper methods

The email service also exposes domain, sender, and template management. All take the standard options object and return { data, error }.

For domain verification steps, see Verify your domain.

samva.messages

The unified send and retrieval API. email.send() delegates to messages.send(); reach for messages.send() directly when you want the explicit nested shape, for example to address contacts by contactId, send to multiple recipients, or thread a reply.

messages.send(input, options?)

const result = await samva.messages.send({
  to: [{ contactId: "contact_123" }],
  cc: [{ email: "grace@example.com" }],
  channel: "email",
  email: {
    subject: "Welcome to Samva",
    html: "<h1>Welcome!</h1>",
    replyTo: "support@example.com",
  },
});

Input fields

The nested email object carries subject, html, text, replyTo, attachments, templateId, templateData, inReplyToMessageId, and unsubscribeGroupId - the same content fields that email.send() flattens into body.

Other message methods

const messages = await samva.messages.list({ channel: "email", limit: "20" });
const message = await samva.messages.get({ id: "msg_123" });
const events = await samva.messages.getEvents({ id: "msg_123" });

Other services

All services follow the same calling convention and result shape.

samva.contacts

samva.conversations

samva.webhooks

For receiving and verifying webhook events, see Receive webhooks.

samva.apiKeys

samva.organizations

samva.scheduledMessages

Scheduling is its own resource; there is no scheduledAt field on messages.send.

samva.campaigns

Error handling

Methods do not throw on API errors by default. Inspect the result instead:

const result = await samva.email.send({
  to: "ada@example.com",
  subject: "Test",
  text: "Hello",
});

if (result.error) {
  // result.error holds the error payload
  console.error(result.error);
} else {
  console.log(result.data?.id);
}

Environment variables

Store the API key in an environment variable rather than hard-coding it.

# .env
SAMVA_API_KEY=samva_sk_live_your_api_key

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

Key format

Production keys start with samva_sk_live_; keys minted outside production start with samva_sk_test_. Pass either environment's key into the client as apiKey.

const samva = createClient({ apiKey: "samva_sk_live_..." });

See API keys for key format and details.

Native Effect client

samva/effect is a first-class Effect v4 client. It returns Effects rather than wrapping the Promise client, so it composes directly into Effect programs. Install effect alongside samva:

npm install samva effect

Create a client inside an Effect and provide an HTTP layer:

import { Effect } from "effect";
import { FetchHttpClient } from "effect/unstable/http";
import { createClient } from "samva/effect";

const program = Effect.gen(function* () {
  const samva = yield* createClient({ apiKey: process.env.SAMVA_API_KEY! });

  return yield* samva.email.send({
    to: "ada@example.com",
    subject: "Welcome to Samva",
    html: "<h1>Welcome!</h1>",
  });
}).pipe(Effect.provide(FetchHttpClient.layer));

For application-wide dependency injection, use the SamvaClient service and provide its layer:

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

const program = Effect.gen(function* () {
  const samva = yield* SamvaClient;

  return yield* samva.email.send({
    to: "ada@example.com",
    subject: "Welcome to Samva",
    html: "<h1>Welcome!</h1>",
  });
}).pipe(Effect.provide(SamvaClient.layerFetch({ apiKey: process.env.SAMVA_API_KEY! })));

The Effect client exposes flat email and messages send helpers, the same email-first surface as the Promise client, plus a top-level raw property (e.g. samva.raw) for the full generated Effect operation surface. Errors surface through the Effect error channel rather than a { data, error } result, so handle them with the usual combinators (Effect.catchAll, Effect.match, and so on).

Support matrix

The SDK is generated from the Samva OpenAPI specification using @hey-api/openapi-ts, so it stays in sync with the REST API. For other languages, use the REST API with your language's HTTP client.

See also