> ## 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 Outlook to an email agent

> Connect Outlook or Microsoft 365 email to Voiceflow with a hosted polling relay, delegated OAuth and Microsoft Graph replies.

## Overview

Poll an Outlook.com or Microsoft 365 user mailbox with Microsoft Graph, run a Voiceflow text turn and send a native reply. This walkthrough uses delegated OAuth for the signed-in mailbox and a developer-hosted relay.

**Note:** 

**Other Microsoft routes.** Graph [change notifications](https://learn.microsoft.com/en-us/graph/outlook-change-notifications-overview) can replace polling, but require subscription renewal and notification handling. This manual implements polling for `/me`; shared-mailbox and application-permission deployments require separate permission and sender configuration.

<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. |
| Microsoft account | A dedicated Outlook.com or Microsoft 365 user mailbox; an administrator who can approve the app if tenant policy requires it. |
| Entra application | An app registration that accepts your account type, a Web redirect URI and a client secret. |

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 a delegated application

In Microsoft Entra **App registrations**, create an app for the account types you intend to use. Add a **Web** redirect URI of `http://localhost:53682/callback`. Create a client secret and record its value, not its identifier.

Add delegated Microsoft Graph permissions **Mail.Read** and **Mail.Send**. Request **offline_access** during consent. Mail.ReadBasic omits content needed by this receiver. Obtain administrator consent if tenant policy requires it; this example does not request application permissions or access another user's mailbox. See the [authorization code flow](https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow).

### 2. Authorize the intended mailbox

Set `PROVIDER=outlook`, `OAUTH_CLIENT_ID`, `OAUTH_CLIENT_SECRET` and `MS_TENANT` in `.env`. Use your tenant ID for a single organization, or `common` only when the app registration permits the intended personal/work account types. Set `MAILBOX`, `REPLY_FROM` and `REPLY_TO` to the signed-in mailbox.

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

Open the printed URL locally and consent with the pilot mailbox. The callback saves its offline grant in SQLite. The relay stores rotated refresh tokens in that same database; keep it writable and protected.

### 3. Check the Inbox polling scope

The adapter [lists Inbox messages](https://learn.microsoft.com/en-us/graph/api/user-list-messages?view=graph-rest-1.0) after `ACCEPT_AFTER`, follows `@odata.nextLink`, and fetches each unseen message's MIME content. It requests immutable message IDs. No subscription or validation callback is needed. Messages moved out of Inbox before a poll are outside the chosen path.

<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.

Graph `conversationId`, mailbox and sender select the session. The adapter calls [`POST /me/messages/{id}/reply`](https://learn.microsoft.com/en-us/graph/api/message-reply?view=graph-rest-1.0) with a plain-text body. Graph owns threading, the sender and Sent Items; it may honor the original Reply-To, so a differing Reply-To is held for human review. A 202 response means acceptance, not inbox delivery.

| 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 delegated Mail.Read/Mail.Send, the signed-in account, tenant consent and client-secret expiry. Read access does not confer Send As for a shared mailbox. Keep the original message in the selected mailbox; a moved or removed message can make its native reply fail.

### 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.

Verify the app’s tenant/account audience, consent and secret expiry before moving support mail to it. Preserve rotated grants during deployment and monitor token failures. Subscription renewal is not part of this polling implementation.

### 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.
