Skip to main content
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

1
Turn AI on for the domain with PUT /mail/mailbox-domains/{domainId}/ai and { “enabled”: true }.
2
Each person can opt out for themselves on a mailbox with PUT /mail/mailboxes/{mailboxId}/ai-preference and { “optedOut”: true }.
3
Open a mailbox to get triage, summaries, drafts and Ask. Turn on the screener if you want unknown senders held back.
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

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

  • 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.

Mailboxes

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

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

Use explicit workspace and Test or Live action consent for Mail reads, content management, sending and billing preparation.

Shared AI credits

Understand your monthly AI allowance, purchase additional credits, choose your funding source, and track Assets and agent usage.