# Upgrading to samva 0.28 and the CLI 0.26
URL: https://samva.dev/changelog/upgrade-to-samva-0-28
> samva 0.28 replaces unsubscribe groups with topics, types query values, and adds campaign run reports. CLI releases now ship native downloads.
- Published: 2026-10-27
- Tags: sdk, cli, api



Search your code for the old names below, then let the type checker find the rest. Each package's full notes are on its [GitHub release](https://github.com/SamvaHQ/samva-typescript/releases).

**What you need to do**

1. **Topics replace unsubscribe groups.** Use `samva.topics`, `audience.topicId` on campaigns, and `topicId` on confirmation requests. Set a contact's status per topic and channel with `topics.setSubscriptions`. Existing opt-outs carry over. Subscription webhooks carry `topicId`, `topicName`, and `channel`, and `samva subscriptions subscribe` takes `--topic-id`. See [Manage topics and subscriptions](/docs/channels/email/topics).
2. **Query values.** Pass numbers and booleans where you passed strings, such as `limit: 20` and `isActive: false`, in both SDKs and `@samva/mailbox`.
3. **Template build failures.** Saving, opening, publishing, or restoring a workspace whose source fails to build throws `TemplateSourceError` (HTTP `422`) with the compiler's `diagnostics`, where it threw `ConflictError`. Catch the new error to read the findings.
4. **Bulk contact calls.** `contacts.bulkDelete`, `contacts.bulkUpdateTags`, `contacts.bulkUpdateStatus`, `conversations.addContacts`, `conversations.removeContacts`, and the `ids` filter of `contacts.export` take at most 1,000 contact ids per request.
5. **Usage.** Organization usage drops `standardGranted`, `standardRemaining`, and `standardResetsAt`. Read AI credits from `includedAiCredits`, `usedAiCredits`, `aiPackCredits`, and `aiResetsAt`.

Preview · Available to selected organizations.

**List import.** `contacts.bulkImport` is removed. Plan an import with `contacts.planImport`, start it with `contacts.startImport`, and follow the background job with `contacts.getImportJob`. See [Import a reader list](/docs/channels/email/list-migration).

Preview · Available to selected organizations.

**Agents.** Remove `approvalPolicy` from agent definitions. Every Google Calendar booking, change, and cancellation waits for a person to approve it.

**Also new**

* **Campaign run reports.** `campaigns.getRunReport` and `samva campaigns report` return a run's delivery outcomes, replies, topic unsubscribes, and skipped recipients.
* **Personalized campaigns.** Campaign templates merge each contact's profile and custom fields. Render a campaign as a contact with `campaigns.preview`, and send yourself a copy with `campaigns.sendTest`.
* **Campaign replies.** A reply to a campaign message carries `campaign: { campaignId, runId }` in mailbox reads and webhooks.
* **Brand return link.** Set `footer.websiteUrl` on a brand to choose the link on its hosted recipient pages.
* **Source and downloads on GitHub.** The SDK's source is public at [SamvaHQ/samva-typescript](https://github.com/SamvaHQ/samva-typescript) and the CLI's at [SamvaHQ/samva-cli](https://github.com/SamvaHQ/samva-cli), both updated with each release. Each CLI release there includes the native `samva` executable for macOS and Linux with a `SHA256SUMS` file.

## Links

- [Manage topics and subscriptions](/docs/channels/email/topics)
- [samva 0.28.0 release notes](https://github.com/SamvaHQ/samva-typescript/releases/tag/samva%400.28.0)
- [@samva/cli 0.26.0 downloads](https://github.com/SamvaHQ/samva-cli/releases/tag/v0.26.0)

## Related

- [Upgrading to samva 0.27: changes since 0.11](/changelog/upgrade-to-samva-0-27)
- [All changelog entries](/changelog)