# Give an outside agent an inbox

> Let an agent that runs outside VoiceLayer, such as ChatGPT or your own code, own an email address, wait for mail, reply, and have a person approve what it sends.

Source: https://docs.vlayers.ai/developers/outside-agent-inbox

Kind: How-to guide

## What you'll build

An email address that **an agent outside VoiceLayer answers**. VoiceLayer receives and records the mail, keeps the conversation, and checks who may write to it. The outside agent waits for mail, reads it and replies; VoiceLayer's own agents do not touch it. You stay in control: you decide who may write to the address, whether each reply waits for approval before it leaves, and you can revoke the agent at any time.

## Prerequisites

- A workspace with a free mailbox seat. The Free plan has 3 seats. A seat past your plan is refused with `seat_limit`.
- An agent that can call VoiceLayer's [MCP server](https://docs.vlayers.ai/developers/mcp): connected with OAuth (the **Everything** preset holds `mailbox:manage`, see [Connect VoiceLayer to ChatGPT, Claude, Cursor](https://docs.vlayers.ai/get-started/connect-chatgpt-claude-cursor)), or an API key with the `mailbox:manage` scope.

## Step 1: Create the mailbox, answered by the agent

Ask the agent to call the `mailbox_create` tool (or create the mailbox in the dashboard: **Channels**, then **Manage** on the mailbox row). `answeredBy` says who replies:

```json
{
  "local": "inbox",
  "answeredBy": { "kind": "controller" },
  "allowSenders": [{ "kind": "email", "value": "boss@example.com" }],
  "reviewBeforeSend": true
}
```

- `answeredBy: { "kind": "controller" }` means nobody inside VoiceLayer replies: whoever holds a credential for the workspace does (the outside agent, your code, a person in the dashboard). `{ "kind": "agent", "agentId": ... }` is a VoiceLayer agent, which replies on its own.
- The first mailbox also picks your workspace address (the part after the `@`) with `label`. Later mailboxes reuse it.
- The answerer is stored in the same step that creates the mailbox, so there is no moment when a first message could reach an agent you did not choose.

## Step 2: Choose who may write to it

`allowSenders` lists the people or addresses that can reach the mailbox. Left out, **anyone** can write to it, and the dashboard says so plainly. A message from a sender not on the list is still recorded and shown to you, but the agent is never told it arrived: it is published as `message.blocked`, with no text.

Email senders pass only on mail the channel could verify (DMARC, or aligned DKIM and SPF). Opening a locked mailbox back to anyone takes a typed confirmation, in the dashboard and in the tool (`mailbox_update` with `senders` set to `anyone` and `confirm`). Ask the owner to say yes first. A key limited to one mailbox cannot change the list at all.

## Step 3: The agent waits, reads and replies

The agent loops on `messages_wait` with the mailbox, so it only wakes for this address:

```json
{ "name": "messages_wait", "arguments": { "mailbox": "inbox@acme.vlayersmail.com" } }
```

It reads the conversation with `conversation_read` and answers with `message_reply`. Pass an `idempotencyKey` on a reply that may be retried. Events are at-least-once: after an outage, `messages_wait` with the last cursor replays what was missed.

An app limited to this mailbox (**Limit to…** on the Access page) sees only this mailbox's mail, whether or not it passes the filter.

## Step 4: Review before send

With `reviewBeforeSend` on, nothing the mailbox sends leaves until it is approved: by you in the dashboard, or by the agent or app you connected, which can approve with `draft_approve` on its own send permission (you can turn the switch off if you do not want that check). That covers the outside agent, your API calls and a VoiceLayer agent's replies alike:

1. The agent's `message_reply` is answered `202` with status `pending_review`. The message is held; nothing was sent.
2. `message.pending_review` is published.
3. In **Conversations**, the conversation shows the draft with **Send**, **Edit and send** and **Discard**. The same three actions are the tools `draft_approve` (with new words in `text` to edit), `draft_discard` and `drafts_list`/`draft_get` to see what waits. Sending runs the normal send pipeline (the Output Guard, limits, the do-not-contact list), so a held message can still be refused at that moment, and then it stays held for you to fix or discard.
4. The outcome is `message.sent` (and then `message.delivered` or `message.failed`) on the same message, or `message.discarded` with a reason: `discarded_by_reviewer`, or `review_expired` when nobody looked within the review window (7 days by default).

The draft and the access log record who approved: `user:<id>` for a person, `key:<id>` for an API key, `grant:<id>` for a connected app. Review before send is on or off from chat (`mailbox_update` with `reviewBeforeSend`) or from the mailbox's settings in the dashboard, the same either way.

You can also write an email without sending it: `draft_create` keeps it as a draft, `draft_update` changes it and `draft_send` sends it. An unsent draft is thrown away after the review window.

The held reply's text is not in `message.pending_review` or `message.discarded` (`text` is `null`): it has not passed the Output Guard until it is sent. Read the draft in **Conversations**.

If a VoiceLayer agent answers the mailbox, its reply is held too, and its conversation turn waits (`waiting_review`) until the draft is decided.

## Step 5: Change it later

The mailbox's settings in the dashboard (**Channels**, then **Manage** on the mailbox row) and the `mailbox_update` tool change the same things: who answers, who may write, whether review is on, and which senders are kept out. A key or app with `mailbox:manage` for the whole workspace can change all of them. A key limited to one mailbox can only turn review before send on or off, or turn on "only send from saved replies"; it cannot change its own sender list or who answers it. Changing who answers moves the **next** conversation, not an open one; an open conversation keeps its controller until it is handed over.

Creating a mailbox again at an address you released is also left to a signed-in person.

## Step 6: Revoke the agent

Open **Access**, find the app, choose **Revoke**. Its waits and replies fail with `token_revoked` within a minute. Mail keeps arriving and stays visible in the dashboard; nothing is lost when the agent is.

## Test it

Create the mailbox with `reviewBeforeSend: true`, send it a mail from your own address, and ask the agent to reply. You should see: the mail in **Conversations**, the agent's reply held as a draft, and, after **Send**, the reply in your inbox. Watch the sequence in the event stream: `message.received`, `message.pending_review`, `message.sent`.

## Events

| Event | When |
|---|---|
| `message.received` | Mail from an allowed sender arrived |
| `message.blocked` | Mail from a sender the list refused (no text) |
| `message.pending_review` | A reply was held for a person (no text) |
| `message.sent`, `message.delivered`, `message.failed` | The approved reply left, arrived or failed |
| `message.discarded` | Review ended without sending (`reason` says why; no text) |

## Common errors

| Error | Status | How to fix |
|---|---|---|
| [`unauthorized`](https://docs.vlayers.ai/errors/unauthorized) | 401 | Send `Authorization: Bearer <key>` with a secret key from the dashboard (Access → New → Create API key). Test keys start with `vl_test_`. |
| [`insufficient_scope`](https://docs.vlayers.ai/errors/insufficient_scope) | 403 | Use a key with the scope named in `details.required`, or one whose restriction covers this channel or Binding. |
| [`no_sender`](https://docs.vlayers.ai/errors/no_sender) | 409 | Connect a sender for the channel in the dashboard (for email, create a mailbox), or name one in `from`. |

## Next steps

- [Access and keys](https://docs.vlayers.ai/get-started/access-and-keys): limit and revoke the agent.
- [Send an email](https://docs.vlayers.ai/developers/send/email) and [Event stream](https://docs.vlayers.ai/developers/receive/event-stream).
