Quarantine suspicious mail

A mailbox checks every incoming message before anyone reads it. Mail that looks like spam, phishing, fraud, or an attempt to steer an AI agent is held instead of delivered. An agent that reads the mailbox never sees held mail unless you gave it quarantine.read, and even then it sees metadata only.

Dispositions

Every incoming message has one disposition.

Reasons

A held message carries a reason and a source: receipt when the scan that runs as the message arrives held it, or classifier when Samva's content classifier did.

Who can see and decide

Held messages show metadata only: sender, subject, reason, and when they arrived and were held. Their bodies and attachments stay unreachable while they are held.

List held messages

import { createClient } from "samva";

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

const held = await samva.mailboxes.listQuarantine({ id: "mbx_..." });

for (const item of held.items) {
  console.log(item.id, item.disposition, item.reason, item.from.address, item.subject);
}

curl "https://api.samva.dev/v1/mailboxes/$MAILBOX_ID/quarantine?limit=50" \
  -H "X-API-Key: $SAMVA_API_KEY"

The newest held message comes first. Pass a page's nextCursor as cursor to read the next page. limit defaults to 20 and is at most 100. after and before bound when a message was held.

Each item has id (the held message's id, the one release and discard take), disposition, reason, source, from, subject, receivedAt, heldAt, releasedAt, threadId, and discardedAt. releasedAt and threadId are set after a release, and discardedAt after a discard.

Release a message

Releasing delivers a quarantined message into the thread it would have joined and publishes one mailbox.message.released event. It does not create a second copy.

Sign in with samva login as a person with an admin grant, or use the dashboard:

samva login
samva mailboxes quarantine release $MESSAGE_ID --mailbox $MAILBOX_ID

Releasing is idempotent: releasing again returns the same result and publishes nothing. An isolated message cannot be released, and neither can one that was discarded. Both are 409.

Discard a message

Discarding removes a held message for good. It leaves the quarantine list, never reaches a thread, and can no longer be released. Both quarantined and isolated messages can be discarded.

samva mailboxes quarantine discard $MESSAGE_ID --mailbox $MAILBOX_ID

Discarding publishes one mailbox.message.discarded event. It is idempotent: discarding again returns the same result and publishes nothing. A message that was released is already in its thread and cannot be discarded: 409.

React to held mail

Three events describe held mail; Events lists their payloads.

• mailbox.message.quarantined fires when a message is held.
• mailbox.message.released fires when a person releases it.
• mailbox.message.discarded fires when a person discards it.

An event stream connection or an extension receives quarantined and discarded events only for mailboxes where its credential holds quarantine.read.

Next steps