Skip to content
Mailboxes

An inbox for your AI agent.

Give your agent its own address on samva.email or your domain. It reads and replies through the API, SDK, CLI, or MCP with a key that reaches only that mailbox, and you can open the same mailbox in the browser.

Start sending freeRead the mailbox guide
mailbox_replymailbox_threads_listmailbox_sendmcp.samva.devdecide: runmailbox.message.receivedsupport@acme.samva.emailmbx_7k2m9q4xw5pf8d3cHOSTED MCPmcp.samva.dev, OAuth or an API key1GRANTS AND POLICIESsend, or hold for approval2MAILBOXmailbox.message.received3
  1. HOSTED MCPmcp.samva.dev, OAuth or an API key
  2. GRANTS AND POLICIESsend, or hold for approval
  3. MAILBOXmailbox.message.received
Fig 9.Your agent connects to its mailbox through hosted MCP. Mail arrives as an event, the agent replies with a tool call, and the mailbox's grants and policies decide whether it sends or waits for a person.

Your agent sends an email, the person replies, and the agent never hears about it. An agent without its own inbox borrows a human's, polls it, and loses the thread.

What your agent gets.

  • Its own address

    On your organization's samva.email subdomain with no DNS to set up, or on a domain you verified.

  • Its own key

    A mailbox-scoped key reaches only the mailboxes you list, and every action it takes is attributed to it.

  • Built for agents

    The API, SDK, CLI, hosted MCP tools, signed webhooks, and a WebSocket event stream.

  • A person can step in

    Open the same mailbox in the browser to read, reply, and compose.

  • Sends you approve

    Hold an agent's sends until a person approves them, and switch modes without a new key.

  • Spam kept out

    Suspicious mail is held in quarantine until a person releases or discards it.

From an address to the first reply.

  1. Create a mailbox.

    Pick an address on your samva.email subdomain, or on a domain you verified with receiving on.

  2. Give the agent its own key.

    A mailbox-scoped key holds only the permissions you choose: read, update, send, and quarantine.read.

  3. Hear about new mail.

    A signed mailbox.message.received webhook reaches your server, or read the WebSocket event stream when it has no public URL.

  4. Reply in the thread.

    The agent replies with its key, or a person approves the send first. The server sets the recipients, subject, and threading headers.

  5. Open the same mailbox.

    Read, reply, or compose in the browser alongside the agent.

  6. Extend it with code.

    Publish an extension, a webhook or a hosted handler, that reacts to mailbox events with its own permissions.

create-mailbox.tsTypeScript
import { createClient } from "samva";

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

const created = await samva.mailboxes.create({
  endpoint: { channel: "email", address: "support@example.samva.email" },
  name: "Support",
});

const key = await samva.apiKeys.create({
  name: "Support agent",
  access: {
    mode: "restricted",
    resources: {},
    mailboxes: {
      permissions: ["read", "update", "send"],
      mailboxIds: [created.id],
    },
  },
});

Ready to build? Give an agent an inbox.

Control stays with you.

  • Granted, not global

    A key is capped by the member who owns it. No key can create or configure a mailbox, approve a send, or release held mail.

  • Approval when you want it

    Set a key, a person's grant, or an extension to approval and its sends wait for a different person. Nobody approves their own send.

  • Spam held back

    Spam, phishing, fraud, and text written to steer an agent are held before the agent reads them. An agent sees held mail as metadata only, and only with quarantine.read.

  • A person decides what's real

    Only a person with an admin grant releases or discards held mail. Keys, extensions, and MCP tools never do.

  • One sub-tenant per customer

    Namespaces confine a key to one customer's mailboxes, for agents you run on your customers' behalf.

  • Allowances by plan

    Plans include mailboxes and storage for their mail: Free 1 mailboxes with 1 GB of mail, Starter 10 mailboxes with 10 GB of mail, Growth 50 mailboxes with 50 GB of mail, Scale 250 mailboxes with 250 GB of mail.

The conversation that brings replies back to your app gets an address your agent owns.

Read next: Give an agent an inbox · Business email for your team · Run the mailbox agent example · Keys and grants · Approve a send · Quarantine · Mailbox events · Hosted MCP tools · What shipped

Samva Agents

An AI assistant answers your customers on the email addresses and WhatsApp numbers you choose. It handles what your instructions cover and brings you the rest, with the reason.

Integrations

Connect Shopify, Google Calendar, or Linear, and your assistant uses them under the access you grant, such as answering a customer's order question from your own Shopify orders.

See every integration

Common questions.

What is email for AI agents?

An inbox your agent owns. Create the address on your samva.email subdomain, or on a domain you verified, and give the agent a key that reaches only that mailbox. It reads and replies through the API, SDK, CLI, or hosted MCP. You can require a different person to approve each send, and quarantine holds suspicious mail until a person releases or discards it. The agent is yours: Samva does not run it.

When should I use a mailbox instead of inbound email?

Use a mailbox when an agent needs its own address, a key scoped to that inbox, and a place to read and reply alongside a person. Use inbound email when your application receives mail on its domain and handles signed message.received webhooks, such as turning a customer's reply into a support-ticket update. Mailbox webhooks use mailbox.message.received; the runnable mailbox agent example also shows the WebSocket event stream without a public webhook endpoint.

Can I use my own domain?

Yes. Verify the domain with receiving on, then create a mailbox on it. An address under your organization's samva.email subdomain needs no DNS setup.

Does the agent run on Samva?

No. The agent is yours, and it reaches the mailbox through the API, SDK, CLI, or hosted MCP. A hosted extension runs only the handler you publish. If you would rather have an assistant that Samva hosts and that answers your customers, see Samva Agents.

Can I connect Gmail, Outlook, or an IMAP client?

No. A mailbox is read and sent through the API, SDK, CLI, hosted MCP, and the browser, not through IMAP, SMTP, or a connected Gmail or Outlook account.

Can an agent send without approval?

By default a send runs at once, within your account's limits. Set a rule that asks a person, and someone other than the sender must approve it first.

What happens to spam and prompt injection?

Every incoming message is checked before anyone reads it. Mail that looks like spam, phishing, fraud, or an attempt to steer an AI agent is held in quarantine until a person releases or discards it.

How many mailboxes does a plan include?

Free 1 mailboxes with 1 GB of mail, Starter 10 mailboxes with 10 GB of mail, Growth 50 mailboxes with 50 GB of mail, Scale 250 mailboxes with 250 GB of mail. Creating a mailbox past your plan's allowance is refused.

The rest of the API.

Give your agent an inbox.

Start sending freeRead the mailbox guide

Related Resources