Skip to main content

Build a support inbox agent

A shared inbox groups received mail and your replies into conversations. There are two ways to put an agent on it:

Autopilot (in Zyphr)Your own agent
RunsIn Zyphr's workflow engineAnywhere you run code (or Claude Code)
Triggered byinbox.email.receivedinbox.* webhooks, or on demand
Acts withinbox_reply and inbox_update workflow stepsThe MCP tools or the API
Good forAcknowledgements, routing, labellingReading the mail and writing real answers

Both can run together: autopilot acknowledges and labels within seconds, and your agent writes the answer.

How it fits together​

Option 1: Autopilot​

Autopilot is a workflow that starts when mail arrives in an inbox. Its steps act on the conversation the email landed in.

Set it up in the dashboard​

  1. Go to Workflows → Create Workflow and name it, for example Support acknowledgement.
  2. Under Event Triggers, click Add. Choose Source: Platform Event, then inbox.email.received from the Inbox group.
  3. In Only for inbox, pick the inbox it should answer, for example support. Left on All inboxes, it runs for mail in every inbox, including the catch-all. Click Add Trigger.
  4. From the Step Palette, drag Update thread (inbox_update) onto the canvas, select it, and choose labels to add, a folder to move to, or mark as read. Click Save Step.
  5. Drag Inbox reply (inbox_reply) below it and write the reply text. {{payload.subject}} and {{payload.from.email}} are filled in. Leave From empty to send from the inbox address the email arrived at (or, for forwarded mail, from your own address it was forwarded from). Click Save Step.
  6. Click Activate.

Inbox steps need a plan that includes inbound email (Starter or higher).

Inbox triggers always run without a subscriber. The people who email you aren't your app's users, Zyphr doesn't create subscribers for them, and a sender's From address is never used to pick one, because it isn't proof of identity. Team notifications (Slack, Discord, Teams) work in these workflows; steps that message a subscriber (email, push, SMS, in-app) are skipped.

Steps over the API​

Event triggers are set up in the dashboard. The workflow's steps can also be added and changed with an API key (POST /v1/workflows/{key}/steps):

{ "type": "inbox_update", "config": { "add_label_ids": ["<label id>"] } }
{ "type": "inbox_reply", "config": { "text": "Thanks for writing in about \"{{payload.subject}}\". We'll reply within one business day." } }

inbox_reply also takes html and from; inbox_update also takes folder, read, assignee_user_id and remove_label_ids. Steps that message a subscriber are skipped on inbox runs, and {{payload.from.email}} works in Slack, Discord and Teams steps too.

Example: Pat writes in​

With the workflow above active on the support inbox:

  1. Pat (pat@example.org) emails support about being charged twice. Zyphr stores it in a new thread and fires inbox.email.received.
  2. The trigger matches and starts a run with no subscriber.
  3. Update thread adds the new label, so your team sees it tagged.
  4. Inbox reply checks the email (below), then sends Re: Charged twice in the same thread, marked Auto-Submitted: auto-replied.
  5. A person, or your own agent, writes the real answer in the same conversation.

If Pat's address had been forged, the email fails DMARC: the thread still gets the label, but no reply is sent. If Pat has an out-of-office, its reply to the acknowledgement carries Auto-Submitted and is dropped on arrival.

Loop protection​

An auto-responder must never get into a reply loop or be turned against someone. Every automatic reply goes through these checks, and is skipped (the thread updates still happen) at the first one that fails:

In detail:

  • It only answers a newly received email, once. A run started by another inbox event (a thread assigned or moved, a reply your team sent) never sends an automatic reply, and re-running a workflow for the same email doesn't send a second one.

  • It only replies to authenticated senders. An email whose From didn't pass DMARC gets no automatic reply, so a forged message can't make autopilot mail someone else. The thread is still updated. Mail relayed by your own Google Group counts as authenticated when Google's ARC seal records DMARC passing.

  • Auto-replies, bounces and list mail never reach it. Mail with Auto-Submitted, Precedence: bulk/list/auto_reply, an empty Return-Path, or X-Auto-Response-Suppress is dropped when it arrives. The one exception is your own Google Group (say support@ is a group): it marks everything it relays as list mail, so its relays are let through (details).

  • It never replies to your own address. Mail that arrives "from" the address it came through gets no automatic reply.

  • Its own replies are marked Auto-Submitted: auto-replied (RFC 3834), so a well-behaved system, including another Zyphr autopilot, won't answer them.

  • No-reply senders are skipped (noreply@, do-not-reply@, mailer-daemon@, postmaster@, notifications@, ...).

  • At most 3 automatic replies per thread per 24 hours, in case a misbehaving auto-responder keeps answering anyway, and at most 200 per project per hour.

  • What autopilot does never triggers a workflow. Its replies and thread changes have source: agent, and agent events never start runs.

Option 2: Your own agent​

Point an AI agent at the inbox with the Zyphr MCP server. The inbox tools are:

  • Read: list_inboxes, list_inbox_threads, get_inbox_thread, list_inbox_thread_emails, list_inbox_labels, list_inbox_drafts.
  • Act: reply_to_inbox_thread, forward_inbound_email, update_inbox_thread, set_inbox_thread_labels, create_inbox_label, create_inbox_draft, update_inbox_draft, send_inbox_draft.

For example, in Claude Code:

claude mcp add zyphr --env ZYPHR_API_KEY=zy_live_... -- npx -y @zyphr-dev/mcp-server

Then ask: "Go through my unread support threads. Label each one billing, bug or other, draft a reply for each, and send the ones you're confident about."

The key needs inbound:read to read, inbound:write to triage and draft, and email:send to reply. To keep a human in the loop, give the agent a key without email:send. It can then only save drafts, which your team reviews and sends from the dashboard. Set ZYPHR_READ_ONLY=true for an agent that may only read.

To react as mail arrives instead of polling, subscribe a webhook to inbox.email.received (see Webhook Event Types). The payload has the thread_id and metadata only, never the body. Your handler fetches the conversation with list_inbox_thread_emails and decides what to do.