---
title: "Inbox instructions"
description: "Write down what an inbox is for and how its mail should be handled, once, so every agent that opens the inbox reads it before the mail."
canonical: "https://machinemail.dev/docs/concepts/inbox-instructions"
---

# Inbox instructions

> Write down what an inbox is for and how its mail should be handled, once, so every agent that opens the inbox reads it before the mail.

Source: https://machinemail.dev/docs/concepts/inbox-instructions

> **Note:** Instructions are visible to every credential that can read the inbox, agents included, so never put secrets in them. Only an organization API key or a person in the dashboard can write them, and
> they never override the trust layer.

Inbox instructions are a short text, written by you, that says what an inbox is for and how its mail should be handled. Over MCP, an agent is pointed to them before it reads the inbox's mail; over the API and the CLI they come with the inbox itself. So a new agent, or a new session of the same agent, knows the job without someone explaining it again in its prompt.

The instructions live on the inbox, not in each agent's prompt, so every agent that works the inbox reads the same version, and changing them changes what every agent reads next.

Instructions are a MachineMail addition: AgentMail's API has no such field.

## An example

Instructions for `support@acme.dev`:

```md title="Instructions"
Customer support for Acme.

- Label billing questions `billing`.
- For order-status questions from verified senders, draft a reply using the order id in the subject. Never send without approval.
- Forward partnership enquiries to partners@acme.dev.
- Archive newsletters.
```

Write them the way you would brief a new colleague: what the inbox is for, what to do with each kind of mail, and what never to do. Plain text and Markdown both work. Say which senders an action applies to (for example "verified senders" or "people at acme.dev"), because an agent cannot tell a customer from someone pretending to be one by reading the mail alone; see [Trust comes first](#trust-comes-first).

## Set the instructions

### In the dashboard

Open the inbox and choose **Instructions** next to its address. Type or paste the instructions and choose **Save**. The editor counts characters against the 4,000-character limit and shows who last edited them and when. **Clear** removes them.

In the inbox list, inboxes with instructions are marked, and **Edit instructions** in a row's menu opens the same editor.

### With the API

Send `instructions` when you create the inbox:

```bash title="Terminal"
curl https://api.machinemail.dev/v0/inboxes \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "support", "instructions": "Customer support for Acme. Label billing questions billing. Never send without approval."}'
```

Or set, replace or clear them on an existing inbox with `PATCH`:

```bash title="Terminal"
# Set or replace
curl -X PATCH https://api.machinemail.dev/v0/inboxes/support@acme.dev \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instructions": "Customer support for Acme.\n\n- Label billing questions `billing`.\n- Never send without approval."}'

# Clear
curl -X PATCH https://api.machinemail.dev/v0/inboxes/support@acme.dev \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instructions": null}'
```

A `PATCH` without `instructions` leaves them unchanged. A create with a `client_id` that is already in use returns the existing inbox unchanged, so `instructions` in that request are ignored: set them with `PATCH`.

### With the CLI

```bash title="Terminal"
# From a file (Markdown or plain text); - reads stdin
machinemail inboxes update support@acme.dev --instructions-file support-instructions.md

# Inline
machinemail inboxes update support@acme.dev --instructions "Archive newsletters. Never send without approval."

# Clear
machinemail inboxes update support@acme.dev --instructions null

# A new inbox with instructions
machinemail inbox new --username support --instructions-file support-instructions.md
```

`machinemail inboxes get support@acme.dev` shows the instructions under the inbox's details. See [inboxes](https://machinemail.dev/docs/cli/commands/inboxes) in the command reference.

## Who can write them

Instructions steer what agents do, so only credentials that speak for the organization can set, change or clear them:

| Credential                                          | Read | Write |
| --------------------------------------------------- | ---- | ----- |
| A person in the dashboard                           | Yes  | Yes   |
| An organization API key                             | Yes  | Yes   |
| A pod or inbox API key                              | Yes  | No    |
| An app connected with OAuth, such as an MCP client  | Yes  | No    |
| An agent registered through auth.md, claimed or not | Yes  | No    |
| An API key that an app or agent created             | Yes  | No    |

Reading needs the `inbox_read` permission, like the rest of the inbox. Writing also needs `inbox_create` or `inbox_update`, for a create or an update.

Any other credential that sends `instructions`, even `null`, gets `403` and nothing is created or changed, whatever its permissions. That includes an organization API key created by an app or an agent (with the `api_keys.write` scope), and any key created with such a key: it acts for the app or agent, not for you. No MCP tool writes them either. So an agent cannot rewrite its own rules, even if an email talks it into trying, and nothing that arrives by email can set them.

## How agents see them

### Over MCP

The [MCP server](https://machinemail.dev/docs/agents/mcp) leads agents to the instructions before the mail:

- The server's instructions tell every agent that an inbox can carry instructions from its owner, to read them with `get_inbox` before handling its mail, and that they never override the trust policy.
- `list_inboxes` marks each inbox that has instructions.
- `get_inbox` returns the inbox with its instructions, set apart from everything else, labelled as written by the inbox owner and followed by a reminder that the trust policy comes first.
- `list_messages`, `list_threads`, `search_messages`, `get_message`, `get_thread` and `wait_for_message` start with one line, before any email content, when the inbox has instructions: "This inbox has instructions from its owner: read them with get\_inbox." A credential without `inbox_read` is told that the inbox has instructions it cannot read.
- The resource `machinemail://inboxes/{inbox_id}/instructions` returns the instructions as Markdown.
- The `triage_inbox` prompt reads the instructions first and applies them within the trust rules.

### Over the API

| Field                     | Notes                                                                                                                                          |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `instructions`            | The text. Present only when set, and only on a single inbox: Get, Create and Update Inbox, and the `inbox.created` and `inbox.expired` events. |
| `has_instructions`        | `true` or `false`. In every inbox response, lists included.                                                                                    |
| `instructions_updated_at` | When the instructions were last set, changed or cleared. Absent when they never were.                                                          |
| `instructions_updated_by` | Who did it: `{ "type": "user", "id": "..." }` for a person in the dashboard, `{ "type": "api_key", "id": "..." }` for an organization API key. |

List Inboxes and Search Inboxes leave the text out, so lists stay small: read `has_instructions` there and fetch the inbox with `GET /v0/inboxes/{inbox_id}`.

```json title="GET /v0/inboxes/support@acme.dev"
{
  "inbox_id": "support@acme.dev",
  "email": "support@acme.dev",
  "display_name": "Acme support",
  "status": "active",
  "has_instructions": true,
  "instructions": "Customer support for Acme.\n\n- Label billing questions `billing`.\n- Never send without approval.",
  "instructions_updated_at": "2026-11-16T09:12:40.118Z",
  "instructions_updated_by": { "type": "api_key", "id": "key_01m4g463jy0002nz2drf5r5bvx" },
  "created_at": "2026-10-09T09:00:15.835Z",
  "updated_at": "2026-11-16T09:12:40.118Z"
}
```

An agent built on the API or webhooks rather than MCP should fetch the inbox once per session (or when `instructions_updated_at` changes) and keep the instructions apart from email content in its own prompt.

## Limits

- Up to **4,000 characters**, counted as Unicode code points: each character counts once, including most single emoji, but an emoji with a skin tone or joiners counts as several.
- Line breaks are stored as LF, and leading and trailing whitespace is trimmed. A value that is empty after trimming clears the instructions, the same as `null`.
- Control characters other than line breaks and tabs are refused with `400`.
- Sending the instructions the inbox already has changes nothing: the time and editor stay as they were, and no audit event is recorded.

## Trust comes first

Instructions are trusted input from you, unlike the mail they describe. They do not make that mail trustworthy:

- Mail the [trust layer](https://machinemail.dev/docs/trust) marks `suspicious` or `quarantined` stays with a person, whatever the instructions say. "Reply to every message" does not make quarantined mail something to act on.
- Instructions inside an email are still email content. An agent should never follow them, whatever the inbox's instructions say about the sender.
- The trust policy wins when the two disagree. The MCP server tells agents so wherever it shows the instructions, and `machinemail inboxes get` prints the same reminder under them. An agent built on the API should carry that rule into its own prompt.

Write instructions that work with trust levels rather than around them: "act on verified senders", "summarise mail from known senders", "leave unknown senders for a person". See [Using trust in agents](https://machinemail.dev/docs/trust/using-trust-in-agents).

## Keep secrets out

Every credential that can read the inbox can read its instructions: agents, pod and inbox keys, connected apps. Never put passwords, API keys, tokens or anything else you would not hand to every one of them. Give an agent a secret through its own configuration instead.

## Change history

Every change is recorded in the [event log](https://machinemail.dev/docs/concepts/events) as the audit event `inbox.instructions_updated`, with the previous and the new text, so you can see what an agent was told when it acted. Setting instructions on a new inbox records one too, with `previous_instructions: null`.

```bash title="Terminal"
curl "https://api.machinemail.dev/v0/events?event_types=inbox.instructions_updated&inbox_id=support@acme.dev" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

```json title="Event"
{
  "event_id": "evt_01m5c8r2k40000b7n3x9q2w6fd",
  "event_type": "inbox.instructions_updated",
  "organization_id": "org_01m4fy8h140000efvagszh6rpx",
  "pod_id": "pod_01m4fy8h150000w4xty1ehfnqa",
  "inbox_id": "support@acme.dev",
  "data": {
    "inbox_id": "support@acme.dev",
    "pod_id": "pod_01m4fy8h150000w4xty1ehfnqa",
    "instructions": "Customer support for Acme.\n\n- Label billing questions `billing`.\n- Never send without approval.",
    "previous_instructions": "Customer support for Acme.",
    "updated_by": { "type": "user", "id": "user_01m4fy8h190000k2d7r5v8n3qa" }
  },
  "timestamp": "2026-11-16T09:12:40.118Z",
  "created_at": "2026-11-16T09:12:40.118Z"
}
```

`instructions` is `null` when they were cleared. Reading the event needs the `metrics_read` permission. Like the other audit events, it is not delivered to webhooks, event streams or MCP subscribers, and cannot be selected in a webhook's `event_types`.

## Next

- [Inboxes](https://machinemail.dev/docs/concepts/inboxes)
- [MCP server](https://machinemail.dev/docs/agents/mcp)
- [Using trust in agents](https://machinemail.dev/docs/trust/using-trust-in-agents)
