API Reference
Browse the Samva email API endpoints by service, generated from the OpenAPI specification.
The Samva API is a REST API: requests and responses are JSON, and standard HTTP status codes signal success or failure. Browse endpoints by resource below, or start from the conventions reference.
OpenAPI specification: the live spec is published at api.samva.dev/v1/openapi.json. See the OpenAPI page for details.
Resources
Each resource has a page that lists its endpoints.
- Messages: Send messages and track their delivery lifecycle, the core send endpoint of the Samva API.
- Email: Configure email-channel infrastructure, including domains, verified senders, suppression, and inbound receiving.
- Templates: Create TSX template projects, publish exact commits, and send from stable template references.
- Brands: Brand themes, logos and footers that templates import with
samva:brand. - Scheduled Messages: One-off scheduled message timers.
- Campaigns: Campaign drafts and scheduled campaign runs.
- Newsletters: Newsletters, their consent topics, and publishing settings.
- Newsletter issues: Newsletter-owned newsletter Markdown files and their Git workspace.
- Newsletter domains: Custom domains for newsletter archives.
- Attachments: Email attachment metadata and secure download URLs.
- Media: Media objects and the presigned uploads that fill them.
Contacts & Conversations
- Contacts: Manage the people you send to, create, update, segment, and export contacts.
- Topic forms: Hosted and embedded double opt-in signup forms for topics.
- Topics: Topics and per-channel contact subscriptions.
- Subscriptions: Recipient-confirmed topic subscriptions.
- Events: Custom contact event ingestion.
- Contact events: A contact's custom and lifecycle event timeline.
- Journeys: Event-triggered, per-contact email flows defined as versioned node graphs.
- Agents: Agents that answer conversations on your mailbox endpoints, with a draft, published versions, and rules for action review, hours, and staff takeover.
- Contact Groups: Segment management, static and dynamic groups with membership operations.
- Custom Fields: Custom field definitions for contact metadata.
- Conversations: Create, update, and list conversations with your contacts.
Mailboxes
- Mailboxes: Mailboxes: endpoints, threads, messages, drafts, and governed sends.
- Policies: Rules governing who decides each gated action.
- Namespaces: Sub-tenants that confine domains, senders, mailboxes, contacts, templates, and API keys inside an organization.
- Extensions: Code that receives mailbox events and acts through the mailbox API.
- Extension installations: Extension versions installed into the organization, each acting as its own principal.
Configuration
- Webhooks: Subscribe to delivery and inbound events with signed, verifiable webhook payloads.
- API Keys: API key management, rotation, and usage statistics.
- Organizations: Organization management and usage statistics.
- Operations: Status of accepted asynchronous mutations.
- Feedback: Reports to Samva about the API itself.
- Whoami: The organization and credential behind the request.
Analytics & Reference
- Analytics: Messaging analytics, channel stats, and data export.
Conventions
Shared conventions (base URL, authentication, request and response shapes, status codes, errors, and pagination) are documented once in the REST API reference. Start there, then open a resource above for its endpoints.
REST conventions
Base URL, headers, status codes, errors, and pagination.
API keys
API keys, headers, and error responses.
TypeScript SDK
The official SDK over this API.
Send an email
A runnable send walkthrough with the TypeScript SDK and curl.
Support
Need help with the API? Email support@samva.dev.