Give a person a mailbox

A personal mailbox belongs to one person. A shared mailbox belongs to the team members granted access to it. Both receive and send email, but their access rules differ.

Mailbox lists and details identify this with kind: personal or shared. owner is the personal owner's user ID, or null for a shared mailbox. Assigning someone an address does not give the person who assigned it access to that mailbox.

Invite someone with a personal addressCopy Anchor Link

An organization owner or admin opens Settings → Team, invites the person by their sign-in email, and chooses their personal mailbox address. Use a verified receiving domain, or the hosted domain offered when the organization has no eligible domain.

Choose Mail user for someone who only needs Samva Mail. They accept the invitation after signing in with the invited email address, and land in Mail. This role does not grant dashboard access or access to other people's mailboxes. Direct dashboard links also return them to Mail. Use another organization role when the person also needs that role's dashboard access.

The invitation reserves the address and its mailbox allowance before the email is sent. Acceptance creates the personal mailbox for the invited person. An address held by another mailbox or pending invitation is refused. See Mailbox allowance for the plan limit.

For a person who already belongs to the organization, open Settings → Team and choose Assign address in their Personal address column. Choose the address and confirm with Assign address. The SDK offers the same operation:

import { createClient } from "samva";

const samva = createClient({ apiKey: process.env.SAMVA_API_KEY! });

const assigned = await samva.organizations.assignPersonalMailbox({
  userId: "user_7q2xk9mvt4znw8rh",
  mailboxAddress: "ada@example.com",
});

console.log(assigned.mailboxId);

Only organization owners and admins may assign an address. They can list which members have an assignment without reading those members' personal mail.

Keep personal mail privateCopy Anchor Link

The owner is the only person who can read a personal mailbox. An organization owner, admin, or teammate does not receive access through their organization role. A personal mailbox cannot be shared with another person through a mailbox grant.

Read personal messages through that mailbox's routes or Samva Mail. Organization-level message, email, attachment, media, conversation, activity-log, and search views exclude personal mail, including when the caller is the personal owner. Organization-wide message webhooks exclude it too. Usage, billing, quota, and suppression totals still include personal mail without exposing its content.

The owner can explicitly authorize an agent or key to act on the mailbox. A delegated key must name the personal mailbox in its mailboxIds; omitting that list does not include personal mailboxes. Its permissions remain bounded by the owner's access. Use the mailbox-scoped reads and sends shown in Agents, people, and keys, including for an owner whose credential can also access organization-level tools.

Remove someone or restore their accessCopy Anchor Link

Removing the person from the organization immediately pauses their personal mailbox and removes access for the person and their delegated agents and keys. The mailbox is scheduled for deletion 30 days after removal; its address remains reserved while it is retained. Mail sent to the paused personal mailbox is not delivered. Authenticated senders receive a mailbox-disabled bounce (5.2.1); unsafe, suppressed, bulk, and automated mail is dropped without a bounce to prevent backscatter. This applies while the address still resolves to that mailbox.

Before deletion, reinvite the same person with the same personal address to restore the existing mailbox and its retained conversations. Mail that arrived during the pause is not backfilled. An organization owner can delete an offboarded personal mailbox sooner through the mailbox deletion operation, without gaining access to its content. An admin cannot use that exception.

After deletion, creating a mailbox at the address starts a new mailbox. Deletion never makes personal messages available through organization-level content views.