How-to guide

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.

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: connected with OAuth (the Everything preset holds mailbox:manage, see Connect VoiceLayer to 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:

{
  "local": "inbox",
  "answeredBy": { "kind": "controller" },
  "allowSenders": [{ "kind": "email", "value": "[email protected]" }],
  "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:

{ "name": "messages_wait", "arguments": { "mailbox": "[email protected]" } }

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

EventWhen
message.receivedMail from an allowed sender arrived
message.blockedMail from a sender the list refused (no text)
message.pending_reviewA reply was held for a person (no text)
message.sent, message.delivered, message.failedThe approved reply left, arrived or failed
message.discardedReview ended without sending (reason says why; no text)

Common errors

ErrorStatusHow to fix
unauthorized401Send Authorization: Bearer <key> with a secret key from the dashboard (Access → New → Create API key). Test keys start with vl_test_.
insufficient_scope403Use a key with the scope named in details.required, or one whose restriction covers this channel or Binding.
no_sender409Connect a sender for the channel in the dashboard (for email, create a mailbox), or name one in from.

Next steps

On this page