> ## Documentation Index > Fetch the complete documentation index at: https://docs.stackshift.cloud/llms.txt > Use this file to discover all available pages before exploring further. # Mailbox AI, the screener and agent tools > Turn on AI for a domain, summarize and draft with it, screen unknown senders, and let an agent work in only the mailboxes you choose. > [!NOTE] > > **Not yet released.** This guide describes implemented changes awaiting rollout. Availability requires the corresponding backend and dashboard release. ## Goal Use AI in a mailbox without giving an email the power to make your assistant act, and decide exactly which mailboxes an agent can see. ## Prerequisites * A mailbox domain with at least one active mailbox * AI credits in the workspace, or your own model key * To use agent tools: an agent connection in the workspace ## Workflow **Step 1** Turn AI on for the domain with PUT /mail/mailbox-domains/\{domainId}/ai and \{ "enabled": true }. **Step 2** Each person can opt out for themselves on a mailbox with PUT /mail/mailboxes/\{mailboxId}/ai-preference and \{ "optedOut": true }. **Step 3** Open a mailbox to get triage, summaries, drafts and Ask. Turn on the screener if you want unknown senders held back. **Step 4** To connect an agent, grant the connection access to specific mailbox addresses and choose which actions it may use. ## What AI does * Triage ranks conversations and marks them needs a reply, waiting on them or FYI. GET /mail/mailboxes/\{mailboxId}/insights?threadIds=a,b returns the result for the threads you ask about. * Thread summaries give two or three lines and what the sender is asking for: GET /mail/mailboxes/\{mailboxId}/threads/\{threadId}/summary. * Reply suggestions draft an answer in your voice and never send it: POST /mail/mailboxes/\{mailboxId}/threads/\{threadId}/suggestions. * Write with AI turns notes into an email (POST .../compose/from-notes) or rewrites a draft in another tone (POST .../compose/rewrite). * Ask answers a question using your own mail and cites the messages it used: POST /mail/mailboxes/\{mailboxId}/ask. * Follow-up nudges list conversations where nobody replied: GET .../nudges, then POST .../nudges/\{nudgeId}/draft or /dismiss. * A voice profile is a short style card built from your sent mail when you ask for it. Build it with PUT .../voice-profile, read it with GET, and delete it with DELETE. It is never used to train a model. * Snooze hides a thread until a time you choose: POST .../threads/\{threadId}/snooze with a time, and DELETE to bring it back. * AI usage is charged to your AI credit balance. Each paid mailbox includes a monthly allowance. Triage stops, not mail, when credits run out. ## The screener * The screener keeps mail from senders you have not decided on out of the main inbox, so first contact never lands unseen. * Turn it on per mailbox with PUT /mail/mailboxes/\{mailboxId}/screener and \{ "enabled": true }. GET returns the senders waiting for a decision. * POST /mail/mailboxes/\{mailboxId}/screener/decisions takes a kind (address or domain), a value and a decision: let\_in, other or block. * DELETE .../screener/decisions/\{decisionId} undoes a decision. * The screener state (first-time sender, let in, blocked) is shown to AI as a fact about the sender, never as an instruction. ## Safe by design for untrusted mail Text inside an email can never cause an action. Only you, or a rule you wrote, can. * The model that reads a message has no tools. It returns a fixed structure, and every field is validated before you see it. * Hidden text, zero-size text and special characters are stripped before any model reads the message. Links are not opened. * Assistants and agents see the structured result and metadata. When one asks for a message body, it arrives marked as untrusted data, and any action proposed in the same step is dropped. * Every send, reply, forward and rule change needs your approval, tied to the exact recipients and text. Changing the proposal invalidates the approval. * An assistant can send only to people already in the thread or to addresses you typed. Attachments are never added automatically. * AI is off until a domain admin turns it on. Each person can opt out. Your mail is never used to train models, and AI insights are deleted with the message. * POST /mail/mailboxes/\{mailboxId}/ask/actions proposes actions found in your mail, such as adding a date to a calendar, and POST .../ask/actions/\{proposalId}/approve runs one you approved. ## Agent tools Agents use the mailbox.\* actions through an agent connection. Access is granted per mailbox address: you choose which mailboxes an agent can see, and it cannot reach any other. * Read actions run directly: mailbox.threads.list, mailbox.threads.search, mailbox.threads.get, mailbox.threads.summary, mailbox.ask, mailbox.reply.suggest and mailbox.screener.list. * Reversible actions need a granted write permission and an exact approved operation: mailbox.drafts.create, mailbox.threads.snooze, mailbox.threads.archive, mailbox.threads.label and mailbox.screener.decide. * Actions that reach other people always ask you: mailbox.send and mailbox.reply. They are classed as external, cannot be undone, and are approved against the exact arguments. * Every action takes the mailbox\_id of the mailbox it works in. threads.list accepts folder, unread\_only and limit. threads.snooze takes thread\_id and until. threads.label takes add and remove lists. screener.decide takes kind, value and decision. * Drafting is allowed by the mailbox autonomy class. Sending is not, unless you create a standing rule for exact recipients and a template. * An agent can send at most a daily limit of messages per mailbox. Bring-your-own-agent usage is not charged by StackShift. * Message bodies returned to agents are wrapped as untrusted content: instructions inside an email are shown as text and never followed. ## Expected result > [!TIP] > > AI helps with reading and writing mail, unknown senders wait in the screener, and agents act only in the mailboxes you granted, with sending always approved by a person. ## Common failures > [!WARNING] > > * ai\_disabled: the domain admin has not turned AI on, or the mailbox has aiEnabled off. > * ai\_opted\_out: the signed-in person turned AI off for this mailbox. > * ai\_credits\_exhausted: AI credits are used up. Triage stops, and mail keeps arriving and sending as normal. > * changed: the conversation changed after an action was suggested. Ask again to get a fresh suggestion. > * needs\_confirmation: sending needs your explicit approval. Approve the exact action, not a general request. > * send\_limit: the assistant reached its daily limit for sent mail on this mailbox. Drafts are still allowed. ## Related guides > **[Mailboxes](https://docs.stackshift.cloud/stackshift-mail/mailboxes.md)** > > Host real mailboxes on your own domain: add the domain, create mailboxes, aliases and groups, route addresses, bring mail over from another provider and connect any mail app. > **[Inbox placement](https://docs.stackshift.cloud/stackshift-mail/inbox-placement.md)** > > What StackShift does so a new domain reaches the inbox, what it cannot promise, and how to see where your domain stands. > **[Mail through external agents](https://docs.stackshift.cloud/stackshift-mail/external-agent-operations.md)** > > Use explicit workspace and Test or Live action consent for Mail reads, content management, sending and billing preparation. > **[Shared AI credits](https://docs.stackshift.cloud/billing/ai-credits.md)** > > Understand your monthly AI allowance, purchase additional credits, choose your funding source, and track Assets and agent usage. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.