Manage a mailbox

Use this guide to change an existing mailbox's configuration or stop its activity. You need an admin grant and authentication allowed to manage mailboxes. A mailbox-scoped key cannot configure a mailbox, even when its owner is an admin. See Agents and keys for the access model.

Read the current configuration

Use the mailbox ID from creation or from mailboxes.list. Lists contain summaries; get returns addresses, metadata, and the default sending identity.

import { createClient } from "samva";

const samva = createClient({ apiKey: process.env.SAMVA_API_KEY! });
const id = "mbx_...";
const mailbox = await samva.mailboxes.get({ id });
console.log(mailbox.displayName, mailbox.status, mailbox.addresses, mailbox.defaultFrom);

Choose the sending identity

Update the mailbox's name and choose a From address it already owns. The mailbox name and the sender's display name are separate fields.

await samva.mailboxes.update({
  id,
  displayName: "Customer support",
  defaultFrom: {
    address: "support@acme.samva.email",
    displayName: "Acme Support",
  },
});

defaultFrom.address must be one of this mailbox's addresses. Set defaultFrom.displayName: null to clear the sender display name. An update changes only fields you name; the mailbox slug and address list are not fields on this update request. See update a mailbox for its contract.

Keep application metadata

Metadata holds string values your app associates with the mailbox. Updates merge by key, and a null value removes a key without replacing the rest.

await samva.mailboxes.update({
  id,
  metadata: {
    team: "support",
    costCenter: "customer-operations",
    oldRoutingTag: null,
  },
});

Read back with mailboxes.get to check the resulting configuration.

Pause and resume

Pausing stops new sends and stops new inbound mail reaching the mailbox. Existing conversations remain readable. Mail that arrives while paused is not added when you resume, so pause only when you intend to miss that interval's incoming mail.

const paused = await samva.mailboxes.pause({ id });
console.log(paused.status);

// Run when the mailbox should accept new mail again.
const resumed = await samva.mailboxes.resume({ id });
console.log(resumed.status);

Resuming allows sending and receiving again from that point. It does not backfill inbound mail. New sends from a paused mailbox are refused; retrying a send that already ran can still replay its receipt. See pause and resume.

Delete a mailbox

Deletion removes the mailbox's addresses, threads, drafts, and history. Messages the organization received remain with the organization, but recreating a mailbox does not restore its thread history or add earlier messages.

await samva.mailboxes.remove({ id });

The mailbox is removed from API key scopes and webhook endpoint mailbox filters. A key or endpoint left with no mailbox is disabled. Review those integrations before deleting; use pause when you need a reversible stop. See delete a mailbox for the response and errors.