---
title: "Tell every agent what an inbox is for"
description: "Write instructions on an inbox once, in plain text or Markdown, and every agent that opens the inbox reads them before its mail. Only you can write them, and they never override the trust layer."
canonical: "https://machinemail.dev/changelog/inbox-instructions"
date: "2026-11-17"
---

# Tell every agent what an inbox is for

> Write instructions on an inbox once, in plain text or Markdown, and every agent that opens the inbox reads them before its mail. Only you can write them, and they never override the trust layer.

- Date: 2026-11-17
- Tags: Dashboard, API, CLI, MCP
- Video: https://machinemail.dev/changelog/media/inbox-instructions.mp4 (A simplified MachineMail dashboard. On the inbox support@acme.example, Instructions · none opens the Instructions for agents dialog. Markdown is typed in, a heading and three rules, while the counter climbs to 144 / 4,000; the Preview tab shows it rendered. Save closes the dialog, a toast says Instructions saved and the button now reads Instructions · set. A terminal shows an agent calling list_messages, which first says the inbox has instructions from its owner, then get_inbox, which returns them inside an inbox_instructions block followed by a reminder that they never override the trust policy. It ends on the MachineMail logo.)
- Source: https://machinemail.dev/changelog/inbox-instructions

Until now, an agent learned what an inbox was for from its own prompt, so every new agent, and every new session, had to be told again. Now the inbox can tell it. Open an inbox in the dashboard and choose **Instructions** next to its address, write what the inbox is for and how its mail should be handled, and save. Every agent that works the inbox reads the same version, and changing it changes what each agent reads next.

- **Write them like a brief.** Plain text or Markdown, up to 4,000 characters. The editor has **Write** and **Preview** tabs, counts characters as you type and shows who last edited the instructions and when. **Clear** removes them, with Undo.
- **Agents read them first.** Over MCP, `get_inbox` returns the instructions in their own block, labelled as written by you. Every tool that reads the inbox's mail starts with one line pointing to them, before any email content. Over the API and the CLI they come with the inbox itself.
- **Only you can write them.** A person in the dashboard or an organization API key can set them. Pod and inbox keys, connected apps and agents can read them but get `403` if they try to change them, and no MCP tool writes them. So an email can't talk an agent into rewriting its own rules.
- **Trust still comes first.** Instructions never make mail trustworthy. Suspicious and quarantined mail stays with a person whatever they say, and agents are reminded of that wherever the instructions appear.
- **Every change is on record.** Each edit is an `inbox.instructions_updated` audit event in the event log, with the previous and the new text, so you can see what an agent was told when it acted.
- **Set them from anywhere.** Send `instructions` when you create an inbox or with `PATCH /v0/inboxes/{inbox_id}`, or run `machinemail inboxes update --instructions-file`. Inboxes with instructions are marked in the inbox list, and **Edit instructions** in a row's menu opens the same editor.

Instructions are visible to every credential that can read the inbox, so keep secrets out of them.

Read more: [Inbox instructions](https://machinemail.dev/docs/concepts/inbox-instructions).
