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

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 — 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",
  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 accepts 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" }],
  channel: "email",
  email: {
    subject: "Welcome to Samva",
    html: "<h1>Welcome!</h1>",
  },
});

Input fields

The nested email object carries subject, html, text, 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.scheduled

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=sk_sm_your_api_key_here

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

Key format

Every Samva API key starts with sk_sm_. There is no separate live and test key — pass your key into the client as apiKey.

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

See Authentication for key format and details.

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