# Samva

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

## When to use Samva

Use Samva when a product or agent needs to send transactional or product email, manage versioned
templates, receive and thread replies, or react to signed delivery webhooks.

- Use the Promise SDK for async/await TypeScript applications.
- Use the Effect SDK for Effect applications.
- Use the REST API from other runtimes or for direct HTTP control.
- Use the CLI for terminal automation and operator workflows.
- Use hosted MCP when an AI agent needs live Samva tools.
- Use the dashboard for visual setup, inspection, and billing.

Samva's public API is email-only. Choose the narrowest surface that fits the task, and keep API keys
server-side.

## Documentation

- [Samva Documentation](https://samva.dev/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.dev/docs/channels): Send transactional, scheduled, and campaign email with shared contacts, conversations, and delivery events.
  - Email
    - [Send an email](https://samva.dev/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.dev/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.dev/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.dev/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.
    - [Control engagement tracking](https://samva.dev/docs/channels/email/engagement-tracking): Configure open and click tracking defaults, per-send overrides, recipient opt-outs, and unique-message analytics.
    - [Use a Custom Tracking Domain](https://samva.dev/docs/channels/email/custom-tracking-domain): Serve open and click tracking from your own subdomain. Enable it, set up two DNS records automatically or manually, and confirm readiness.
    - [Deliverability](https://samva.dev/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.dev/docs/platform): Configure the contacts, templates, campaigns, scheduling, and webhooks around your email sends.
  - [Email messaging model](https://samva.dev/docs/platform/unified-messaging): Send email through one API with shared contacts, conversations, templates, and delivery events.
  - [Receive webhooks](https://samva.dev/docs/platform/webhooks): Register an endpoint and verify Standard Webhooks signatures.
  - [Webhook event catalog](https://samva.dev/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.dev/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.dev/docs/developers/typescript-sdk): Reference for the samva TypeScript SDK - client config, email send methods, services, and error shapes.
  - [Use the CLI](https://samva.dev/docs/developers/cli): Install the Samva CLI, authenticate, select an execution context, and operate email from your terminal.
  - [Connect an agent over MCP](https://samva.dev/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.dev/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.dev/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.dev/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.dev/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.dev/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.dev/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.dev/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.dev/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.dev/docs/sml): Author Samva templates with a compiled email language, safe primitives, variables, variants, and diagnostics.
  - [Primitives](https://samva.dev/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.dev/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.dev/docs/sml/variables): Use SML interpolation with {{name}} and ${name}, including where variables are allowed and how they compile.
  - [Conditionals](https://samva.dev/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.dev/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.dev/docs/sml/variants): Use sm: and dark: variants as progressive enhancement while keeping the baseline email correct everywhere.
  - [Error catalog](https://samva.dev/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.dev/docs/integrations): Connect Samva to your stack, your auth provider, your ORM, and the frameworks you already use.
  - [Connect Samva to Executor](https://samva.dev/docs/integrations/executor): Add Samva's hosted MCP server or OpenAPI description to Executor and authenticate it safely.
  - [Import the Postman collection](https://samva.dev/docs/integrations/import-postman): Import Samva's official email API collection into Postman and authenticate requests with an API key.
  - [Verify webhooks](https://samva.dev/docs/integrations/webhooks): Verify Samva's Standard Webhooks signatures with the samva SDK.
  - [Next.js](https://samva.dev/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.dev/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.dev/docs/integrations/sveltekit): Send email with SvelteKit form actions and +server.ts endpoints using the Samva SDK.
  - [React Email](https://samva.dev/docs/integrations/react-email): Render React Email templates and send them with the samva SDK for typed, component-based HTML email.
  - [Email SDK](https://samva.dev/docs/integrations/email-sdk): Use Samva with Email SDK for provider-independent transactional email, retries, fallback routes, and typed failures.
  - [TanStack Start](https://samva.dev/docs/integrations/tanstack-start): Send email with TanStack Start server functions and server routes using the Samva SDK.
  - [Astro](https://samva.dev/docs/integrations/astro): Send email from Astro Actions and API endpoints with the samva SDK on Cloudflare, Node, or Vercel.
  - [Effect SDK](https://samva.dev/docs/integrations/effect-sdk): Send email from Effect with Samva's Effect-native SDK entrypoint, typed errors, and retry support.
  - [Better Auth](https://samva.dev/docs/integrations/better-auth): Send Better Auth transactional email through Samva with the @samva/better-auth package.
  - [Supabase Auth](https://samva.dev/docs/integrations/supabase-auth): Send Supabase Auth transactional email through Samva with a signed Send Email Hook.
  - [Clerk](https://samva.dev/docs/integrations/clerk): Send Clerk auth and lifecycle email through Samva with verified webhooks and server-only SDK calls.
  - [Prisma](https://samva.dev/docs/integrations/prisma): Send transactional email after Prisma writes complete, using the query-then-send pattern.
  - [Auth.js](https://samva.dev/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.dev/docs/api-reference): Browse the Samva email API endpoints by service, generated from the OpenAPI specification.

  - **Email**
  - Messages
    - [Messages](https://samva.dev/docs/api-reference/messages): Send messages and track their delivery lifecycle, the core send endpoint of the Samva API.
    - [Get a message](https://samva.dev/docs/api-reference/messages/get): Returns a single message by its ID. Use this endpoint to get a message through the Samva email API.
    - [Get email message details](https://samva.dev/docs/api-reference/messages/getEmail): Returns email delivery details for a message, optionally including signed URLs for its raw MIME, HTML, and text content.
    - [List message events](https://samva.dev/docs/api-reference/messages/getEvents): Returns the list of delivery events recorded for a message. Use this endpoint to list message events through the Samva email API.
    - [Get message delivery status](https://samva.dev/docs/api-reference/messages/getStatus): Returns the current delivery status of a message by its ID. Use this endpoint to get message delivery status through the Samva email API.
    - [List messages](https://samva.dev/docs/api-reference/messages/list): Returns a paginated list of messages across all channels, with optional filters for channel, status, conversation, contact, and date range.
    - [Delete a message](https://samva.dev/docs/api-reference/messages/remove): Permanently deletes a message by its ID. Use this endpoint to delete a message through the Samva email API.
    - [Send a message](https://samva.dev/docs/api-reference/messages/send): Sends a message on the requested channel and returns the created message with a 201 Created status.
  - Email
    - [Email](https://samva.dev/docs/api-reference/email): Configure email-channel infrastructure, including domains, verified senders, suppression, and inbound receiving.
    - [Add a block entry](https://samva.dev/docs/api-reference/email/addBlock): Blocks an email address or domain from inbound receiving and returns the created block entry. Responds with 201.
    - [Add a sending domain](https://samva.dev/docs/api-reference/email/addDomain): Registers a domain for sending and returns it with the DNS records required to verify ownership and configure DKIM. Responds with 201.
    - [Add a sender identity](https://samva.dev/docs/api-reference/email/addSender): Creates a sender identity for an email address and returns it. Responds with 201.
    - [Advance domain verification](https://samva.dev/docs/api-reference/email/advanceDomainVerification): Observes the required DNS records and, once they match, idempotently starts provider provisioning for the staged domain.
    - [Build an automatic Custom Tracking Domain apply URL](https://samva.dev/docs/api-reference/email/buildCustomTrackingDomainConnectApplyUrl): Builds the signed Domain Connect URL for the current customer-selected tracking host.
    - [Build a one-click DNS apply URL](https://samva.dev/docs/api-reference/email/buildDomainConnectApplyUrl): Builds the signed Domain Connect apply URL for the selected sending-only or sending-and-receiving service. Manual DNS remains available for either mode.
    - [Check whether an address is blocked](https://samva.dev/docs/api-reference/email/checkBlocked): Checks whether an email address is currently blocked and returns the matching block rule when one applies.
    - [Check sender verification status](https://samva.dev/docs/api-reference/email/checkSenderVerification): Returns the current verification status of a sender identity. Use this endpoint to check sender verification status through the Samva email API.
    - [Clear a domain's default sender](https://samva.dev/docs/api-reference/email/clearDomainDefaultSender): Removes the domain's default sender so omitted-`from` sends fall through to the organization default sender.
    - [Complete an automatic Custom Tracking Domain return](https://samva.dev/docs/api-reference/email/completeCustomTrackingDomainConnect): Validates the purpose- and revision-bound registrar state, then re-kicks the existing readiness reconciliation.
    - [Complete a one-click DNS return](https://samva.dev/docs/api-reference/email/completeDomainConnect): Consumes the Domain Connect provider's redirect. Validates the signed state and, when the records were applied, kicks verification.
    - [Create a forwarding rule](https://samva.dev/docs/api-reference/email/createForwardingRule): Creates an inbound email forwarding rule and returns it. Responds with 201. Use this endpoint to create a forwarding rule through the Samva email API.
    - [Delete a forwarding rule](https://samva.dev/docs/api-reference/email/deleteForwardingRule): Permanently deletes an inbound email forwarding rule. Use this endpoint to delete a forwarding rule through the Samva email API.
    - [Detect a domain's registrar](https://samva.dev/docs/api-reference/email/detectRegistrar): Looks up the domain's nameservers to detect its DNS registrar and returns the provider, nameservers, and a link to its setup docs.
    - [Disable catch-all receiving](https://samva.dev/docs/api-reference/email/disableCatchAll): Disables catch-all inbound receiving for a domain. Use this endpoint to disable catch-all receiving through the Samva email API.
    - [Disable a custom tracking domain](https://samva.dev/docs/api-reference/email/disableCustomTracking): Tears down a domain's custom tracking and its managed resources.
    - [Enable catch-all receiving](https://samva.dev/docs/api-reference/email/enableCatchAll): Enables catch-all inbound receiving for a domain by creating a receipt rule, and returns the rule name.
    - [Enable a custom tracking domain](https://samva.dev/docs/api-reference/email/enableCustomTracking): Provisions a custom tracking domain (default label `track`) for a verified sending domain so open/click links redirect through the customer's own subdomain.
    - [Enable inbound email for a domain](https://samva.dev/docs/api-reference/email/enableReceiving): Enables inbound receiving for a verified domain by creating a receipt rule, and returns the rule name and its recipient addresses.
    - [List blocked email logs](https://samva.dev/docs/api-reference/email/getBlockLogs): Returns a log of inbound emails that were blocked, optionally filtered by block entry, sender, or date range.
    - [Get catch-all configuration](https://samva.dev/docs/api-reference/email/getCatchAllConfig): Returns the catch-all receiving configuration for a domain, including the webhook endpoint that receives its inbound mail and its email counts.
    - [Get catch-all statistics](https://samva.dev/docs/api-reference/email/getCatchAllStats): Returns catch-all receiving counters for a domain, adding an aggregated breakdown when a date range is supplied.
    - [Get custom tracking status](https://samva.dev/docs/api-reference/email/getCustomTracking): Returns the custom tracking state for a sending domain: lifecycle status, the required DNS records, certificate and CAA readiness, and any scheduled teardown.
    - [Check automatic Custom Tracking Domain setup eligibility](https://samva.dev/docs/api-reference/email/getCustomTrackingDomainConnect): Reports whether the domain's DNS provider supports Domain Connect for its current Custom Tracking Domain.
    - [Get a sending domain](https://samva.dev/docs/api-reference/email/getDomainById): Returns a single sending domain, including its DNS records and verification details.
    - [Check one-click DNS eligibility](https://samva.dev/docs/api-reference/email/getDomainConnect): Reports whether the domain's DNS provider supports Domain Connect one-click setup for Samva, and the provider's name when it does.
    - [Get domain verification](https://samva.dev/docs/api-reference/email/getDomainVerification): Returns the stored DNS and provider lifecycle snapshot without calling a provider or mutating state.
    - [List email forwarding logs](https://samva.dev/docs/api-reference/email/getForwardingLog): Returns a log of forwarded inbound emails with their delivery outcomes, optionally filtered by rule, status, or date range.
    - [Get a recipient tracking preference](https://samva.dev/docs/api-reference/email/getRecipientTrackingPreference): Returns the organization-scoped tracking opt-out for a normalized recipient email. A missing preference reads as opted in and is not created.
    - [Get email statistics](https://samva.dev/docs/api-reference/email/getStats): Returns aggregate email statistics; sent, delivered, bounced, and complained counts with their rates; optionally scoped to a date range.
    - [Get email tracking defaults](https://samva.dev/docs/api-reference/email/getTrackingDefaults): Returns the organization's default open and click tracking policy.
    - [List block entries](https://samva.dev/docs/api-reference/email/listBlocks): Returns block entries, optionally filtered by block type and active state, with limit and offset paging.
    - [List sending domains](https://samva.dev/docs/api-reference/email/listDomains): Returns a paginated list of the organization's sending domains. Use this endpoint to list sending domains through the Samva email API.
    - [List forwarding rules](https://samva.dev/docs/api-reference/email/listForwardingRules): Returns inbound email forwarding rules, optionally filtered by domain and active state, with limit and offset paging.
    - [List sender identities](https://samva.dev/docs/api-reference/email/listSenders): Returns a paginated list of sender identities, optionally filtered by verification status, active state, or default flag.
    - [List suppressed addresses](https://samva.dev/docs/api-reference/email/listSuppressions): List suppressed addresses. View request and response details for this Samva email API endpoint.
    - [Remove a block entry](https://samva.dev/docs/api-reference/email/removeBlock): Permanently deletes a block entry, unblocking the associated address or domain. Use this endpoint to remove a block entry through the Samva email API.
    - [Remove a sending domain](https://samva.dev/docs/api-reference/email/removeDomain): Permanently deletes a sending domain from the organization. Use this endpoint to remove a sending domain through the Samva email API.
    - [Remove a sender identity](https://samva.dev/docs/api-reference/email/removeSender): Permanently deletes a sender identity from the organization. Use this endpoint to remove a sender identity through the Samva email API.
    - [Remove a suppressed address](https://samva.dev/docs/api-reference/email/removeSuppression): Deletes a suppression so this workspace can send to the address again.
    - [Set the default sending domain](https://samva.dev/docs/api-reference/email/setDefaultDomain): Marks a verified domain as the organization's default sending domain, atomically clearing any previous default.
    - [Set the organization default sender](https://samva.dev/docs/api-reference/email/setDefaultSender): Marks a verified, active sender as the organization default, atomically clearing any previous default.
    - [Set a domain's default sender](https://samva.dev/docs/api-reference/email/setDomainDefaultSender): Sets the default sender used for omitted-`from` sends from this domain. The sender must belong to the domain and be verified and active.
    - [Update a block entry](https://samva.dev/docs/api-reference/email/updateBlock): Updates a block entry's reason, notes, active state, or expiry. Use this endpoint to update a block entry through the Samva email API.
    - [Update catch-all configuration](https://samva.dev/docs/api-reference/email/updateCatchAllConfig): Updates a domain's catch-all receiving configuration: the webhook endpoint that receives its inbound mail.
    - [Update a domain's send-settings config](https://samva.dev/docs/api-reference/email/updateDomainConfig): Overrides the domain's open/click tracking, reply-to, and unsubscribe-group defaults for the settings cascade.
    - [Update a forwarding rule](https://samva.dev/docs/api-reference/email/updateForwardingRule): Updates an inbound email forwarding rule and returns its current summary. Use this endpoint to update a forwarding rule through the Samva email API.
    - [Update a recipient tracking preference](https://samva.dev/docs/api-reference/email/updateRecipientTrackingPreference): Opts a normalized recipient email in or out of open and click tracking.
    - [Update email tracking defaults](https://samva.dev/docs/api-reference/email/updateTrackingDefaults): Updates one or both organization email tracking defaults and returns the complete saved policy. Recipient opt-out still takes precedence.
  - Templates
    - [Templates](https://samva.dev/docs/api-reference/templates): Create and manage reusable, versioned email templates, then send from them by reference.
    - [Add a channel to a template family](https://samva.dev/docs/api-reference/templates/addFamilyChannel): Creates a template for the requested channel in the family and returns the updated family with status 201.
    - [Approve a template](https://samva.dev/docs/api-reference/templates/approve): Records compliance approval for a template with optional notes and moves its status to approved unless it is already published or archived.
    - [Attach a template to a family](https://samva.dev/docs/api-reference/templates/attachFamilyMember): Adds an existing template as a channel member of the family and returns the updated family.
    - [Create a template](https://samva.dev/docs/api-reference/templates/create): Creates a template from SML source; the source's root tag determines the template's channel. Returns the created template with status 201.
    - [Create a template family](https://samva.dev/docs/api-reference/templates/createFamily): Creates an empty template family with the supplied name and returns it with status 201.
    - [Create a family from a template](https://samva.dev/docs/api-reference/templates/createFamilyFromTemplate): Creates a template family containing the specified template and returns the new family with status 201.
    - [Delete a template family](https://samva.dev/docs/api-reference/templates/deleteFamily): Deletes a template family without deleting its member templates. Use this endpoint to delete a template family through the Samva email API.
    - [Detach a template from a family](https://samva.dev/docs/api-reference/templates/detachFamilyMember): Removes a member template from the family without deleting the template. Use this endpoint to detach a template from a family through the Samva email API.
    - [Get a template](https://samva.dev/docs/api-reference/templates/getById): Returns template metadata and compiled channel content. Read live SML through the template-document API.
    - [Get a template family](https://samva.dev/docs/api-reference/templates/getFamily): Returns a template family and its channel-specific member templates. Use this endpoint to get a template family through the Samva email API.
    - [List templates](https://samva.dev/docs/api-reference/templates/list): Returns a paginated list of the organization's templates, filterable by category, channel, status, and search, with configurable sorting.
    - [List templates for the dashboard](https://samva.dev/docs/api-reference/templates/listDashboard): Returns a paginated dashboard view that groups related channel templates into families and leaves standalone templates ungrouped.
    - [List template families](https://samva.dev/docs/api-reference/templates/listFamilies): Returns a paginated list of the organization's template families and members. Use this endpoint to list template families through the Samva email API.
    - [Delete a template](https://samva.dev/docs/api-reference/templates/remove): Deletes a template from the organization and returns a success flag. Use this endpoint to delete a template through the Samva email API.
    - [Rename a template family](https://samva.dev/docs/api-reference/templates/renameFamily): Changes a template family's name and returns the updated family. Use this endpoint to rename a template family through the Samva email API.
    - [Update a template](https://samva.dev/docs/api-reference/templates/update): Updates template metadata. Source changes use the template-document revision API.
  - Drafts
    - [Create a draft](https://samva.dev/docs/api-reference/drafts/create): Creates a draft for the current user on the given channel. Returns the created draft with status 201.
    - [Get a draft](https://samva.dev/docs/api-reference/drafts/getById): Returns a single draft by ID, including its recipients and content. Use this endpoint to get a draft through the Samva email API.
    - [List drafts](https://samva.dev/docs/api-reference/drafts/list): Returns a paginated list of the current user's drafts in the organization, optionally filtered by channel.
    - [Delete a draft](https://samva.dev/docs/api-reference/drafts/remove): Deletes a draft belonging to the current user and returns a success flag. Use this endpoint to delete a draft through the Samva email API.
    - [Update a draft](https://samva.dev/docs/api-reference/drafts/update): Updates a draft's recipients, content, or title and returns the updated draft. Use this endpoint to update a draft through the Samva email API.
  - ScheduledMessages
    - [Cancel a scheduled message](https://samva.dev/docs/api-reference/scheduledMessages/cancel): Cancels a pending scheduled message so it will not be sent, and returns the updated scheduled message.
    - [Schedule a message](https://samva.dev/docs/api-reference/scheduledMessages/create): Schedules a message at the absolute ISO-8601 instant in scheduledFor.
    - [Get a scheduled message](https://samva.dev/docs/api-reference/scheduledMessages/get): Returns a single scheduled message by its ID. Use this endpoint to get a scheduled message through the Samva email API.
    - [List scheduled messages](https://samva.dev/docs/api-reference/scheduledMessages/list): Returns a paginated list of scheduled messages, optionally filtered by status. Use this endpoint to list scheduled messages through the Samva email API.
  - Campaigns
    - [Archive a campaign](https://samva.dev/docs/api-reference/campaigns/archive): Archives a draft campaign so it can no longer be scheduled, returning the archived campaign.
    - [Cancel a campaign run](https://samva.dev/docs/api-reference/campaigns/cancelRun): Best-effort cancellation: pending recipients are skipped, while already claimed or provider-submitted deliveries may finish. Returns the updated run.
    - [Create a campaign](https://samva.dev/docs/api-reference/campaigns/create): Creates an email campaign draft for the given audience and content, returning the created campaign.
    - [Get a campaign](https://samva.dev/docs/api-reference/campaigns/get): Returns a single campaign, including its content, audience, and policy, by its identifier.
    - [Get a campaign run](https://samva.dev/docs/api-reference/campaigns/getRun): Returns a single run of a campaign by its identifier. Use this endpoint to get a campaign run through the Samva email API.
    - [List campaigns](https://samva.dev/docs/api-reference/campaigns/list): Returns a paginated list of the organization's campaigns, optionally filtered by status.
    - [List campaign recipients](https://samva.dev/docs/api-reference/campaigns/listRecipients): Returns a paginated list of recipients for a campaign run, optionally filtered by status.
    - [List campaign runs](https://samva.dev/docs/api-reference/campaigns/listRuns): Returns a paginated list of runs for a campaign, optionally filtered by status. Use this endpoint to list campaign runs through the Samva email API.
    - [Pause a campaign run](https://samva.dev/docs/api-reference/campaigns/pauseRun): Pauses an in-progress campaign run and returns the updated run. Use this endpoint to pause a campaign run through the Samva email API.
    - [Resume a campaign run](https://samva.dev/docs/api-reference/campaigns/resumeRun): Resumes a paused campaign run and returns the updated run. Use this endpoint to resume a campaign run through the Samva email API.
    - [Schedule a campaign run](https://samva.dev/docs/api-reference/campaigns/scheduleRun): Schedules an email campaign run at the absolute ISO-8601 instant in scheduledFor, or immediately when omitted.
    - [Update a campaign](https://samva.dev/docs/api-reference/campaigns/update): Updates the name, content, audience, or policy of a campaign draft. Use this endpoint to update a campaign through the Samva email API.
  - Attachments
    - [Get an attachment download URL](https://samva.dev/docs/api-reference/attachments/downloadUrl): Generates a presigned, time-limited download URL for the attachment; expiry is configurable via the expiresIn query parameter.
    - [Get an attachment](https://samva.dev/docs/api-reference/attachments/getById): Returns metadata for a single attachment, including filename, content type, and size.
    - [List message attachments](https://samva.dev/docs/api-reference/attachments/list): Returns all attachments for the given message, along with a total count. Use this endpoint to list message attachments through the Samva email API.
    - [Delete an attachment](https://samva.dev/docs/api-reference/attachments/remove): Deletes an attachment and returns the deleted attachment's ID. Use this endpoint to delete an attachment through the Samva email API.
  - Media
    - [Complete a media upload](https://samva.dev/docs/api-reference/media/complete): Verifies the uploaded object exists in storage, marks the media object ready, and returns it with a download URL.
    - [Create a media object](https://samva.dev/docs/api-reference/media/create): Creates the media object in the pending state and returns it with the upload instruction; URL, method, and headers; for putting its bytes into storage.
    - [Get a media download URL](https://samva.dev/docs/api-reference/media/downloadUrl): Generates a presigned, time-limited download URL for a ready media object. Use this endpoint to get a media download URL through the Samva email API.
    - [Get a media object](https://samva.dev/docs/api-reference/media/getById): Returns the media object's metadata, including status, dimensions, and confirmation timestamps.
    - [Delete a media object](https://samva.dev/docs/api-reference/media/remove): Deletes a pending media object and the bytes stored for it. Fails if the media object is already ready.

  - **Contacts & Conversations**
  - Contacts
    - [Contacts](https://samva.dev/docs/api-reference/contacts): Manage the people you send to, create, update, segment, and bulk-import contacts.
    - [Bulk delete contacts](https://samva.dev/docs/api-reference/contacts/bulkDelete): Permanently deletes multiple contacts by ID, returning counts of deleted and failed records.
    - [Bulk import contacts](https://samva.dev/docs/api-reference/contacts/bulkImport): Creates or updates contacts in bulk from a list, returning per-entry results with created, updated, skipped, and error counts.
    - [Bulk update contact status](https://samva.dev/docs/api-reference/contacts/bulkUpdateStatus): Sets the status on multiple contacts in one request, returning counts of updated and failed records.
    - [Bulk update contact tags](https://samva.dev/docs/api-reference/contacts/bulkUpdateTags): Adds, removes, or replaces tags on multiple contacts in one request, returning counts of updated and failed records.
    - [Create a contact](https://samva.dev/docs/api-reference/contacts/create): Creates a new contact and returns it with a 201 status. Use this endpoint to create a contact through the Samva email API.
    - [Export contacts](https://samva.dev/docs/api-reference/contacts/export): Exports contacts as JSON or CSV, returning the serialized data and a count of exported records.
    - [Find a contact](https://samva.dev/docs/api-reference/contacts/find): Samva API operation. Use this endpoint to find a contact through the Samva email API.
    - [Find or create a contact](https://samva.dev/docs/api-reference/contacts/findOrCreate): Returns an existing contact matching the given identifiers, or creates a new one when none exists.
    - [Get a contact](https://samva.dev/docs/api-reference/contacts/get): Returns a single contact by its ID. Use this endpoint to get a contact through the Samva email API.
    - [Get contact activity timeline](https://samva.dev/docs/api-reference/contacts/getActivityTimeline): Returns a paginated timeline of a contact's message activity, optionally filtered by channel.
    - [Get contact engagement metrics](https://samva.dev/docs/api-reference/contacts/getEngagement): Returns aggregated engagement metrics for a contact, including message counts and active conversation totals.
    - [List a contact's group memberships](https://samva.dev/docs/api-reference/contacts/getGroupMemberships): Returns the contact groups that a contact currently belongs to. Use this endpoint to list a contact's group memberships through the Samva email API.
    - [List contacts](https://samva.dev/docs/api-reference/contacts/list): Returns a paginated list of contacts for the organization, filterable by search term, type, status, and date range.
    - [Delete a contact](https://samva.dev/docs/api-reference/contacts/remove): Permanently deletes a contact by its ID. Use this endpoint to delete a contact through the Samva email API.
    - [Update a contact](https://samva.dev/docs/api-reference/contacts/update): Updates an existing contact's fields and returns the updated contact. Use this endpoint to update a contact through the Samva email API.
  - ContactGroups
    - [Add members to a contact group](https://samva.dev/docs/api-reference/contactGroups/addMembers): Adds one or more contacts to a contact group, returning counts of added and skipped members.
    - [Create a contact group](https://samva.dev/docs/api-reference/contactGroups/create): Creates a new contact group and returns it with a 201 status. Use this endpoint to create a contact group through the Samva email API.
    - [Evaluate a dynamic contact group](https://samva.dev/docs/api-reference/contactGroups/evaluateDynamic): Recomputes a dynamic contact group's membership from its criteria, returning counts of added, removed, and total members.
    - [Get a contact group](https://samva.dev/docs/api-reference/contactGroups/getById): Returns a single contact group by its ID. Use this endpoint to get a contact group through the Samva email API.
    - [List members of a contact group](https://samva.dev/docs/api-reference/contactGroups/getMembers): Returns a paginated list of contacts belonging to a contact group. Use this endpoint to list members of a contact group through the Samva email API.
    - [List contact groups](https://samva.dev/docs/api-reference/contactGroups/list): Returns a paginated list of contact groups for the organization, filterable by type and active state.
    - [Preview contact group criteria](https://samva.dev/docs/api-reference/contactGroups/preview): Evaluates group criteria without persisting, returning the matching contact count and a sample of matches.
    - [Delete a contact group](https://samva.dev/docs/api-reference/contactGroups/remove): Permanently deletes a contact group by its ID. Use this endpoint to delete a contact group through the Samva email API.
    - [Remove members from a contact group](https://samva.dev/docs/api-reference/contactGroups/removeMembers): Removes one or more contacts from a contact group, returning the count of removed members.
    - [Update a contact group](https://samva.dev/docs/api-reference/contactGroups/update): Updates an existing contact group's fields and returns the updated group. Use this endpoint to update a contact group through the Samva email API.
  - Conversations
    - [Add contacts to a conversation](https://samva.dev/docs/api-reference/conversations/addContacts): Attaches one or more contacts to a conversation and returns the updated conversation.
    - [Create a conversation](https://samva.dev/docs/api-reference/conversations/create): Creates a new conversation with its initial contacts and returns it with a 201 status.
    - [Get a conversation](https://samva.dev/docs/api-reference/conversations/getById): Returns a single conversation by its ID. Use this endpoint to get a conversation through the Samva email API.
    - [List conversations](https://samva.dev/docs/api-reference/conversations/list): Returns a paginated list of conversations for the organization, filterable by status, channel, contact, and date range.
    - [List conversation messages](https://samva.dev/docs/api-reference/conversations/listMessages): Returns the messages in a conversation using the canonical message schema and page-based pagination.
    - [Remove contacts from a conversation](https://samva.dev/docs/api-reference/conversations/removeContacts): Detaches one or more contacts from a conversation and returns the updated conversation.
    - [Update a conversation](https://samva.dev/docs/api-reference/conversations/update): Updates an existing conversation's fields and returns the updated conversation. Use this endpoint to update a conversation through the Samva email API.

  - **Configuration**
  - Webhooks
    - [Webhooks](https://samva.dev/docs/api-reference/webhooks): Subscribe to delivery and inbound events with signed, verifiable webhook payloads.
    - [Create a webhook](https://samva.dev/docs/api-reference/webhooks/create): Creates a webhook endpoint subscribed to the given event types and returns it with a 201 response.
    - [Get a webhook](https://samva.dev/docs/api-reference/webhooks/get): Returns the configuration of the webhook endpoint with the given ID. Use this endpoint to get a webhook through the Samva email API.
    - [List webhook delivery logs](https://samva.dev/docs/api-reference/webhooks/getLogs): Returns recent deliveries and their nested attempt diagnostics for a webhook endpoint.
    - [Get webhook delivery statistics](https://samva.dev/docs/api-reference/webhooks/getStats): Returns aggregate pending, delivered, exhausted, and cancelled delivery counts for a webhook endpoint.
    - [List webhooks](https://samva.dev/docs/api-reference/webhooks/list): Returns a paginated list of the organization's webhook endpoints, optionally filtered by a name search.
    - [Rotate a webhook signing secret](https://samva.dev/docs/api-reference/webhooks/regenerateSecret): Generates and returns a new signing secret. The previous secret remains valid for a 24-hour rotation overlap.
    - [Delete a webhook](https://samva.dev/docs/api-reference/webhooks/remove): Deletes a webhook endpoint so it no longer receives event deliveries. Use this endpoint to delete a webhook through the Samva email API.
    - [Retry a webhook delivery](https://samva.dev/docs/api-reference/webhooks/retryDelivery): Performs one immediate manual redelivery attempt and returns that attempt's identity and outcome without changing the automatic retry lifecycle.
    - [Send a test webhook delivery](https://samva.dev/docs/api-reference/webhooks/test): Queues a signed webhook.test event through the normal delivery and retry lifecycle.
    - [Update a webhook](https://samva.dev/docs/api-reference/webhooks/update): Updates a webhook's name, URL, subscribed events, channels, custom headers, or status and returns the updated endpoint.
  - ApiKeys
    - [Create an API key](https://samva.dev/docs/api-reference/apiKeys/create): Creates a new API key for the organization and returns the created key, including the plaintext secret, with a 201 response.
    - [Get an API key](https://samva.dev/docs/api-reference/apiKeys/get): Returns the API key with the given ID, including its metadata and permissions. Use this endpoint to get an API key through the Samva email API.
    - [List API key activity](https://samva.dev/docs/api-reference/apiKeys/getActivity): Returns a paginated list of recent request activity recorded for an API key. Use this endpoint to list API key activity through the Samva email API.
    - [Get API key send statistics](https://samva.dev/docs/api-reference/apiKeys/getStats): Returns aggregate send counts and daily volume attributed to an API key over the selected period of 7, 30, or 90 days.
    - [List API keys](https://samva.dev/docs/api-reference/apiKeys/list): Returns a paginated list of the organization's API keys, filterable by status and search term.
    - [Delete an API key](https://samva.dev/docs/api-reference/apiKeys/remove): Permanently deletes an API key record. Unlike revocation, the key row is removed rather than deactivated.
    - [Revoke an API key](https://samva.dev/docs/api-reference/apiKeys/revoke): Deactivates an API key so it can no longer authenticate requests. The key record is retained and remains listable.
    - [Rotate an API key](https://samva.dev/docs/api-reference/apiKeys/rotate): Issues a replacement with the same owner, name, and permissions, then deactivates the existing key. Returns the new key, including the plaintext secret.
    - [Update an API key](https://samva.dev/docs/api-reference/apiKeys/update): Updates the name or description of an API key and returns the updated key. Use this endpoint to update an API key through the Samva email API.
  - Developers
    - [Get a log entry](https://samva.dev/docs/api-reference/developers/getLogEntry): Returns one log entry by message id, including the message content, its status history, and the sanitized API request Samva recorded when it accepted the send.
    - [List logs](https://samva.dev/docs/api-reference/developers/listLogs): Returns a paginated log of accepted outbound sends, filterable by API key, delivery status, channel, message id, and date range.
  - Organizations
    - [Create the first workspace](https://samva.dev/docs/api-reference/organizations/bootstrap): Creates a replacement first workspace under the signed-in user's billing account when no workspace membership remains.
    - [Create a workspace](https://samva.dev/docs/api-reference/organizations/create): Creates a new workspace organization under the current billing account and returns it.
    - [Delete the current workspace](https://samva.dev/docs/api-reference/organizations/delete): Accepts owner-authorized durable workspace deletion.
    - [Get the current organization](https://samva.dev/docs/api-reference/organizations/get): Returns the organization for the current billing account. Use this endpoint to get the current organization through the Samva email API.
    - [Get organization usage](https://samva.dev/docs/api-reference/organizations/getUsage): Returns usage statistics for the current organization over the selected reporting period.
    - [Update the current organization](https://samva.dev/docs/api-reference/organizations/update): Updates the current organization's profile, billing, locale, design, default reply-to, and default unsubscribe-group fields and returns the saved organization.
  - Billing
    - [Get the workspace's overage usage and limits](https://samva.dev/docs/api-reference/billing/getOverageSettings): Get the workspace's overage usage and limits. View request and response details for this Samva email API endpoint.
    - [Set the workspace's overage limits](https://samva.dev/docs/api-reference/billing/updateOverageSettings): Replaces this workspace's spend limit and overage switch.
  - Operations
    - [Get an asynchronous operation](https://samva.dev/docs/api-reference/operations/get): Returns one durable asynchronous operation from the active organization. Use this endpoint to get an asynchronous operation through the Samva email API.
    - [List asynchronous operations](https://samva.dev/docs/api-reference/operations/list): Lists durable asynchronous operation state for the active organization. Use this endpoint to list asynchronous operations through the Samva email API.
    - [Retry an asynchronous operation](https://samva.dev/docs/api-reference/operations/retry): Retries the same durable execution identity when its failure is explicitly retryable. Retrying a workspace deletion additionally requires `organization:delete`.

  - **Analytics & Reference**
  - Analytics
    - [Export messaging analytics data](https://samva.dev/docs/api-reference/analytics/exportData): Exports per-message records for the given date range as CSV or JSON and returns the file content inline.
    - [Get channel performance analytics](https://samva.dev/docs/api-reference/analytics/getChannelStats): Returns aggregate delivery metrics plus unique-message email Open and Click rates over the selected date range.
    - [Get message delivery metrics](https://samva.dev/docs/api-reference/analytics/getDeliveryMetrics): Returns delivered, failed, and pending rates plus average delivery time over the selected date range, optionally filtered by channel.
    - [Get geographic message distribution](https://samva.dev/docs/api-reference/analytics/getGeographicDistribution): Samva API operation. Use this endpoint to get geographic message distribution through the Samva email API.
    - [Get hourly message distribution](https://samva.dev/docs/api-reference/analytics/getHourlyDistribution): Returns outbound message counts over the half-open selected instant range, bucketed by organization-local hour.
    - [Get message volume analytics](https://samva.dev/docs/api-reference/analytics/getStats): Returns outbound message counts over the half-open selected instant range, grouped by organization-local calendar day, week, or month.
    - [List top contacts by message volume](https://samva.dev/docs/api-reference/analytics/getTopContacts): Returns the contacts with the highest message counts over the selected date range, up to the requested limit.
  - [OpenAPI specification](https://samva.dev/docs/api-reference/openapi): Download the OpenAPI 3.1.0 document for the Samva API and generate clients from it.