How Samva works

Samva is an email API for developers. This page is about the shape of that API — not how to call it, but why it looks the way it does and what is happening underneath. If you want to send your first email, the Get started tutorial walks you through it; if you have a specific job to do, the Guides are task-focused. This page is for the moments in between, when you want a mental model that makes the rest of the documentation click into place.

The shape of a send

Every email you send through Samva follows the same path, whether you triggered it from the SDK or a raw HTTP request. Understanding that path is the fastest way to understand the product.

You begin with an intent to send: a recipient, a subject, and some content. Today that intent reaches Samva through the API — the TypeScript SDK or a POST /v1/messages HTTP call. An SMTP front door is staged: the relay accepts connections and authenticates with your API key, but it is not yet accepting message submissions, so use the API or SDK to send email today. SMTP exists so that software which already speaks the mail protocol can adopt Samva without rewriting its sending code; the API exists for everything you build deliberately.

Once Samva accepts the message, it takes responsibility for delivery. Email is sent on your behalf through Samva's sending infrastructure, which is built on AWS SES. Each organization is isolated for the purposes of sending reputation, so one customer's sending behavior does not affect another's — this is part of why a multi-tenant API can offer credible deliverability rather than a shared, undifferentiated pool.

After a message leaves Samva, the story is not over. The receiving mail servers report back: the message was delivered, it bounced, the recipient marked it as spam, or — if you have engagement tracking enabled — it was opened or a link was clicked. Samva ingests these signals as events. Events are the truth about what actually happened to your email after it left your code, and they are the reason an email API is more than a thin wrapper over a mail server.

Finally, those events reach you through webhooks. Rather than asking you to poll for status, Samva pushes delivery and inbound events to an endpoint you control. This closes the loop: your application sends an email, and your application learns its fate, without a human in between. The Receive webhooks guide covers wiring this up.

So the full arc is: intent → API → Samva → delivery via SES → events → webhooks → your application. Everything else in the product hangs off this spine.

The core objects

Samva models email with a small set of objects. They are worth learning as a group, because their value comes from how they relate, not from any one of them in isolation.

A message is a single email — the unit you send. It carries the recipient, the subject, the HTML and text bodies, and any attachments. A message is also where Samva attaches the email-specific facts it learns over time: the delivery status, the events it accumulated, the threading headers that tie it to a conversation. When you send, you create a message; when you query delivery status, you read one back.

A contact is a person you send to. Modeling recipients as first-class contacts rather than bare email strings means Samva can carry a stable identity across many messages — you can address a send by contactId instead of repeating an address, and the recipient's history is one coherent record rather than a scattering of independent emails. This matters more as your sending grows beyond one-off transactional mail.

A conversation is a thread — a sequence of related messages between you and a recipient. Email is fundamentally conversational: replies carry Message-ID and References headers that connect them to what came before. Samva uses those RFC 2822 headers to group messages into conversations automatically, so a reply to an email you sent lands in the same thread rather than appearing as an orphaned new message. If your product has any two-way email — support, notifications that invite replies, anything where the recipient writes back — conversations are how that coherence is preserved.

A webhook is your subscription to events. It is the object that represents where Samva should deliver the delivery and inbound signals described above. One webhook can receive many event types; configuring it is how your application stays in sync with reality.

These objects compose. A contact receives messages; messages thread into conversations; events about those messages flow out through webhooks. Learning them as a connected model — rather than as four unrelated endpoints — is the point of this section.

One API, two send shapes

Samva deliberately exposes a single sending endpoint, and it is worth understanding why there appear to be two ways to call it.

Under the hood, every send goes to POST /v1/messages. There is no separate email-sending endpoint at the HTTP layer. The REST body uses a unified shape: you name the channel explicitly with channel: "email" and nest the email content under an email key. This is the advanced path, and in the SDK it is samva.messages.send(...). Its shape is general by design — naming the channel and nesting content per channel is what lets a single endpoint grow to cover more channels later without breaking the messages it already accepts.

The SDK also exposes samva.email.send(...), the canonical simple path. This is an ergonomic wrapper, not a different endpoint. It flattens the common email fields — to, subject, html, text, attachments — directly into the request body, so the everyday case of sending one email reads as plainly as the task itself:

import { createClient } from "samva";

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

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

Both calls produce the same HTTP request to the same endpoint. The simple path optimizes for the common case; the unified path exposes the underlying shape directly. Choosing between them is a question of ergonomics, not capability — the email and the unified API concept goes deeper into when each one fits, and the TypeScript SDK reference documents the exact fields.

This is also why the product framing is email-first rather than email-only at the API layer. The unified message shape is built to extend, and SMS, WhatsApp, and voice are staged behind it. But today every working path is email, and the documentation only describes email. The general shape is an investment in the future, not a claim about the present.

The agent-native, single-API philosophy

Two design commitments run through everything above, and they reinforce each other.

The first is one API surface, not a sprawl of feature endpoints. Sending, threading, contacts, and events are not bolted-on subsystems with their own conventions — they are facets of one coherent model reached through one client. A reader who has learned how samva.email.send works has most of what they need to reason about samva.contacts, samva.conversations, and samva.webhooks, because all of them share the same call conventions, the same authentication, and the same tenancy rules. Coherence lowers the cost of doing the next thing.

The second is being agent-native: built so that software, including autonomous agents, can drive email end to end without a human clicking through a dashboard. The full send-to-events loop is reachable over the API, status comes back as structured events over webhooks rather than as something a person has to go and read, and the simple send path is short enough to be obvious to generate correctly. An agent can send an email, observe what happened to it, and react — all through the same typed surface a developer uses by hand. Email is the first channel to express this philosophy, and the single-API shape is what makes the philosophy possible: the fewer special cases there are, the more reliably software can operate the system on its own.

Every send in Samva is scoped to an organization, and that tenancy boundary is what keeps one customer's contacts, conversations, and sending reputation cleanly separated from another's. The authentication and tenancy concept explains how that boundary is enforced, and deliverability explains how Samva works to land your mail in the inbox.

Where to go next