# An inbox for your AI agent. URL: https://samva.dev/features/mailboxes Mailboxes 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 free](https://samva.dev/signup?entry=marketing_page) [Read the mailbox guide](https://samva.dev/docs/mailboxes) A mailbox receives a message. The agent's reply is held by mailbox.action.pending_approval until a person approves it, and then mailbox.message.sent fires. 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. TypeScript example in create-mailbox.ts: import { createClient } from "samva"; const samva = createClient({ apiKey: process.env.SAMVA_API_KEY! }); const created = await samva.mailboxes.create({ 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](https://samva.dev/docs/mailboxes). 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. ## 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 3 mailboxes with 3 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. ## Common questions. ### 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. ### 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 the send mode to approval and a person 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 3 mailboxes with 3 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 email API. - [Send email in one typed call](https://samva.dev/features/transactional-email): Transactional email from the SDK, REST, CLI, or your agent through MCP. Retries are safe. - [Replies land in your app](https://samva.dev/features/inbound-email): Receive on your domain, parsed and threaded to the email it answers, delivered as a signed webhook. - [Change the email without a deploy](https://samva.dev/features/templates): Versioned templates in Git. Review the diff, publish that version. - [Know why an email did or didn't land](https://samva.dev/features/deliverability): SPF and DKIM on your domain, suppression you can see, events for every send. - [Send the announcement too](https://samva.dev/features/campaigns): Campaigns go to a list of contacts from the same templates and domain. - [An inbox for your AI agent](https://samva.dev/features/mailboxes): A mailbox your agent reads and replies from, with a key that reaches only it. ## Give your agent an inbox. [Start sending free](https://samva.dev/signup?entry=marketing_page) [Read the mailbox guide](https://samva.dev/docs/mailboxes)