# Samva

> Samva is a developer email API for product teams: deliverability, versioned templates, inbound threading, and signed webhooks behind one typed send call.

## Documentation

- [Samva Documentation](https://samva.app/docs): Build email with Samva through task guides, SDKs, integrations, SML, and the REST API reference.
- Channels: Send email: verify your domain, tune deliverability, and send.
  - [Email guides](https://samva.app/docs/channels): Send transactional, scheduled, and campaign email with shared contacts, conversations, and delivery events.
  - Email
    - [Send an email](https://samva.app/docs/channels/email/send-an-email): Send a transactional email with the Samva TypeScript SDK, the REST API, or curl.
    - [Schedule an email](https://samva.app/docs/channels/email/schedule-an-email): Schedule one email for an absolute future instant, then inspect or cancel it before dispatch begins.
    - [Send an email campaign](https://samva.app/docs/channels/email/send-a-campaign): Create an email campaign for an audience, schedule a run, and inspect or control delivery progress.
    - [Verify your sending domain](https://samva.app/docs/channels/email/verify-your-domain): Verify a domain in Samva so you can send email from your own address. Add the domain, publish the DNS records Samva provides, and confirm verification.
    - [Deliverability](https://samva.app/docs/channels/email/deliverability): Understand what affects inbox placement and how Samva helps, from domain authentication to suppression and engagement tracking.
- Platform: Configure email delivery building blocks: webhooks, contacts, templates, campaigns, and scheduling.
  - [Platform](https://samva.app/docs/platform): Configure the contacts, templates, campaigns, scheduling, and webhooks around your email sends.
  - [Email messaging model](https://samva.app/docs/platform/unified-messaging): Send email through one API with shared contacts, conversations, templates, and delivery events.
  - [Receive webhooks](https://samva.app/docs/platform/webhooks): Register a webhook endpoint, subscribe to email events, and verify the X-Webhook-Signature header in your handler.
  - [Webhook event catalog](https://samva.app/docs/platform/webhook-events): Reference every webhook event Samva delivers, its type string, when it fires, and the payload fields your handler receives.
- Developers: Integrate Samva in code — SDK, CLI, MCP, REST, and the concepts behind them.
  - [Send your first email](https://samva.app/docs/developers): Get a Samva API key, install the SDK, and send your first email in a few minutes.

  - **SDKs & Tools**
  - [TypeScript SDK](https://samva.app/docs/developers/typescript-sdk): Reference for the samva TypeScript SDK - client config, email send methods, services, and error shapes.
  - [Use the CLI](https://samva.app/docs/developers/cli): Sign in, select an organization, and send email from your terminal with the Samva CLI.
  - [Connect an agent over MCP](https://samva.app/docs/developers/mcp): Point an AI agent at Samva's hosted Model Context Protocol server to send and track email as tools.
  - [REST API](https://samva.app/docs/developers/rest-api): Reference REST conventions for Samva's email API, covering auth, request and response shapes, status codes, rate limits, pagination, and errors.
  - [Error reference](https://samva.app/docs/developers/error-reference): Reference every error the Samva API can return, its HTTP status, cause, response fields, and how to resolve it.
  - [API keys](https://samva.app/docs/developers/authentication): Reference API key formats, the X-API-Key header, rate limits, and authentication errors for Samva's email API.

  - **Agents**
  - [Agent Skills](https://samva.app/docs/developers/agent-skills): Teach AI agents to choose and use Samva's email surfaces with a published skill served for automatic discovery.

  - **Concepts**
  - [How Samva works](https://samva.app/docs/developers/how-samva-works): Understand how a send flows from your code to the inbox, the core objects that model email, and the single-API philosophy behind Samva.
  - [Email and the unified API](https://samva.app/docs/developers/email-and-the-unified-api): Understand why Samva exposes both an email send facade and a unified messages API, and how each fits your integration.
  - [Organizations and tenancy](https://samva.app/docs/developers/authentication-and-tenancy): How an API key binds to a Samva organization, why every record is tenant-scoped, and how teams and roles share that boundary.
  - [API keys and OAuth sessions](https://samva.app/docs/developers/oauth-device-login): Compare the two ways to authenticate with Samva, durable API keys for servers and OAuth device-login sessions for people.
- SML: Author Samva templates with SML: primitives, class subsets, variables, variants, and compiler diagnostics.
  - [SML](https://samva.app/docs/sml): Author Samva templates with a compiled email language, safe primitives, variables, variants, and diagnostics.
  - [Primitives](https://samva.app/docs/sml/primitives): Reference all 14 SML block primitives plus inline strong, em, and a tags, with attributes and content models.
  - [Class-subset reference](https://samva.app/docs/sml/classes): Every Tailwind-subset utility SML supports, generated from the utility registry, plus the forbidden-utility list with client-specific reasons.
  - [Variables](https://samva.app/docs/sml/variables): Use SML interpolation with {{name}} and ${name}, including where variables are allowed and how they compile.
  - [Conditionals](https://samva.app/docs/sml/conditionals): Branch at send time with SML If and Else primitives, predicate grammar, missing-variable semantics, and compiled markers.
  - [Authoring in TSX](https://samva.app/docs/sml/authoring-tsx): Author one default-exported SML template per TSX file with typed variables, predicate builders, and clear send-time semantics.
  - [Responsive and dark-mode variants](https://samva.app/docs/sml/variants): Use sm: and dark: variants as progressive enhancement while keeping the baseline email correct everywhere.
  - [Error catalog](https://samva.app/docs/sml/errors): Resolve every parse and compile diagnostic SML emits with the source condition, an example, and the fix.
- Integrations: Connect Samva to your stack and third-party services.
  - [Integrations](https://samva.app/docs/integrations): Connect Samva to your stack, your auth provider, your ORM, and the frameworks you already use.
  - [Import the Postman collection](https://samva.app/docs/integrations/import-postman): Import the Samva email API into Postman from the OpenAPI spec and authenticate your requests with an API key.
  - [Verify webhooks](https://samva.app/docs/integrations/webhooks): Verify the signature on Samva's outbound webhooks with the samva SDK's samva/webhooks export.
  - [Next.js](https://samva.app/docs/integrations/nextjs): Send email with Next.js Server Actions, Route Handlers, React Email, and the server-only samva SDK.
  - [Hono on Cloudflare Workers](https://samva.app/docs/integrations/hono-cloudflare-workers): Send email with Hono on Cloudflare Workers using Samva, Worker secrets, and an edge-native fetch send path.
  - [SvelteKit](https://samva.app/docs/integrations/sveltekit): Send email with SvelteKit form actions and +server.ts endpoints using the Samva SDK.
  - [React Email](https://samva.app/docs/integrations/react-email): Render React Email templates and send them with the samva SDK for typed, component-based HTML email.
  - [TanStack Start](https://samva.app/docs/integrations/tanstack-start): Send email with TanStack Start server functions and server routes using the Samva SDK.
  - [Astro](https://samva.app/docs/integrations/astro): Send email from Astro Actions and API endpoints with the samva SDK on Cloudflare, Node, or Vercel.
  - [Effect SDK](https://samva.app/docs/integrations/effect-sdk): Send email from Effect with Samva's Effect-native SDK entrypoint, typed errors, and retry support.
  - [Better Auth](https://samva.app/docs/integrations/better-auth): Send Better Auth transactional email through Samva with the @samva/better-auth package.
  - [Supabase Auth](https://samva.app/docs/integrations/supabase-auth): Send Supabase Auth transactional email through Samva with a signed Send Email Hook.
  - [Clerk](https://samva.app/docs/integrations/clerk): Send Clerk auth and lifecycle email through Samva with verified webhooks and server-only SDK calls.
  - [Prisma](https://samva.app/docs/integrations/prisma): Send transactional email after Prisma writes complete, using the query-then-send pattern.
  - [Auth.js](https://samva.app/docs/integrations/authjs): Send Auth.js and NextAuth magic-link email through Samva with a custom HTTP email provider.
- API Reference
  - [API Reference](https://samva.app/docs/api-reference): Browse the Samva email API endpoints by service, generated from the OpenAPI specification.

  - **Email**
  - Messages
    - [Messages](https://samva.app/docs/api-reference/messages): Send messages and track their delivery lifecycle, the core send endpoint of the Samva API.
    - [Get a message](https://samva.app/docs/api-reference/messages/get)
    - [List message events](https://samva.app/docs/api-reference/messages/getEvents)
    - [Get message delivery status](https://samva.app/docs/api-reference/messages/getStatus)
    - [List messages](https://samva.app/docs/api-reference/messages/list)
    - [Delete a message](https://samva.app/docs/api-reference/messages/remove)
    - [Send a message](https://samva.app/docs/api-reference/messages/send)
  - Email
    - [Email](https://samva.app/docs/api-reference/email): Email-channel infrastructure, sending domains, verified senders, suppression, inbound receiving, and threads.
    - [Add a block entry](https://samva.app/docs/api-reference/email/addBlock)
    - [Add a sending domain](https://samva.app/docs/api-reference/email/addDomain)
    - [Add a sender identity](https://samva.app/docs/api-reference/email/addSender)
    - [Check whether an address is blocked](https://samva.app/docs/api-reference/email/checkBlocked)
    - [Check domain verification status](https://samva.app/docs/api-reference/email/checkDomainVerification)
    - [Check sender verification status](https://samva.app/docs/api-reference/email/checkSenderVerification)
    - [Complete email onboarding](https://samva.app/docs/api-reference/email/completeEmailOnboarding)
    - [Create a forwarding rule](https://samva.app/docs/api-reference/email/createForwardingRule)
    - [Create an email template](https://samva.app/docs/api-reference/email/createTemplate)
    - [Delete a forwarding rule](https://samva.app/docs/api-reference/email/deleteForwardingRule)
    - [Detect a domain's registrar](https://samva.app/docs/api-reference/email/detectRegistrar)
    - [Disable catch-all receiving](https://samva.app/docs/api-reference/email/disableCatchAll)
    - [Enable catch-all receiving](https://samva.app/docs/api-reference/email/enableCatchAll)
    - [Enable inbound email for a domain](https://samva.app/docs/api-reference/email/enableReceiving)
    - [Generate an onboarding API key](https://samva.app/docs/api-reference/email/generateOnboardingApiKey)
    - [Get an email message](https://samva.app/docs/api-reference/email/get)
    - [List blocked email logs](https://samva.app/docs/api-reference/email/getBlockLogs)
    - [Get catch-all configuration](https://samva.app/docs/api-reference/email/getCatchAllConfig)
    - [Get catch-all statistics](https://samva.app/docs/api-reference/email/getCatchAllStats)
    - [Get a sending domain](https://samva.app/docs/api-reference/email/getDomainById)
    - [Get sending domain status](https://samva.app/docs/api-reference/email/getDomainStatus)
    - [List email forwarding logs](https://samva.app/docs/api-reference/email/getForwardingLog)
    - [Get email onboarding state](https://samva.app/docs/api-reference/email/getOnboardingState)
    - [Get email statistics](https://samva.app/docs/api-reference/email/getStats)
    - [Get an email thread](https://samva.app/docs/api-reference/email/getThread)
    - [Get email thread details](https://samva.app/docs/api-reference/email/getThreadById)
    - [Get email thread counts](https://samva.app/docs/api-reference/email/getThreadCounts)
    - [List email thread messages](https://samva.app/docs/api-reference/email/getThreadMessages)
    - [Get message threading metadata](https://samva.app/docs/api-reference/email/getThreadMetadata)
    - [List block entries](https://samva.app/docs/api-reference/email/listBlocks)
    - [List sending domains](https://samva.app/docs/api-reference/email/listDomains)
    - [List forwarding rules](https://samva.app/docs/api-reference/email/listForwardingRules)
    - [List sender identities](https://samva.app/docs/api-reference/email/listSenders)
    - [List email templates](https://samva.app/docs/api-reference/email/listTemplates)
    - [List email threads](https://samva.app/docs/api-reference/email/listThreads)
    - [Remove a block entry](https://samva.app/docs/api-reference/email/removeBlock)
    - [Remove a sending domain](https://samva.app/docs/api-reference/email/removeDomain)
    - [Remove a sender identity](https://samva.app/docs/api-reference/email/removeSender)
    - [Update a block entry](https://samva.app/docs/api-reference/email/updateBlock)
    - [Update catch-all configuration](https://samva.app/docs/api-reference/email/updateCatchAllConfig)
    - [Update a forwarding rule](https://samva.app/docs/api-reference/email/updateForwardingRule)
    - [Verify a sending domain](https://samva.app/docs/api-reference/email/verifyDomain)
  - Templates
    - [Templates](https://samva.app/docs/api-reference/templates): Create and manage reusable, versioned email templates, then send from them by reference.
    - [Add Family Channel](https://samva.app/docs/api-reference/templates/addFamilyChannel)
    - [Approve a template](https://samva.app/docs/api-reference/templates/approve)
    - [Attach Family Member](https://samva.app/docs/api-reference/templates/attachFamilyMember)
    - [Create a template](https://samva.app/docs/api-reference/templates/create)
    - [Create Family](https://samva.app/docs/api-reference/templates/createFamily)
    - [Create Family From Template](https://samva.app/docs/api-reference/templates/createFamilyFromTemplate)
    - [Delete Family](https://samva.app/docs/api-reference/templates/deleteFamily)
    - [Detach Family Member](https://samva.app/docs/api-reference/templates/detachFamilyMember)
    - [Duplicate a template](https://samva.app/docs/api-reference/templates/duplicate)
    - [Get a template](https://samva.app/docs/api-reference/templates/getById)
    - [Get Family](https://samva.app/docs/api-reference/templates/getFamily)
    - [List templates](https://samva.app/docs/api-reference/templates/list)
    - [List Dashboard](https://samva.app/docs/api-reference/templates/listDashboard)
    - [List Families](https://samva.app/docs/api-reference/templates/listFamilies)
    - [Publish a template](https://samva.app/docs/api-reference/templates/publish)
    - [Delete a template](https://samva.app/docs/api-reference/templates/remove)
    - [Rename Family](https://samva.app/docs/api-reference/templates/renameFamily)
    - [Render a template](https://samva.app/docs/api-reference/templates/render)
    - [Restore a template version](https://samva.app/docs/api-reference/templates/restoreVersion)
    - [Spam-check a template or email content](https://samva.app/docs/api-reference/templates/spamCheck)
    - [Send a test email from a template](https://samva.app/docs/api-reference/templates/testSend)
    - [Unpublish a template](https://samva.app/docs/api-reference/templates/unpublish)
    - [Update a template](https://samva.app/docs/api-reference/templates/update)
    - [List template versions](https://samva.app/docs/api-reference/templates/versionHistory)
  - Drafts
    - [Create a draft](https://samva.app/docs/api-reference/drafts/create)
    - [Get a draft](https://samva.app/docs/api-reference/drafts/getById)
    - [List drafts](https://samva.app/docs/api-reference/drafts/list)
    - [Delete a draft](https://samva.app/docs/api-reference/drafts/remove)
    - [Update a draft](https://samva.app/docs/api-reference/drafts/update)
  - ScheduledMessages
    - [Cancel a scheduled message](https://samva.app/docs/api-reference/scheduledMessages/cancel)
    - [Schedule a message](https://samva.app/docs/api-reference/scheduledMessages/create)
    - [Get a scheduled message](https://samva.app/docs/api-reference/scheduledMessages/get)
    - [List scheduled messages](https://samva.app/docs/api-reference/scheduledMessages/list)
  - Campaigns
    - [Archive a campaign](https://samva.app/docs/api-reference/campaigns/archive)
    - [Cancel a campaign run](https://samva.app/docs/api-reference/campaigns/cancelRun)
    - [Create a campaign](https://samva.app/docs/api-reference/campaigns/create)
    - [Get a campaign](https://samva.app/docs/api-reference/campaigns/get)
    - [Get a campaign run](https://samva.app/docs/api-reference/campaigns/getRun)
    - [List campaigns](https://samva.app/docs/api-reference/campaigns/list)
    - [List campaign recipients](https://samva.app/docs/api-reference/campaigns/listRecipients)
    - [List campaign runs](https://samva.app/docs/api-reference/campaigns/listRuns)
    - [Pause a campaign run](https://samva.app/docs/api-reference/campaigns/pauseRun)
    - [Resume a campaign run](https://samva.app/docs/api-reference/campaigns/resumeRun)
    - [Schedule a campaign run](https://samva.app/docs/api-reference/campaigns/scheduleRun)
    - [Update a campaign](https://samva.app/docs/api-reference/campaigns/update)
  - Attachments
    - [Get an attachment download URL](https://samva.app/docs/api-reference/attachments/downloadUrl)
    - [Get an attachment](https://samva.app/docs/api-reference/attachments/getById)
    - [List message attachments](https://samva.app/docs/api-reference/attachments/list)
    - [Delete an attachment](https://samva.app/docs/api-reference/attachments/remove)
    - [Get an attachment thumbnail URL](https://samva.app/docs/api-reference/attachments/thumbnailUrl)
  - Media
    - [Cancel a media upload](https://samva.app/docs/api-reference/media/cancelUpload)
    - [Confirm a media upload](https://samva.app/docs/api-reference/media/confirmUpload)
    - [Upload a media file directly](https://samva.app/docs/api-reference/media/directUpload)
    - [Get a media record](https://samva.app/docs/api-reference/media/getMedia)
    - [Get a media download URL](https://samva.app/docs/api-reference/media/getMediaUrl)
    - [Initialize a media upload](https://samva.app/docs/api-reference/media/initializeUpload)

  - **Contacts & Conversations**
  - Contacts
    - [Contacts](https://samva.app/docs/api-reference/contacts): Manage the people you send to, create, update, segment, and bulk-import contacts.
    - [Bulk delete contacts](https://samva.app/docs/api-reference/contacts/bulkDelete)
    - [Bulk import contacts](https://samva.app/docs/api-reference/contacts/bulkImport)
    - [Bulk update contact status](https://samva.app/docs/api-reference/contacts/bulkUpdateStatus)
    - [Bulk update contact tags](https://samva.app/docs/api-reference/contacts/bulkUpdateTags)
    - [Create a contact](https://samva.app/docs/api-reference/contacts/create)
    - [Export contacts](https://samva.app/docs/api-reference/contacts/export)
    - [Find a contact](https://samva.app/docs/api-reference/contacts/find)
    - [Find or create a contact](https://samva.app/docs/api-reference/contacts/findOrCreate)
    - [Get a contact](https://samva.app/docs/api-reference/contacts/get)
    - [Get contact activity timeline](https://samva.app/docs/api-reference/contacts/getActivityTimeline)
    - [Get contact engagement metrics](https://samva.app/docs/api-reference/contacts/getEngagement)
    - [List a contact's group memberships](https://samva.app/docs/api-reference/contacts/getGroupMemberships)
    - [List contacts](https://samva.app/docs/api-reference/contacts/list)
    - [Delete a contact](https://samva.app/docs/api-reference/contacts/remove)
    - [Update a contact](https://samva.app/docs/api-reference/contacts/update)
  - ContactGroups
    - [Add members to a contact group](https://samva.app/docs/api-reference/contactGroups/addMembers)
    - [Create a contact group](https://samva.app/docs/api-reference/contactGroups/create)
    - [Evaluate a dynamic contact group](https://samva.app/docs/api-reference/contactGroups/evaluateDynamic)
    - [Get a contact group](https://samva.app/docs/api-reference/contactGroups/getById)
    - [List members of a contact group](https://samva.app/docs/api-reference/contactGroups/getMembers)
    - [List contact groups](https://samva.app/docs/api-reference/contactGroups/list)
    - [Preview contact group criteria](https://samva.app/docs/api-reference/contactGroups/preview)
    - [Recount a contact group's members](https://samva.app/docs/api-reference/contactGroups/recount)
    - [Delete a contact group](https://samva.app/docs/api-reference/contactGroups/remove)
    - [Remove members from a contact group](https://samva.app/docs/api-reference/contactGroups/removeMembers)
    - [Update a contact group](https://samva.app/docs/api-reference/contactGroups/update)
  - Conversations
    - [Add contacts to a conversation](https://samva.app/docs/api-reference/conversations/addContacts)
    - [Create a conversation](https://samva.app/docs/api-reference/conversations/create)
    - [Get a conversation](https://samva.app/docs/api-reference/conversations/getById)
    - [List conversations](https://samva.app/docs/api-reference/conversations/list)
    - [Remove contacts from a conversation](https://samva.app/docs/api-reference/conversations/removeContacts)
    - [Update a conversation](https://samva.app/docs/api-reference/conversations/update)

  - **Configuration**
  - Webhooks
    - [Webhooks](https://samva.app/docs/api-reference/webhooks): Subscribe to delivery and inbound events with signed, verifiable webhook payloads.
    - [Create a webhook](https://samva.app/docs/api-reference/webhooks/create)
    - [Get a webhook](https://samva.app/docs/api-reference/webhooks/get)
    - [List webhook delivery logs](https://samva.app/docs/api-reference/webhooks/getLogs)
    - [Get webhook delivery statistics](https://samva.app/docs/api-reference/webhooks/getStats)
    - [List webhooks](https://samva.app/docs/api-reference/webhooks/list)
    - [Rotate a webhook signing secret](https://samva.app/docs/api-reference/webhooks/regenerateSecret)
    - [Delete a webhook](https://samva.app/docs/api-reference/webhooks/remove)
    - [Retry a webhook delivery](https://samva.app/docs/api-reference/webhooks/retryDelivery)
    - [Send a test webhook delivery](https://samva.app/docs/api-reference/webhooks/test)
    - [Update a webhook](https://samva.app/docs/api-reference/webhooks/update)
  - ApiKeys
    - [Create an API key](https://samva.app/docs/api-reference/apiKeys/create)
    - [Get an API key](https://samva.app/docs/api-reference/apiKeys/get)
    - [List API key activity](https://samva.app/docs/api-reference/apiKeys/getActivity)
    - [Get API key usage statistics](https://samva.app/docs/api-reference/apiKeys/getStats)
    - [List API keys](https://samva.app/docs/api-reference/apiKeys/list)
    - [Delete an API key](https://samva.app/docs/api-reference/apiKeys/remove)
    - [Revoke an API key](https://samva.app/docs/api-reference/apiKeys/revoke)
    - [Rotate an API key](https://samva.app/docs/api-reference/apiKeys/rotate)
    - [Update an API key](https://samva.app/docs/api-reference/apiKeys/update)
  - Developers
    - [Get an API request log](https://samva.app/docs/api-reference/developers/getApiLog)
    - [List API request logs](https://samva.app/docs/api-reference/developers/getApiLogs)
  - Organizations
    - [Create a workspace](https://samva.app/docs/api-reference/organizations/create)
    - [Get the current organization](https://samva.app/docs/api-reference/organizations/get)
    - [Get organization usage](https://samva.app/docs/api-reference/organizations/getUsage)
    - [Update the current organization](https://samva.app/docs/api-reference/organizations/update)

  - **Analytics & Reference**
  - Analytics
    - [Export messaging analytics data](https://samva.app/docs/api-reference/analytics/exportData)
    - [Get channel performance analytics](https://samva.app/docs/api-reference/analytics/getChannelStats)
    - [Get message delivery metrics](https://samva.app/docs/api-reference/analytics/getDeliveryMetrics)
    - [Get geographic message distribution](https://samva.app/docs/api-reference/analytics/getGeographicDistribution)
    - [Get hourly message distribution](https://samva.app/docs/api-reference/analytics/getHourlyDistribution)
    - [Get message volume analytics](https://samva.app/docs/api-reference/analytics/getStats)
    - [List top contacts by message volume](https://samva.app/docs/api-reference/analytics/getTopContacts)
  - [OpenAPI Specification](https://samva.app/docs/api-reference/openapi): Generate clients and inspect the complete OpenAPI 3.0 specification for the Samva API.