samva@0.31.0

samva@0.31.0

Filter conversations by mailbox

Pass mailboxId to conversations.list to list only conversations in that mailbox. Combine it with the existing contact, channel, status, and date filters.

@samva/webhooks@0.31.0

@samva/webhooks@0.31.0

Filter conversations by mailbox

Pass mailboxId to conversations.list to list only conversations in that mailbox. Combine it with the existing contact, channel, status, and date filters.

samva@0.30.0

samva@0.30.0

One Idempotency Option Across the SDK

Breaking: Pass idempotency keys in the second options argument as { idempotencyKey }.
Raw HTTP callers send Idempotency-Key; body and query spellings are removed. Both clients
supply a fresh key for every idempotent operation and reuse it across automatic retries.

The Promise client retries reads and idempotent mutations, accepts client-level and per-call
maxRetries, and adds lazy .pages() and .items() async iterators to cursor lists.
OAuth clients can select an organization with orgSlug.

Breaking: Import mailbox extension helpers from samva/mailbox, samva/mailbox/test, and
samva/mailbox/webhook. Handlers receive the normal client and call
ctx.samva.mailboxes.reply({ id, messageId, text }). Event dispatch preserves deterministic
send keys. The CLI extension scaffold uses these imports and flat calls.

For samva events send, pass --idempotency-key instead of embedding a key in --data.

Agent definitions hold integration grants

AgentDefinition.integrationIds is replaced by integrations, a list of grants. Each grant names
the integration, the tools the agent may use (all, readOnly, or selected with names), and
the tools that always wait for a person (requireApproval). Replace each id in integrationIds
with { integrationId, tools: { kind: "all" }, requireApproval: [] }.

Publishing an agent now fails with a validation error on definition.integrations when a grant
names an integration the organization has not installed or a tool its app does not have.

Newsletters own issue publishing

Use newsletters for newsletter management, newsletters.issues for issue authoring, and
newsletters.domains for custom domains on the Promise client. Effect callers import
samva/effect/newsletters, samva/effect/newsletter-issues, and samva/effect/newsletter-domains.

The API uses /v1/newsletters/:id/issues/* and /v1/newsletters/:id/domains/*; CLI commands use
samva newsletters. Topic issue routes, SDK namespaces, MCP issues_* tools, and topic archive
fields are removed. Newsletter mutations accept one optional Idempotency-Key header. Consent,
subscriptions, sending defaults, and campaign audiences continue to use topicId.

Discover archive domains with newsletters.domains.list or samva newsletters domains list.
The hostname-ordered response includes verification snapshots and an opaque nextCursor.

Accept Effect 4.0.x

samva and @samva/webhooks accept effect@^4.0.4 as their optional peer. Install 4.0.6, or any
later 4.0.x, next to those packages when using the Effect entrypoints.

Issue frontmatter carries an optional date

The frontmatter that topicIssues.check and topicIssues.render return includes an optional date (YYYY-MM-DD), the value a layout's <IssueDate /> prints.

@samva/webhooks@0.30.0

@samva/webhooks@0.30.0

One Idempotency Option Across the SDK

Breaking: Pass idempotency keys in the second options argument as { idempotencyKey }.
Raw HTTP callers send Idempotency-Key; body and query spellings are removed. Both clients
supply a fresh key for every idempotent operation and reuse it across automatic retries.

The Promise client retries reads and idempotent mutations, accepts client-level and per-call
maxRetries, and adds lazy .pages() and .items() async iterators to cursor lists.
OAuth clients can select an organization with orgSlug.

Breaking: Import mailbox extension helpers from samva/mailbox, samva/mailbox/test, and
samva/mailbox/webhook. Handlers receive the normal client and call
ctx.samva.mailboxes.reply({ id, messageId, text }). Event dispatch preserves deterministic
send keys. The CLI extension scaffold uses these imports and flat calls.

For samva events send, pass --idempotency-key instead of embedding a key in --data.

Agent definitions hold integration grants

AgentDefinition.integrationIds is replaced by integrations, a list of grants. Each grant names
the integration, the tools the agent may use (all, readOnly, or selected with names), and
the tools that always wait for a person (requireApproval). Replace each id in integrationIds
with { integrationId, tools: { kind: "all" }, requireApproval: [] }.

Publishing an agent now fails with a validation error on definition.integrations when a grant
names an integration the organization has not installed or a tool its app does not have.

Newsletters own issue publishing

Use newsletters for newsletter management, newsletters.issues for issue authoring, and
newsletters.domains for custom domains on the Promise client. Effect callers import
samva/effect/newsletters, samva/effect/newsletter-issues, and samva/effect/newsletter-domains.

The API uses /v1/newsletters/:id/issues/* and /v1/newsletters/:id/domains/*; CLI commands use
samva newsletters. Topic issue routes, SDK namespaces, MCP issues_* tools, and topic archive
fields are removed. Newsletter mutations accept one optional Idempotency-Key header. Consent,
subscriptions, sending defaults, and campaign audiences continue to use topicId.

Discover archive domains with newsletters.domains.list or samva newsletters domains list.
The hostname-ordered response includes verification snapshots and an opaque nextCursor.

Accept Effect 4.0.x

samva and @samva/webhooks accept effect@^4.0.4 as their optional peer. Install 4.0.6, or any
later 4.0.x, next to those packages when using the Effect entrypoints.

Issue frontmatter carries an optional date

The frontmatter that topicIssues.check and topicIssues.render return includes an optional date (YYYY-MM-DD), the value a layout's <IssueDate /> prints.

samva@0.29.1

samva@0.29.1

Use Effect 4.0.5 with the SDK and webhook adapter

Install effect@4.0.5 when using samva/effect or @samva/webhooks/effect. Both packages require
that exact peer version.

samva@0.29.0

samva@0.29.0

Author newsletter issues and pin saved content to campaigns

The SDK adds topicIssues on the Promise client and TopicIssues at
samva/effect/topic-issues. The CLI adds samva topics issues for creating and editing Markdown
issues, checking and previewing email or web output, and saving commits. Listing issues returns
each draft's title and its latest campaign send, and needs messages read access beside contacts
read access. Issue authoring is Preview and requires access for your organization.

Campaigns accept content.issue: { path, commit } with audience.topicId to select a saved issue.
The saved title and preheader supply the email content, and each run keeps its selected path and
commit. Use the CLI's --issue-path and --issue-commit options to select that content.

Use SML 0.21 for template projects

Update your project's @samva/markup and @samva/vite packages to 0.21.0. Compiled templates use
sml: 2; direct renderer calls select output with { target: "email" } instead of
{ channel: "email" }.

Publish sent newsletter issues on the web

Publication sites are Preview and available to selected organizations. Enable an opt-in topic's
archive with archiveEnabled and choose its <publicationSlug>.samva.app hostname. Sent issues
appear in the archive, RSS feed and sitemap; saving a draft does not publish it.

The SDK adds topicPublicationDomains on the Promise client and TopicPublicationDomains at
samva/effect/publication-domains to add, inspect and remove custom publication domains. The CLI
adds --archive enabled|disabled and --publication-slug <label|none> to topic settings.

Email sent with publication Preview access includes a private view-in-browser link to that
delivery's frozen content. Compiled templates must support SML's web renderer; raw API HTML and
text are also supported.

samva@0.28.1

samva@0.28.1

Open every package README by saying what Samva is

The samva, @samva/webhooks, @samva/cli, native CLI, and @samva/mailbox READMEs now open
with a one-line description of Samva. @samva/cli describes itself as an email tool and drops the
cpaas and messaging keywords.

samva@0.28.0

samva@0.28.0

Send at most 1,000 contact ids per bulk request

Breaking: contacts.bulkDelete, contacts.bulkUpdateTags, contacts.bulkUpdateStatus,
conversations.addContacts, conversations.removeContacts, and the ids filter of
contacts.export accept at most 1,000 contact ids. A longer list fails with ValidationError
(HTTP 422), and the Effect client refuses it before sending. Split larger selections into
batches of 1,000.

Subscribe contacts to topics

Breaking: Topics replace unsubscribe groups. Use client.topics (Effect: samva/effect/topics),
audience.topicId on campaigns, and topicId when requesting a confirmation email. Set each
contact's subscribed or unsubscribed status per topic and channel with topics.setSubscriptions.
Existing opt-outs carry over, and opt_in topics reach only subscribed contacts.

• Webhooks: subscription events carry topicId, topicName, and channel instead of group fields.
  Skipped-recipient receipts report topic-unsubscribe with a topicId, in the SDKs and in mailbox
  extensions.
• CLI: manage topics with samva topics. samva subscriptions subscribe requires --topic-id; the
  contact-group and unsubscribe-group flags are removed.
• Confirmation: a confirmation request creates the contact only once the recipient confirms.
  Outstanding confirmation links that named no unsubscribe group no longer work.

Handle template build failures as TemplateSourceError

Breaking: When a template's source fails to build, saving, opening, publishing, or restoring a
workspace fails with TemplateSourceError (HTTP 422) instead of ConflictError (409). Catch
TemplateSourceError wherever you caught ConflictError to read build findings. It is a
validation error and not retryable; the Effect client exports it from samva/effect/errors.

Its diagnostics hold the compiler's findings, each with a code, severity, and origins locations;
a failure with no location is a single sml/build-failed finding. If a save pulled in an outside
commit before the build failed, the error includes revision: reload the workspace, fix the
source, and retry. ConflictError now means only a real conflict, such as a moved branch head, a
save already in progress, or a reused idempotency key.

The CLI prints each finding's location and how to fix it. --json and --jsonl include every
finding in details.diagnostics and the next step in next.

Pass query values as numbers and booleans

Breaking: Query parameters take numbers and booleans instead of strings, in both SDKs and
@samva/mailbox: for example limit: 20, urlExpiresIn: 60, isActive: false, sendable: true,
shared: true, and the mailbox unread, starred, and snoozed filters. Replace values such as
limit: "20".

A call whose body has only optional fields no longer needs one. campaigns.scheduleRun({ id })
schedules a run with its defaults, and the Effect Organizations.update() and
Email.updateTrackingDefaults() send {}. CLI flags are unchanged.

Personalize campaigns and see which campaign a reply answers

Campaign templates merge each contact's profile and custom fields, falling back to templateData.
A recipient missing a required value is skipped with missing_merge_field and the missing field.
Campaigns can override the sender, reply mailbox, and preheader; the defaults come from the topic.

Preview a campaign as a contact with campaigns.preview, and send yourself a copy with
campaigns.sendTest without starting a run.

An authenticated reply to a campaign message carries campaign: { campaignId, runId } in message
and mailbox reads and in the message.received and mailbox.message.received webhooks.

Set a brand's return website

Set footer.websiteUrl when creating or updating a brand to choose the HTTPS return link on its
hosted recipient pages. Brand responses include the configured URL.

Import subscriber lists as a background job

Breaking: contacts.bulkImport is removed. Plan an import with contacts.planImport, start it
with contacts.startImport using the plan's preview hash and an idempotency key, and follow it with
contacts.getImportJob. Imports run as a background job instead of returning per-contact results.
List import is in Preview and must be enabled for your organization.

Import related beehiiv, Substack, Kit, or Mailchimp exports together. When files disagree about a
contact, the most restrictive status wins, and reimports keep existing unsubscribes, suppressions,
and bounces. Contact detail shows which import a contact came from.

In the CLI, preview with samva contacts import --preset --topic --file EVIDENCE=PATH --dry-run,
start with an idempotency key, follow progress with samva contacts import-status, and resume an
eligible failed job with samva contacts import-resume.

Read a campaign run's results

campaigns.getRunReport and samva campaigns report <campaignId> <runId> return a run's delivery
outcomes, replies, topic unsubscribes, and skipped recipients, counted once per recipient. Opens and
clicks are marked directional and leave out those classified as automated.

Calendar changes always wait for approval

Breaking: Remove approvalPolicy from the agent definition you pass to agents.create and
agents.replaceDraft. An agent's Google Calendar bookings, changes, and cancellations always wait
for a person to approve them.

Read the source on GitHub

The packages' source is public at
SamvaHQ/samva-typescript, a read-only mirror updated
with each release. The npm repository and bugs links point there; report problems as issues on
that repository.

Every agent draws AI credits

Breaking: Organization usage no longer has a Standard allowance: standardGranted,
standardRemaining, and standardResetsAt are removed, and samva org usage no longer prints
them. Every agent draws the plan's monthly AI credits instead. Show the balance from
includedAiCredits, usedAiCredits, aiPackCredits, and aiResetsAt.

samva@0.27.0

samva@0.27.0

Manage hosted agents from the SDK

The Promise client has an agents service and the Effect SDK has an Agents module
(samva/effect/agents) for the hosted agents API, which is in Preview: list, create, get,
update, remove, replaceDraft, publish, listVersions, and getVersion.

Construct tagged union members without _tag

The Effect schemas for the mailbox send errors and the domain verification evidence variants are
now Schema.TaggedStruct, so their make constructors fill in _tag. Decoded values and the JSON
they read and write are unchanged.

@samva/webhooks@0.29.1

@samva/webhooks@0.29.1

Use Effect 4.0.5 with the SDK and webhook adapter

Install effect@4.0.5 when using samva/effect or @samva/webhooks/effect. Both packages require
that exact peer version.