> ## Documentation Index
> Fetch the complete documentation index at: https://www.voiceflow.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Zoho Mail to an agent

> Connect Zoho Mail to Voiceflow with your hosted polling relay. Receive messages from one folder and send replies through the Zoho Mail API.

## Overview

Poll one Zoho Mail account folder, run incoming text through Voiceflow and send replies with Zoho’s message API. The developer hosts the relay and owns OAuth renewal, the queue and conversation state.

**Note:** 

**Protocol alternative.** [IMAP/SMTP](/docs/guides/channels/email/imap-smtp) is a separate completed walkthrough for hosts that allow its authentication method. This manual uses Zoho’s Mail API, not a Voiceflow inbox connector or Zoho shared-mailbox API.

<a id="before-you-begin"></a>

## Before you begin

Prepare the agent, mail access and a supervised test.

Start with an existing [support agent](/docs/guides/usecases/customer-service/build-faq-agent) and public policy content in [Knowledge](/docs/documentation/build/importing-data-sources). The agent owner publishes a reviewed Environment; the backend developer supplies its relay host.

| Requirement | What to obtain |
| --- | --- |
| Voiceflow | Project ID, server-side project API key and the intended released Environment alias. |
| Host | Node 24.14.1, one persistent process and encrypted writable storage for SQLite; a Linux VM with Docker/Compose is the supplied hosting path. |
| Test | A separate sender/recipient inbox you control and a known question with an expected answer. |
| Zoho mailbox | A dedicated user account with Mail API access and permission to send as its own address. Confirm access for your organization and subscription. |
| OAuth client | A server-based application in the Zoho API Console for the account’s data center. |

The sample provides text-only public support. Email addresses are untrusted context; they do not authorize account access. Keep credentials, grants and session keys on the server. It sends to one customer, with no reply-all or file forwarding.

<a id="prepare-relay"></a>

## Prepare the relay

Configure the executable service and persistent queue.

### 1. Configure the supplied implementation

Download and extract the [relay bundle](/docs/examples/email-relay/email-relay.zip). In its `email-relay` folder, use Node 24.14.1 and run:

```sh
npm ci
cp .env.example .env
chmod 600 .env
openssl rand -hex 32
```

Use the generated value for `IDENTITY_SECRET` and keep it stable. Fill `VF_PROJECT_ID`, `VF_API_KEY` and `VF_ENVIRONMENT` with the project owner's values. Set `ACCEPT_AFTER` to a fixed UTC instant just before the pilot, `ALLOW_SENDERS` to your test sender and `AUTO_SEND=false`. The provider steps below supply the remaining fields.

### 2. Keep the processing record

`server.mjs` stores incoming identities, sessions and cached replies in `data/relay.sqlite`. It launches a session with the explicit Environment endpoint, then sends text actions to [`/v4/interact`](/docs/api-reference/conversation/interact-non-stream). Only text response traces become the email body. A completed runtime call does not yet send mail.

Keep one worker per database. The sample re-scans the selected pilot window/folder; it is intended for a small supervised mailbox. It has no distributed worker lease, queue cap or provider-wide rate limiter. Plan those controls before higher-volume public rollout.

<a id="connect-email"></a>

## Connect receiving and replies

Authorize the provider-specific path to your agent.

### 1. Register the Zoho app

In the [Zoho API Console](https://api-console.zoho.com/), create a server-based application. Register `http://localhost:53682/callback`. Copy its client ID and secret into `OAUTH_CLIENT_ID` and `OAUTH_CLIENT_SECRET`; set `PROVIDER=zoho-mail`.

Set `ZOHO_ACCOUNTS` and `ZOHO_MAIL` to your account's matching data-center hosts, such as `https://accounts.zoho.com` and `https://mail.zoho.com` for US accounts. Do not mix regions. The helper requests `ZohoMail.messages.READ`, `ZohoMail.messages.CREATE`, `ZohoMail.accounts.READ` and `ZohoMail.folders.READ`. [Zoho OAuth](https://www.zoho.com/mail/help/api/using-oauth-2.html) supplies an offline grant; access tokens alone expire.

### 2. Authorize and select the folder

Run `node --env-file=.env oauth.mjs` locally and consent as the mailbox owner. Then run:

```sh
node --env-file=.env setup.mjs
```

With `ZOHO_ACCOUNT_ID` empty, this prints account details. Copy the intended account's ID into `.env`; run it again to list folders. Set `ZOHO_FOLDER_ID` to the dedicated receiving folder's ID. IDs are strings: copy them exactly. Set `MAILBOX`, `REPLY_FROM` and `REPLY_TO` to that account's address. The helper stores and refreshes the OAuth grant in SQLite.

### 3. Check the receiving folder

Deliver test mail directly to Inbox, or have the mail administrator create a rule that puts support mail in the selected folder. Keep it there until processed. The adapter paginates [`messages/view`](https://www.zoho.com/mail/help/api/get-emails-list.html), filters `receivedTime` against the fixed cutoff and retrieves [original MIME](https://www.zoho.com/mail/help/api/get-original-message.html). It does not poll only unread mail or mark messages read. No webhook subscription is created.

<a id="host-relay"></a>

## Host the receiver

Keep one authenticated service and its state running.

### 1. Run and check locally

After completing provider configuration, run `npm start`. Check `http://localhost:8080/health`; `running` confirms the process, while poll failures produce HTTP 503. For webhooks, the local URL is not publicly reachable: deploy HTTPS before the provider test.

### 2. Deploy a single persistent service

On a Linux VM with Docker/Compose, upload the folder and private `.env`, then run:

```sh
docker compose create --build
```

For OAuth providers, stop the local process first and copy the authorized database into the service volume **before** starting it:

```sh
docker compose cp data/. relay:/app/data/
docker compose run --rm --user root relay chown -R node:node /app/data
```

Then run `docker compose up -d` and `docker compose logs --tail=50`. The supplied Compose file keeps `/app/data` persistent and binds port 8080 to loopback. Protect the volume and backups as credentials. Do not run a local and hosted worker against the same mailbox simultaneously.

### 3. Expose only the required ingress

Polling providers need outbound access and no public webhook. For webhook providers, point your relay hostname to the VM, install Caddy, allow TCP 80/443 and replace the hostname in the supplied `Caddyfile`. Copy it to `/etc/caddy/Caddyfile` and run `sudo systemctl reload caddy`. Caddy forwards HTTPS to loopback port 8080; check `https://YOUR_RELAY_HOST/health`.

Use `https://YOUR_RELAY_HOST/inbound` at the provider. Preserve raw body bytes and authentication headers. The bundle’s README supplies the same deployment commands and provider-independent operating details; it is included in the download.

<a id="conversation-mapping"></a>

## Route messages and conversations

Map the sender, thread and reply destination deliberately.

Internet Message-ID, In-Reply-To and References map replies within the mailbox/sender scope. The adapter sends a [native reply](https://www.zoho.com/mail/help/api/post-reply-to-an-email.html) to `/accounts/{accountId}/messages/{messageId}` with `action: "reply"`, `fromAddress`, `toAddress`, `subject`, `content` and `mailFormat: "plaintext"`. Zoho owns outgoing thread headers. The source message must remain accessible.

| Incoming event | Relay behavior |
| --- | --- |
| Same delivery again | Durable source ID and Internet Message-ID deduplication suppress another agent turn/send. |
| Customer replies | Reuse the mapped session while it remains active; an ended conversation starts a fresh session. |
| Sender/participants change | Isolate the new sender; no authorization comes from quoting another message ID. |
| Own address, mailing list, automated response or detected spam | Ignore it; no automatic answer loop. |
| Attachment, no usable text, forwarding, changed Reply-To or over 12,000 text characters | Hold for human review; do not send file bytes/HTML to the agent. |
| Runtime/session failure or uncertain sending result | Hold; do not automatically repeat a possibly completed write. |

Quote removal uses provider extraction where supplied plus a small plain-text heuristic. Test your languages and inline replies; it is not a universal parser. For polling, MIME over 10 MiB or invalid MIME creates a body-free `quarantined` source record and later mail continues; answer the original manually at the provider. Oversize webhook requests are rejected before queuing. See [Keep conversations together](/docs/guides/channels/email/keep-conversations-together) and [Handle attachments safely](/docs/guides/channels/email/handle-attachments-safely).

<a id="test-conversation"></a>

## Test an email conversation

Prove receiving, agent execution and customer-visible replies.

### 1. Send a new customer question

From the allowed test inbox, send a plain-text policy question to `MAILBOX`. Inspect the provider's receiving record, then the relay queue:

```sh
node --env-file=.env cli.mjs list
node --env-file=.env cli.mjs show JOB_ID
```

On the host, use `docker compose exec relay node cli.mjs ...` instead. Expect one review item containing the incoming message and an answer from the intended agent. Find the corresponding API conversation in [Transcripts](/docs/documentation/measure/transcripts); compare the question and released agent.

### 2. Approve and verify actual delivery

Read the candidate. Correct it with `cli.mjs reply JOB_ID ./reviewed-reply.txt` if needed, then run `cli.mjs approve JOB_ID` using the same local/host command prefix. After the next worker pass, check `sent`, the provider's sending/activity record, and the actual customer inbox. Confirm From, Reply-To, text and subject. Provider acceptance alone does not establish delivery.

### 3. Continue the thread and check recovery

Reply from that same inbox with a follow-up requiring earlier context. Review/approve the second answer and verify the same thread/session and correct context. Send a separate new subject/message and confirm isolation. Re-deliver a provider event or let polling repeat; expect no extra send for the same Message-ID.

Send an automated response and a message with an attachment; expect ignored and held work respectively. Stop/restart the service and confirm processed mail is not answered again. In the pilot, cause a controlled provider rejection, inspect the held result and complete the recovery procedure below before launch.

<a id="troubleshooting" />

### Incoming mail never reaches the queue

Compare the provider’s receiving record with this relay’s configuration.

Check the account/folder IDs, matching regional hosts and both READ and CREATE message scopes. A 200 HTTP response can contain an API status error; the adapter checks the returned status. Inspect original mail and organization restrictions before reauthorizing or replaying a held reply.

### The message is held or has no reply

Inspect the local state before changing the agent or sending again.

Use `list` and `show` to distinguish `review-input`, `review`, `uncertain-turn` and `uncertain-send`. Review attachments at the original provider. For runtime failures, verify the server key, project, published Environment, credits and transcript; the session may have expired. Unsupported visual/handoff traces need a written human reply. [Review replies before sending](/docs/guides/channels/email/review-replies-before-sending) covers the exact queue commands.

### The provider accepted the reply but no email arrived

Check final delivery before retrying a cached response.

Inspect the provider's delivery, suppression and bounce records and the test inbox's spam folder. Compare recipient, sender authorization and domain authentication. A successful API response, queued webhook or `sent` record is not evidence of inbox placement. If the outcome is uncertain, keep it held and use the recovery steps below.

<a id="go-live"></a>

## Release and maintain the connection

Move the reviewed route into service and recover safely.

Keep the API client and grant in the mailbox’s data center, monitor refresh failures and confirm the folder rule remains active. A rule that moves mail elsewhere changes receiving coverage; test it before enabling automatic replies.

### 1. Release the intended support route

Publish the reviewed agent and confirm the explicit `VF_ENVIRONMENT` alias. For project, mailbox, Environment, cutoff or identity-secret changes, drain/resolve old work and use a fresh database; the deployment fingerprint rejects accidental reuse. Keep an available human support route while moving the provider's receiving configuration.

### 2. Repeat the customer test in production

Repeat [the complete conversation test](#test-conversation) through the production address and released Environment. Keep review-first until the results are accepted. `AUTO_SEND=true` sends later eligible text replies automatically; `[HUMAN_REVIEW]`, unsupported output and held input still require review. Expand `ALLOW_SENDERS` only for the reviewed support scope; `*` admits public senders and grants no account authorization.

### Recover an uncertain turn or send

Resolve remote effects before replaying work.

Stop the worker first. Inspect the runtime transcript and provider sent/activity logs. For `uncertain-send`, use `cli.mjs mark-sent JOB_ID` if accepted. Only after confirming it was not sent, use `cli.mjs retry-send JOB_ID --confirmed-not-sent`; this retries the cached reply without another agent turn. If delivery cannot be determined, leave it held and resolve manually.

For `uncertain-turn`, check tool side effects before `cli.mjs restart JOB_ID --reviewed-side-effects`. This starts a new session and may repeat agent actions; it does not restore lost context. Locally use `node --env-file=.env`; while Docker is stopped use `docker compose run --rm relay node cli.mjs ...`. Restart the worker after reconciling the job.

### Rotate, retain or remove the connection

Maintain credentials and durable state without replaying old mail.

Rotate provider credentials with a new pilot message, retaining the identity secret, cutoff and database for an ordinary restart. Monitor held jobs, oldest pending work, polling/webhook failures, disk use and bounces. Provider retry windows are finite: reconcile original mail against the queue after outages.

Stop the service for a consistent database backup; encrypt/restrict it and include its retention in your policy. The example has no automatic purge. Coordinate deletion of provider mail, local bodies/grants, runtime transcripts and backups. Deleting state loses deduplication and can replay old mail; resolve pending work and use a deliberate new cutoff for a replacement deployment.

To remove, first move receiving/forwarding to human support, drain pending work, stop the service, revoke its grants/keys/passwords and remove obsolete DNS. Confirm new customer mail still reaches the replacement route.
