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.

Other Microsoft routes. Graph change notifications 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.

Before you begin

Prepare the agent, mail access and a supervised test.

Start with an existing support agent and public policy content in Knowledge. The agent owner publishes a reviewed Environment; the backend developer supplies its relay host.

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.

Prepare the relay

Configure the executable service and persistent queue.

1

Configure the supplied implementation

Download and extract the relay bundle. In its email-relay folder, use Node 24.14.1 and run:

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

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.

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.

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

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:

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

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.

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

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 and Handle attachments safely.

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:

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

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

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

Use the up and down arrow keys to select a result, Enter to open it, and Escape to close the search.