Samva

https://samva.dev/docs
Admin
Samva is a modern email API and platform that enables product teams to send transactional,...
Tokens:59,773
Snippets:769
Trust Score:3.9
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install dependencies

Source: https://samva.dev/docs/integrations/prisma

Install the required Samva and Prisma client packages.

```sh
bun add samva @prisma/client
```

--------------------------------

### Install and verify the Samva CLI

Source: https://samva.dev/docs/developers/cli

Install the CLI globally via npm and verify the installation with the help command.

```bash
npm install -g @samva/cli
samva --help
```

--------------------------------

### Install Samva Effect SDK

Source: https://samva.dev/docs/integrations/effect-sdk

Install the required packages using bun.

```sh
bun add samva effect@4.0.0-rc.110
```

--------------------------------

### Install dependencies

Source: https://samva.dev/docs/integrations/authjs

Install the required Auth.js and Samva packages.

```sh
bun add next-auth@beta samva
```

--------------------------------

### Install Better Auth integration

Source: https://samva.dev/docs/integrations/better-auth

Install the required packages using bun.

```sh
bun add better-auth samva @samva/better-auth
```

--------------------------------

### Install dependencies

Source: https://samva.dev/docs/integrations/react-email

Install the necessary packages for React Email and the Samva SDK.

```sh
bun add react-email samva
```

--------------------------------

### Install Samva SDK

Source: https://samva.dev/docs/integrations/nextjs

Install the required packages for the Samva SDK in a Next.js project.

```sh
bun add samva server-only
```

--------------------------------

### Install Samva Effect SDK

Source: https://samva.dev/docs/developers/typescript-sdk

Install the required Samva package and the compatible version of Effect.

```bash
npm install samva effect@4.0.0-rc.110
```

--------------------------------

### Install Samva SDK

Source: https://samva.dev/docs/developers

Installs the required Samva package using your preferred package manager.

```bash
npm install samva
```

```bash
bun add samva
```

```bash
yarn add samva
```

--------------------------------

### Install Email SDK dependencies

Source: https://samva.dev/docs/integrations/email-sdk

Install the required packages using the Bun package manager.

```sh
bun add @samva/email-sdk @opencoredev/email-sdk samva
```

--------------------------------

### Install TypeScript SDK

Source: https://samva.dev/docs/api-reference/openapi

Command to install the official Samva TypeScript SDK via npm.

```bash
npm install samva
```

--------------------------------

### Install dependencies

Source: https://samva.dev/docs/integrations/hono-cloudflare-workers

Install the required Hono and Samva packages along with development dependencies for Cloudflare Workers.

```sh
bun add hono samva
bun add -d wrangler @cloudflare/workers-types typescript
```

--------------------------------

### GET /api-reference/email/getCustomTrackingDomainConnect

Source: https://samva.dev/docs/api-reference/email/getCustomTrackingDomainConnect

Checks the eligibility status for automatic Custom Tracking Domain setup.

```APIDOC
## GET /api-reference/email/getCustomTrackingDomainConnect

### Description
Checks whether a custom tracking domain is eligible for automatic setup.

### Method
GET

### Endpoint
https://samva.dev/docs/api-reference/email/getCustomTrackingDomainConnect
```

--------------------------------

### Install React Email dependencies

Source: https://samva.dev/docs/integrations/tanstack-start

Install the necessary packages to use React Email with your project.

```sh
bun add react-email react react-dom
```

--------------------------------

### Install React Email dependencies

Source: https://samva.dev/docs/integrations/hono-cloudflare-workers

Install the necessary packages to enable React Email rendering in a Workers-compatible environment.

```sh
bun add @react-email/render react react-dom
```

--------------------------------

### GET /docs/api-reference/email/getCatchAllConfig

Source: https://samva.dev/docs/api-reference/email/getCatchAllConfig

Retrieves the catch-all configuration settings.

```APIDOC
## GET https://samva.dev/docs/api-reference/email/getCatchAllConfig

### Description
Retrieves the catch-all configuration for the specified email service.

### Method
GET

### Endpoint
https://samva.dev/docs/api-reference/email/getCatchAllConfig
```

--------------------------------

### Request paginated messages

Source: https://samva.dev/docs/developers/rest-api

Example of a GET request using page and limit query parameters.

```http
GET /v1/messages?page=2&limit=50
```

--------------------------------

### Error Response Examples

Source: https://samva.dev/docs/developers/rest-api

Examples of various error responses, including validation failures, missing resources, and rate limiting.

```json
{
  "_tag": "ValidationError",
  "message": "Invalid request body",
  "fields": {
    "to": ["Must be a valid email address"]
  }
}
```

```json
{
  "_tag": "ResourceNotFoundError",
  "resource": "Message",
  "id": "msg_7q2xk9mvt4znw8rh"
}
```

```json
{
  "_tag": "RateLimitedError",
  "retryAfterSeconds": 30
}
```

--------------------------------

### GET /docs/api-reference/developers/listLogs

Source: https://samva.dev/docs/api-reference/developers/listLogs

Retrieves a list of logs from the system.

```APIDOC
## GET /docs/api-reference/developers/listLogs

### Description
Retrieves a list of logs from the system.

### Method
GET

### Endpoint
https://samva.dev/docs/api-reference/developers/listLogs
```

--------------------------------

### GET https://samva.dev/docs/api-reference/templates/list

Source: https://samva.dev/docs/api-reference/templates/list

Retrieves a list of templates available in the system.

```APIDOC
## GET https://samva.dev/docs/api-reference/templates/list

### Description
Retrieves a list of available templates.

### Method
GET

### Endpoint
https://samva.dev/docs/api-reference/templates/list
```

--------------------------------

### GET https://samva.dev/docs/api-reference/campaigns/list

Source: https://samva.dev/docs/api-reference/campaigns/list

Retrieves a list of campaigns.

```APIDOC
## GET https://samva.dev/docs/api-reference/campaigns/list

### Description
Retrieves a list of campaigns from the system.

### Method
GET

### Endpoint
https://samva.dev/docs/api-reference/campaigns/list
```

--------------------------------

### GET /webhooks

Source: https://samva.dev/docs/api-reference/webhooks/list

Retrieves a list of all webhooks configured for the user.

```APIDOC
## GET /webhooks

### Description
Retrieves a list of all webhooks configured for the user.

### Method
GET

### Endpoint
https://samva.dev/docs/api-reference/webhooks/list
```

--------------------------------

### GET /docs/api-reference/billing/getOverageSettings

Source: https://samva.dev/docs/api-reference/billing/getOverageSettings

Retrieves the overage usage and limits for the specified workspace.

```APIDOC
## GET /docs/api-reference/billing/getOverageSettings

### Description
Retrieves the overage usage and limits for the workspace.

### Method
GET

### Endpoint
https://samva.dev/docs/api-reference/billing/getOverageSettings
```

--------------------------------

### GET https://samva.dev/docs/api-reference/templates/listDashboard

Source: https://samva.dev/docs/api-reference/templates/listDashboard

Retrieves a list of templates available for the dashboard.

```APIDOC
## GET https://samva.dev/docs/api-reference/templates/listDashboard

### Description
Retrieves a list of templates available for the dashboard.

### Method
GET

### Endpoint
https://samva.dev/docs/api-reference/templates/listDashboard
```

--------------------------------

### Client Initialization and Usage

Source: https://samva.dev/docs/developers/typescript-sdk

Demonstrates how to initialize the Samva client using a fetch-backed layer and execute a domain operation.

```APIDOC
## SDK Usage

### Description
Initialize the Samva client using `Client.layerFetch` and execute operations from domain modules like `Email` or `Media`.

### Installation
```bash
npm install samva effect@4.0.0-rc.110
```

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

const program = Email.send({
    to: "ada@example.com",
    subject: "Welcome to Samva",
    html: "<h1>Welcome!</h1>",
  }).pipe(
    Effect.provide(
      Client.layerFetch({ apiKey: process.env.SAMVA_API_KEY! }),
    ),
  );
```
```

--------------------------------

### Webhook request structure

Source: https://samva.dev/docs/integrations/webhooks

Example of a POST request with required Standard Webhooks headers.

```http
POST /webhooks/samva
webhook-id: evt_01…
webhook-timestamp: 1786796531
webhook-signature: v1,base64-signature
content-type: application/json

{"type":"message.delivered","timestamp":"2026-01-15T09:42:11.204Z","data":{"messageId":"msg_01…","status":"delivered"}}
```

--------------------------------

### API Response Example

Source: https://samva.dev/docs/channels/email/send-an-email

The JSON structure returned upon a successful request.

```json
{
  "id": "msg_7q2xk9mvt4znw8rh",
  "status": "pending"
}
```

--------------------------------

### GET https://samva.dev/docs/api-reference/apiKeys/get

Source: https://samva.dev/docs/api-reference/apiKeys/get

Retrieves an API key from the specified endpoint.

```APIDOC
## GET https://samva.dev/docs/api-reference/apiKeys/get

### Description
Retrieves an API key from the Samva API.

### Method
GET

### Endpoint
https://samva.dev/docs/api-reference/apiKeys/get
```

--------------------------------

### GET https://samva.dev/docs/api-reference/apiKeys/getActivity

Source: https://samva.dev/docs/api-reference/apiKeys/getActivity

Retrieves the activity logs for API keys.

```APIDOC
## GET https://samva.dev/docs/api-reference/apiKeys/getActivity

### Description
Retrieves the activity logs for API keys.

### Method
GET

### Endpoint
https://samva.dev/docs/api-reference/apiKeys/getActivity
```

--------------------------------

### Configure Environment Variables

Source: https://samva.dev/docs/developers/typescript-sdk

Store API keys in environment variables and initialize the client using process.env.

```bash
# .env
SAMVA_API_KEY=samva_sk_live_your_api_key
```

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

--------------------------------

### Initialize Client with API Key

Source: https://samva.dev/docs/developers/typescript-sdk

Pass the production or test API key directly into the client configuration.

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

--------------------------------

### createClient(config)

Source: https://samva.dev/docs/developers/typescript-sdk

Initializes a new Samva client instance. You must provide either an apiKey or an authToken to authenticate your requests.

```APIDOC
## createClient(config)

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

### Parameters
- **apiKey** (string) - Required (One of apiKey/authToken) - API key. Sent as the X-API-Key header.
- **authToken** (string) - Required (One of apiKey/authToken) - OAuth bearer token. Sent as Authorization: Bearer.
- **baseUrl** (string) - Optional - API base URL. Defaults to https://api.samva.dev.

### Usage Example
```typescript
import { createClient } from "samva";

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

--------------------------------

### Generate Client Libraries

Source: https://samva.dev/docs/api-reference/openapi

Commands to generate SDKs for TypeScript, Python, and Go using the OpenAPI specification.

```bash
npx @hey-api/openapi-ts -i https://api.samva.dev/v1/openapi.json -o ./src/client
```

```bash
openapi-generator generate -i https://api.samva.dev/v1/openapi.json -g python -o ./python-client
```

```bash
openapi-generator generate -i https://api.samva.dev/v1/openapi.json -g go -o ./go-client
```

--------------------------------

### GET /v1/messages

Source: https://samva.dev/docs/developers/rest-api

Retrieves a list of messages.

```APIDOC
## GET /v1/messages

### Description
List messages.

### Method
GET

### Endpoint
/v1/messages
```

--------------------------------

### Initialize and use Samva Effect client

Source: https://samva.dev/docs/developers/typescript-sdk

Import the necessary modules and provide the fetch-backed client layer to the program.

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

const program = Email.send({
    to: "ada@example.com",
    subject: "Welcome to Samva",
    html: "<h1>Welcome!</h1>",
  }).pipe(
    Effect.provide(
      Client.layerFetch({ apiKey: process.env.SAMVA_API_KEY! }),
    ),
  );
```

--------------------------------

### GET /webhooks/stats

Source: https://samva.dev/docs/api-reference/webhooks/getStats

Retrieves the delivery statistics for webhooks.

```APIDOC
## GET /webhooks/stats

### Description
Retrieves the delivery statistics for webhooks configured in the system.

### Method
GET

### Endpoint
https://samva.dev/docs/api-reference/webhooks/getStats
```

--------------------------------

### Preview templates locally

Source: https://samva.dev/docs/integrations/react-email

Use the email CLI to preview templates and enable hot-reloading during development.

```sh
bunx email dev    # live preview at http://localhost:3000
```

--------------------------------

### GET /scheduledMessages

Source: https://samva.dev/docs/api-reference/scheduledMessages/list

Retrieves a list of all scheduled messages.

```APIDOC
## GET /scheduledMessages

### Description
Retrieves a list of all scheduled messages currently stored in the system.

### Method
GET

### Endpoint
https://samva.dev/docs/api-reference/scheduledMessages/list
```

--------------------------------

### Implement Form Action

Source: https://samva.dev/docs/integrations/sveltekit

Handle form submissions in a SvelteKit server file to send messages via Samva.

```ts
import { fail } from "@sveltejs/kit";
import type { Actions } from "./$types";

import { getSamva } from "$lib/server/samva";

const escapeHtml = (value: string): string =>
  value
    .replaceAll("&", "&amp;")
    .replaceAll("<", "&lt;")
    .replaceAll(">", "&gt;")
    .replaceAll('"', "&quot;")
    .replaceAll("'", "&#39;");

const field = (formData: FormData, name: string): string =>
  String(formData.get(name) ?? "").trim();

export const actions = {
  default: async ({ request }) => {
    const formData = await request.formData();
    const email = field(formData, "email");
    const message = field(formData, "message");

    if (!email || !message) {
      return fail(400, { error: "Email and message are required." });
    }

    await getSamva().messages.send({
      to: [{ email }],
      channel: "email",
      email: {
        subject: "Thanks for contacting us",
        html: `<p>${escapeHtml(message).replaceAll("\n", "<br />")}</p>`,
        text: message,
      },
    });

    return { success: true };
  },
} satisfies Actions;
```

--------------------------------

### GET /organizations

Source: https://samva.dev/docs/api-reference/organizations/get

Retrieves the details of the current organization.

```APIDOC
## GET /organizations

### Description
Retrieves the details of the current organization associated with the authenticated user or request context.

### Method
GET

### Endpoint
https://samva.dev/docs/api-reference/organizations/get
```

--------------------------------

### POST https://samva.dev/docs/api-reference/apiKeys/create

Source: https://samva.dev/docs/api-reference/apiKeys/create

Endpoint to create a new API key.

```APIDOC
## POST https://samva.dev/docs/api-reference/apiKeys/create

### Description
Creates a new API key for the user.

### Method
POST

### Endpoint
https://samva.dev/docs/api-reference/apiKeys/create
```

--------------------------------

### Install Samva and Cloudflare Adapter

Source: https://samva.dev/docs/integrations/astro

Commands to add the Samva package and the Cloudflare adapter to an Astro project.

```sh
bun add samva
bunx astro add cloudflare
```

--------------------------------

### POST https://samva.dev/docs/api-reference/organizations/create

Source: https://samva.dev/docs/api-reference/organizations/create

Endpoint to create a new workspace.

```APIDOC
## POST https://samva.dev/docs/api-reference/organizations/create

### Description
Creates a new workspace in the Samva system.

### Method
POST

### Endpoint
https://samva.dev/docs/api-reference/organizations/create
```

--------------------------------

### Authenticate with OAuth

Source: https://samva.dev/docs/developers/cli

Perform interactive login and select an organization context.

```bash
samva login
samva org list
samva org use <slug>
```

--------------------------------

### POST /templates

Source: https://samva.dev/docs/api-reference/templates/create

Creates a new template in the system.

```APIDOC
## POST /templates

### Description
Creates a new template.

### Method
POST

### Endpoint
https://samva.dev/docs/api-reference/templates/create
```

--------------------------------

### GET /apiKeys

Source: https://samva.dev/docs/api-reference/apiKeys/list

Retrieves a list of all API keys.

```APIDOC
## GET /apiKeys

### Description
Retrieves a list of all API keys associated with the user account.

### Method
GET

### Endpoint
https://samva.dev/docs/api-reference/apiKeys/list
```

--------------------------------

### Create a SvelteKit API endpoint

Source: https://samva.dev/docs/integrations/sveltekit

Use a +server.ts file to handle POST requests for sending messages. Ensure credentials are configured in the server-only client module.

```ts
import { error, json } from "@sveltejs/kit";
import type { RequestHandler } from "./$types";

import { getSamva } from "$lib/server/samva";

const escapeHtml = (value: string): string =>
  value
    .replaceAll("&", "&amp;")
    .replaceAll("<", "&lt;")
    .replaceAll(">", "&gt;")
    .replaceAll('"', "&quot;")
    .replaceAll("'", "&#39;");

const isRecord = (value: unknown): value is Record<string, unknown> =>
  typeof value === "object" && value !== null && !Array.isArray(value);

const readString = (value: unknown): string => (typeof value === "string" ? value.trim() : "");

export const POST: RequestHandler = async ({ request }) => {
  const body: unknown = await request.json().catch(() => null);
  if (!isRecord(body)) {
    error(400, "Expected a JSON object.");
  }

  const to = readString(body.to);
  const subject = readString(body.subject);
  const message = readString(body.message);

  if (!to || !subject || !message) {
    error(400, "to, subject, and message are required.");
  }

  await getSamva().messages.send({
    to: [{ email: to }],
    channel: "email",
    email: {
      subject,
      html: `<p>${escapeHtml(message).replaceAll("\n", "<br />")}</p>`,
      text: message,
    },
  });

  return json({ ok: true });
};
```

--------------------------------

### GET /webhooks/logs

Source: https://samva.dev/docs/api-reference/webhooks/getLogs

Retrieves a list of webhook delivery logs.

```APIDOC
## GET /webhooks/logs

### Description
Retrieves a list of webhook delivery logs for the account.

### Method
GET

### Endpoint
https://samva.dev/docs/api-reference/webhooks/getLogs
```

--------------------------------

### Initialize Samva client

Source: https://samva.dev/docs/developers

Initializes the Samva client using the API key stored in environment variables.

```typescript
import { createClient } from "samva";

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

--------------------------------

### GET /docs/api-reference/templates/getById

Source: https://samva.dev/docs/api-reference/templates/getById

Retrieves a specific template by its unique identifier.

```APIDOC
## GET /docs/api-reference/templates/getById

### Description
Retrieves a specific template from the Samva platform using its unique identifier.

### Method
GET

### Endpoint
https://samva.dev/docs/api-reference/templates/getById
```

--------------------------------

### Manage execution profiles

Source: https://samva.dev/docs/developers/cli

Create and switch between execution profiles to manage target environments.

```bash
samva profile create local --target local
samva profile use local
samva --profile local email doctor
```

--------------------------------

### GET https://samva.dev/docs/api-reference/scheduledMessages/get

Source: https://samva.dev/docs/api-reference/scheduledMessages/get

Retrieves the details of a scheduled message.

```APIDOC
## GET https://samva.dev/docs/api-reference/scheduledMessages/get

### Description
Retrieves the details of a scheduled message.

### Method
GET

### Endpoint
https://samva.dev/docs/api-reference/scheduledMessages/get
```

--------------------------------

### Create and schedule an email campaign with TypeScript

Source: https://samva.dev/docs/channels/email/send-a-campaign

Initializes the Samva client to create a campaign with inline HTML content and schedules a run for a specific future time.

```typescript
import { createClient } from "samva";

const samva = createClient({ apiKey: process.env.SAMVA_API_KEY! });
const campaign = await samva.campaigns.create({
  name: "August newsletter",
  channel: "email",
  content: {
    channel: "email",
    email: { subject: "What's new", html: "<h1>August updates</h1>" },
  },
  audience: { includeTags: ["newsletter"], excludeTags: ["bounced"] },
});

const run = await samva.campaigns.scheduleRun({
  id: campaign.id,
  scheduledFor: "2026-08-01T09:00:00Z",
  idempotencyKey: "august-newsletter-v1",
});

console.log("Campaign run:", run.id);
```

--------------------------------

### GET https://samva.dev/docs/api-reference/operations/list

Source: https://samva.dev/docs/api-reference/operations/list

Retrieves a list of asynchronous operations.

```APIDOC
## GET https://samva.dev/docs/api-reference/operations/list

### Description
Retrieves a list of asynchronous operations.

### Method
GET

### Endpoint
https://samva.dev/docs/api-reference/operations/list
```

--------------------------------

### GET /messages

Source: https://samva.dev/docs/api-reference/messages/list

Retrieves a list of messages from the Samva API.

```APIDOC
## GET /messages

### Description
Retrieves a list of messages from the Samva platform.

### Method
GET

### Endpoint
https://samva.dev/docs/api-reference/messages/list
```

--------------------------------

### POST /campaigns

Source: https://samva.dev/docs/api-reference/campaigns/create

Creates a new campaign in the system.

```APIDOC
## POST /campaigns

### Description
Creates a new campaign.

### Endpoint
https://samva.dev/docs/api-reference/campaigns/create
```

--------------------------------

### GET https://samva.dev/docs/api-reference/messages/get

Source: https://samva.dev/docs/api-reference/messages/get

Retrieves a message from the Samva API.

```APIDOC
## GET https://samva.dev/docs/api-reference/messages/get

### Description
Retrieves a message from the Samva platform.

### Method
GET

### Endpoint
https://samva.dev/docs/api-reference/messages/get
```

--------------------------------

### GET https://samva.dev/docs/api-reference/contacts/list

Source: https://samva.dev/docs/api-reference/contacts/list

Retrieves a list of contacts from the system.

```APIDOC
## GET https://samva.dev/docs/api-reference/contacts/list

### Description
Retrieves a list of contacts from the Samva platform.

### Method
GET

### Endpoint
https://samva.dev/docs/api-reference/contacts/list
```

--------------------------------

### Manage Campaigns via CLI

Source: https://samva.dev/docs/channels/email/send-a-campaign

Commands for creating campaigns, scheduling runs, and retrieving run status or recipient information.

```bash
samva campaigns create --name "August newsletter" \
  --subject "What's new" --html "<h1>August updates</h1>" \
  --include-tags newsletter
samva campaigns runs create <campaign-id> --at 2026-08-01T09:00:00Z \
  --idempotency-key august-newsletter-v1
samva campaigns runs get <campaign-id> <run-id>
samva campaigns runs recipients <campaign-id> <run-id> --status failed
```

--------------------------------

### GET https://samva.dev/docs/api-reference/email/listBlocks

Source: https://samva.dev/docs/api-reference/email/listBlocks

Retrieves a list of block entries.

```APIDOC
## GET https://samva.dev/docs/api-reference/email/listBlocks

### Description
Retrieves a list of block entries from the system.

### Method
GET

### Endpoint
https://samva.dev/docs/api-reference/email/listBlocks
```

--------------------------------

### GET https://samva.dev/docs/api-reference/contacts/getEngagement

Source: https://samva.dev/docs/api-reference/contacts/getEngagement

Retrieves engagement metrics for a contact.

```APIDOC
## GET https://samva.dev/docs/api-reference/contacts/getEngagement

### Description
Retrieves engagement metrics for a specific contact.

### Method
GET

### Endpoint
https://samva.dev/docs/api-reference/contacts/getEngagement
```

--------------------------------

### Enable Custom Tracking via CLI

Source: https://samva.dev/docs/channels/email/custom-tracking-domain

Use the CLI to enable custom tracking for a specific domain ID, optionally specifying a custom subdomain label.

```bash
samva email domains custom-tracking enable dom_abc123
samva email domains custom-tracking enable dom_abc123 --label links
```

--------------------------------

### GET https://samva.dev/docs/api-reference/contacts/get

Source: https://samva.dev/docs/api-reference/contacts/get

Retrieves a contact record from the system.

```APIDOC
## GET https://samva.dev/docs/api-reference/contacts/get

### Description
Retrieves a specific contact record from the Samva API.

### Method
GET

### Endpoint
https://samva.dev/docs/api-reference/contacts/get
```

--------------------------------

### Create and schedule a campaign with REST API

Source: https://samva.dev/docs/channels/email/send-a-campaign

Performs two sequential POST requests to create a campaign and then schedule its run using curl.

```bash
curl -X POST https://api.samva.dev/v1/campaigns \
  -H "X-API-Key: $SAMVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "August newsletter",
    "channel": "email",
    "content": {
      "channel": "email",
      "email": { "subject": "What is new", "html": "<h1>August updates</h1>" }
    },
    "audience": { "includeTags": ["newsletter"] }
  }'

curl -X POST https://api.samva.dev/v1/campaigns/<campaign-id>/runs \
  -H "X-API-Key: $SAMVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scheduledFor": "2026-08-01T09:00:00Z",
    "idempotencyKey": "august-newsletter-v1"
  }'
```

--------------------------------

### GET https://samva.dev/docs/api-reference/contactGroups/list

Source: https://samva.dev/docs/api-reference/contactGroups/list

Retrieves a list of contact groups.

```APIDOC
## GET https://samva.dev/docs/api-reference/contactGroups/list

### Description
Retrieves a list of contact groups.

### Method
GET

### Endpoint
https://samva.dev/docs/api-reference/contactGroups/list
```

--------------------------------

### Configure environment secrets

Source: https://samva.dev/docs/integrations/clerk

Set the required API keys and webhook signing secrets in your server environment.

```sh
SAMVA_API_KEY=samva_sk_live_...
CLERK_WEBHOOK_SIGNING_SECRET=whsec_...
```

--------------------------------

### GET https://samva.dev/docs/api-reference/contactGroups/preview

Source: https://samva.dev/docs/api-reference/contactGroups/preview

Preview the criteria for a contact group.

```APIDOC
## GET https://samva.dev/docs/api-reference/contactGroups/preview

### Description
Preview the criteria for a contact group.

### Method
GET

### Endpoint
https://samva.dev/docs/api-reference/contactGroups/preview
```

--------------------------------

### GET https://samva.dev/docs/api-reference/campaigns/get

Source: https://samva.dev/docs/api-reference/campaigns/get

Retrieves details for a specific campaign.

```APIDOC
## GET https://samva.dev/docs/api-reference/campaigns/get

### Description
Retrieves the details of a specific campaign from the Samva platform.

### Method
GET

### Endpoint
https://samva.dev/docs/api-reference/campaigns/get
```

--------------------------------

### Compose domain modules with Layers

Source: https://samva.dev/docs/integrations/effect-sdk

Build a reusable SamvaLayer and provide it to domain operations.

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

const SamvaLayer = Client.layerFetch({
  apiKey: process.env.SAMVA_API_KEY!,
});

const sendWelcome = (to: string) =>
  Email.send({
    to,
    subject: "Welcome",
    html: "<p>Your workspace is ready.</p>",
    text: "Your workspace is ready.",
  });

await Effect.runPromise(sendWelcome("ada@example.com").pipe(Effect.provide(SamvaLayer)));
```

--------------------------------

### GET /campaigns/run

Source: https://samva.dev/docs/api-reference/campaigns/getRun

Retrieves the details of a specific campaign run.

```APIDOC
## GET /campaigns/run

### Description
Retrieves the details of a specific campaign run from the Samva platform.

### Method
GET

### Endpoint
https://samva.dev/docs/api-reference/campaigns/getRun
```

--------------------------------

### Send an email with Effect

Source: https://samva.dev/docs/integrations/effect-sdk

Demonstrates sending an email by providing the Client.layerFetch to the program.

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

const program = Email.send({
  to: "ada@example.com",
  subject: "Welcome",
  html: "<p>Hi Ada</p>",
  text: "Hi Ada",
}).pipe(
  Effect.provide(
    Client.layerFetch({ apiKey: process.env.SAMVA_API_KEY! }),
  ),
);

const message = await Effect.runPromise(program);
console.log(message.id, message.status);
```

--------------------------------

### POST https://samva.dev/docs/api-reference/email/completeDomainConnect

Source: https://samva.dev/docs/api-reference/email/completeDomainConnect

Completes the one-click DNS return process for a domain.

```APIDOC
## POST https://samva.dev/docs/api-reference/email/completeDomainConnect

### Description
Completes a one-click DNS return process for domain configuration.

### Method
POST

### Endpoint
https://samva.dev/docs/api-reference/email/completeDomainConnect
```

--------------------------------

### GET https://samva.dev/docs/api-reference/analytics/getDeliveryMetrics

Source: https://samva.dev/docs/api-reference/analytics/getDeliveryMetrics

Retrieves delivery metrics for messages.

```APIDOC
## GET https://samva.dev/docs/api-reference/analytics/getDeliveryMetrics

### Description
Retrieves delivery metrics for messages sent through the platform.

### Method
GET

### Endpoint
https://samva.dev/docs/api-reference/analytics/getDeliveryMetrics
```

--------------------------------

### Create Multi-column Layout

Source: https://samva.dev/docs/sml/primitives

Use <Row> and <Column> to arrange content side-by-side, as these are the only supported layout primitives.

```xml
<Row>
  <Column width="50%" class="pr-2">
    <Text>Plan: {{plan}}</Text>
  </Column>
  <Column width="50%" class="pl-2">
    <Text>Seats: {{seats}}</Text>
  </Column>
</Row>
```

--------------------------------

### GET https://samva.dev/docs/api-reference/analytics/getHourlyDistribution

Source: https://samva.dev/docs/api-reference/analytics/getHourlyDistribution

Retrieves the hourly distribution of messages.

```APIDOC
## GET https://samva.dev/docs/api-reference/analytics/getHourlyDistribution

### Description
Retrieves the hourly message distribution data.

### Method
GET

### Endpoint
https://samva.dev/docs/api-reference/analytics/getHourlyDistribution
```

--------------------------------

### GET https://samva.dev/docs/api-reference/analytics/getGeographicDistribution

Source: https://samva.dev/docs/api-reference/analytics/getGeographicDistribution

Retrieves the geographic distribution of messages.

```APIDOC
## GET https://samva.dev/docs/api-reference/analytics/getGeographicDistribution

### Description
Retrieves the geographic distribution of messages for analytics purposes.

### Method
GET

### Endpoint
https://samva.dev/docs/api-reference/analytics/getGeographicDistribution
```

--------------------------------

### Configure API Key

Source: https://samva.dev/docs/integrations/tanstack-start

Set the server-only API key in your environment variables without a VITE_ prefix.

```text
SAMVA_API_KEY=samva_sk_live_your_api_key
```

--------------------------------

### GET /v1/messages/{id}

Source: https://samva.dev/docs/developers/rest-api

Retrieves the details of a specific message by its ID.

```APIDOC
## GET /v1/messages/{id}

### Description
Retrieve a single message.

### Method
GET

### Endpoint
/v1/messages/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the message.
```

--------------------------------

### Manual wiring with samvaEmail

Source: https://samva.dev/docs/integrations/better-auth

Use samvaEmail to manually assign specific Better Auth callbacks and plugin configurations.

```ts
import { betterAuth } from "better-auth";
import { emailOTP, magicLink } from "better-auth/plugins";
import { samvaEmail } from "@samva/better-auth";

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

export const auth = betterAuth({
  emailVerification: samva.emailVerification,
  emailAndPassword: {
    enabled: true,
    sendResetPassword: samva.emailAndPassword.sendResetPassword,
  },
  plugins: [
    emailOTP(samva.plugins.emailOTP),
    magicLink(samva.plugins.magicLink),
  ],
});
```

--------------------------------

### GET /v1/messages/scheduled/{id}

Source: https://samva.dev/docs/channels/email/schedule-an-email

Retrieves details of a specific scheduled message.

```APIDOC
## GET /v1/messages/scheduled/{id}

### Description
Inspects the schedule of a specific message.

### Method
GET

### Endpoint
/v1/messages/scheduled/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the scheduled message.
```

--------------------------------

### POST https://samva.dev/docs/api-reference/media/complete

Source: https://samva.dev/docs/api-reference/media/complete

This endpoint is used to complete a media upload process.

```APIDOC
## POST https://samva.dev/docs/api-reference/media/complete

### Description
Completes a media upload process.

### Method
POST

### Endpoint
https://samva.dev/docs/api-reference/media/complete
```

--------------------------------

### GET /webhooks/{id}

Source: https://samva.dev/docs/api-reference/webhooks/get

Retrieves the details of a specific webhook by its identifier.

```APIDOC
## GET /webhooks/{id}

### Description
Retrieves the details of a specific webhook configuration.

### Method
GET

### Endpoint
https://samva.dev/docs/api-reference/webhooks/get
```

--------------------------------

### GET https://samva.dev/docs/api-reference/templates/listFamilies

Source: https://samva.dev/docs/api-reference/templates/listFamilies

Retrieves a list of all available template families.

```APIDOC
## GET https://samva.dev/docs/api-reference/templates/listFamilies

### Description
Retrieves a list of all available template families.

### Method
GET

### Endpoint
https://samva.dev/docs/api-reference/templates/listFamilies
```

--------------------------------

### Generate shell completions

Source: https://samva.dev/docs/developers/cli

Configure shell completion for Bash, Zsh, or Fish to enable command suggestions.

```bash
# Bash
samva --completions bash >> ~/.bashrc

# Zsh
mkdir -p ~/.zsh/completions
samva --completions zsh > ~/.zsh/completions/_samva
# Add ~/.zsh/completions to fpath, then run `autoload -Uz compinit && compinit` in .zshrc.

# Fish
mkdir -p ~/.config/fish/completions
samva --completions fish > ~/.config/fish/completions/samva.fish

# sh emits the Bash-compatible completion script
samva --completions sh
```

--------------------------------

### Send Email with Go

Source: https://samva.dev/docs/channels/email/send-an-email

Send an email using the standard net/http library.

```go
package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    payload := map[string]any{
        "to":      []map[string]string{{"email": "ada@example.com"}},
        "channel": "email",
        "email": map[string]string{
            "subject": "Welcome to Samva",
            "text":    "Welcome! Thanks for joining.",
        },
    }

    body, _ := json.Marshal(payload)

    req, _ := http.NewRequest("POST",
        "https://api.samva.dev/v1/messages",
        bytes.NewBuffer(body))

    req.Header.Set("X-API-Key", "samva_sk_live_your_api_key")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}
```

--------------------------------

### Build Verification URL

Source: https://samva.dev/docs/integrations/supabase-auth

Construct the Supabase confirmation link using the token hash and action type.

```ts
function buildVerifyURL(emailData: EmailData) {
  const params = new URLSearchParams({
    token: emailData.token_hash,
    type: emailData.email_action_type,
    redirect_to: emailData.redirect_to || emailData.site_url,
  });

  return `https://${Deno.env.get("SUPABASE_PROJECT_REF")}.supabase.co/auth/v1/verify?${params}`;
}
```

--------------------------------

### Configure Email Domains and Tracking

Source: https://samva.dev/docs/developers/cli

Commands to manage sending domains, sender addresses, and tracking defaults, including dry-run options.

```bash
samva email domains list
samva email domains add --domain example.com --dry-run
samva email senders list
samva email senders add --email hello@example.com --dry-run
samva email doctor --json
samva email tracking defaults get
samva email tracking defaults set --opens on --clicks off
samva email design pull
samva email design push --dry-run
```

--------------------------------

### GET https://samva.dev/docs/api-reference/templates/getFamily

Source: https://samva.dev/docs/api-reference/templates/getFamily

Retrieves details for a specific template family.

```APIDOC
## GET https://samva.dev/docs/api-reference/templates/getFamily

### Description
Retrieves information about a specific template family.

### Method
GET

### Endpoint
https://samva.dev/docs/api-reference/templates/getFamily
```

--------------------------------

### Construct an authenticated client with organization scoping

Source: https://samva.dev/docs/developers/oauth-device-login

Use this pattern to initialize the Samva client with an authentication token and a specific organization slug header.

```typescript
import { createClient } from "samva";

const samva = createClient({
  authToken: process.env.SAMVA_AUTH_TOKEN!,
  headers: { "x-org-slug": "acme" },
});
```

--------------------------------

### GET https://samva.dev/docs/api-reference/messages/getEmail

Source: https://samva.dev/docs/api-reference/messages/getEmail

Retrieves the details of a specific email message.

```APIDOC
## GET https://samva.dev/docs/api-reference/messages/getEmail

### Description
Retrieves the details of a specific email message.

### Method
GET

### Endpoint
https://samva.dev/docs/api-reference/messages/getEmail
```

--------------------------------

### GET https://samva.dev/docs/api-reference/operations/get

Source: https://samva.dev/docs/api-reference/operations/get

Retrieves the details of a specific asynchronous operation.

```APIDOC
## GET https://samva.dev/docs/api-reference/operations/get

### Description
Retrieves the status and details of an asynchronous operation.

### Method
GET

### Endpoint
https://samva.dev/docs/api-reference/operations/get
```

--------------------------------

### GET https://samva.dev/docs/api-reference/messages/getStatus

Source: https://samva.dev/docs/api-reference/messages/getStatus

Retrieves the delivery status of a specific message.

```APIDOC
## GET https://samva.dev/docs/api-reference/messages/getStatus

### Description
Retrieves the current delivery status of a message.

### Method
GET

### Endpoint
https://samva.dev/docs/api-reference/messages/getStatus
```

--------------------------------

### Schedule an email with the CLI

Source: https://samva.dev/docs/channels/email/schedule-an-email

Commands for creating, retrieving, and cancelling scheduled messages via the command line.

```bash
samva scheduled-messages create --to ada@example.com \
  --subject "Reminder" --html "<p>See you tomorrow.</p>" \
  --at 2026-08-01T09:00:00Z --timezone America/New_York \
  --idempotency-key reminder-ada-2026-08-01
samva scheduled-messages get <scheduled-message-id>
samva scheduled-messages cancel <scheduled-message-id> --yes
```

--------------------------------

### GET https://samva.dev/docs/api-reference/media/getById

Source: https://samva.dev/docs/api-reference/media/getById

Retrieves a media object by its unique identifier.

```APIDOC
## GET https://samva.dev/docs/api-reference/media/getById

### Description
Retrieves a specific media object from the system using its unique identifier.

### Method
GET

### Endpoint
https://samva.dev/docs/api-reference/media/getById
```
Tokens:
Raw