# Upgrading to samva 0.27: changes since 0.11
URL: https://samva.dev/changelog/upgrade-to-samva-0-27
> Moving from samva 0.11 to 0.27 renames mailbox calls, changes contact and sender setup, and reshapes template and usage responses. Check these changes.
- Published: 2026-10-26
- Tags: sdk, cli, api



Many of these changes are live on the REST API too. Search your code for the old names below, then let the type checker find the rest. If you upgrade one release at a time, each version's notes are in the [package changelog](https://www.npmjs.com/package/samva/v/0.27.0).

**What you need to do**

1. **Mailbox streams.** The stream now pings every 30 seconds instead of sending heartbeats. Upgrade the SDK or CLI before you rely on a long-lived stream, or an older one reconnects about every 90 seconds (0.12).
2. **Contacts.** `contacts.bulkImport` takes `identities` and `profile` and an `onConflict` of `skip` or `update`. `findOrCreate` takes a `lookup` and returns `{ contact, created }` (0.13, 0.14). An identity has a `type` of `email` or `phone` where it had a `channel` (0.19).
3. **Mailbox sends.** A send, reply or forward returns a receipt with a `state`, such as `queued` or `completed`, in place of `status` (0.14). A mailbox owns endpoints (0.15, 0.16):

```ts
// Before
await samva.mailboxes.create({
  slug: "support",
  displayName: "Support",
  addresses: [{ address: "support@acme.samva.email" }],
});

// After
await samva.mailboxes.create({
  endpoint: { channel: "email", address: "support@acme.samva.email" },
  name: "Support",
});
```

4. **Default sender.** An organization has one default sender, and domains carry none (0.16):

```ts
// Before
await samva.email.setDomainDefaultSender({ id: domainId, senderId });

// After
await samva.email.setDefaultSender({ id: senderId });
```

5. **Unsubscribe groups.** Members are contacts. `addEmails` is `addMembers`, `removeEmails` is `removeMembers`, and each takes `{ contactId }`, `{ email }` or `{ phone }` (0.19).
6. **Templates.** Publications return `compiled` where they returned `ir`, and a brand's footer is one `renderedFooter` (0.23). Template, API key and campaign run responses carry new required fields, so update test fixtures (0.21).
7. **Usage.** Organization usage reports `includedCredits`, `usedCredits` and `overageCredits` where it reported email counts, with AI credits in separate fields (0.23).
8. **Sends without a sender.** A send with no `from` and no default sender throws `FromAddressRequiredError`, whose `verifiedDomains` lists what you can use (0.24).
9. **Effect users.** `Client.raw` is gone. Call the domain operation, such as `Contacts.list(...)` from `samva/effect/contacts` (0.17).

Also in this range: Promise request types accept `undefined` inside free-form objects such as `templateData`, and list parameters accept two or more items (0.23.1).

## Links

- [TypeScript SDK](/docs/developers/typescript-sdk)
- [samva 0.27.0 on npm](https://www.npmjs.com/package/samva/v/0.27.0)
- [@samva/cli 0.25.0 on npm](https://www.npmjs.com/package/@samva/cli/v/0.25.0)

## Related

- [Upgrading to samva 0.28 and the CLI 0.26](/changelog/upgrade-to-samva-0-28)
- [Add your own headers to any email you send](/changelog/add-your-own-headers-to-an-email-you-send)
- [All changelog entries](/changelog)