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 channel 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. The default path is the API, the TypeScript SDK or a POST /v1/messages HTTP call. Samva also has an SMTP front door for software that already speaks the mail protocol; the hosted relay routes accepted messages into the same delivery pipeline as API sends. SMTP exists so legacy clients can adopt Samva without rewriting their 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 exposes a single sending endpoint, POST /v1/messages, reached through two shapes in the SDK: the email-shaped samva.email.send(...) facade for the common case, and the unified samva.messages.send(...) for everything that needs recipients, contacts, and conversations as first-class things. Both compile to the same request, so choosing between them is a question of ergonomics, not capability. The email and the unified API concept covers both shapes and when each one fits.

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. The single-API shape is what makes this 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 organizations 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