Overview

Receive a Resend email event, fetch the message’s content, run Voiceflow and send a threaded text reply. The supplied relay verifies the signed webhook before using the Receiving API.

Receiving domain choices. Resend offers managed receiving subdomains and verified domains. This walkthrough starts with the managed address for incoming mail and a verified sender for replies. A sending-only API key or webhook metadata alone is insufficient.

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

Choose the receiving and sending addresses

In Emails → Receiving, find your account’s receiving address under its managed <id>.resend.app subdomain. Set PROVIDER=resend, MAILBOX and REPLY_TO to one chosen address there. Resend accepts any local part on that subdomain; the relay accepts only its configured address/aliases.

Set REPLY_FROM to an address on your separately verified sending domain and complete its DNS authentication. Set RESEND_API_KEY to a key with both sending and receiving access for this implementation. For your own receiving domain, enable receiving and apply the MX value Resend shows; do not overwrite your current mailbox’s MX during a pilot.

2

Subscribe to received messages

Create a webhook in the Resend dashboard with your https://YOUR_RELAY_HOST/inbound URL. Select email.received. Save its signing secret in RESEND_WEBHOOK_SECRET, then start/restart the relay. The receiver verifies the raw body and Svix webhook headers before parsing the event.

Test invalid signatures as well as a valid event. A webhook configured for email.sent or delivery events will not supply incoming support messages. See receiving webhook setup.

3

Fetch content before running the agent

The webhook contains email_id and metadata, not the message body. The adapter calls GET /emails/receiving/{email_id}, with the API key, to obtain text, Internet message_id, headers and attachment metadata. It queues that result before acknowledging the webhook. It does not download attachment content.

If retrieval fails, fix receiving-key permissions or the failed API call before replaying the event. Do not feed the event’s subject alone to the agent as if it were the customer’s message.

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.

The provider email ID suppresses event re-delivery. Internet message_id and sender-scoped references select the session. POST /emails sends plain text with In-Reply-To, References and a Re: subject. reply_to points to the managed receiving address so the customer’s next reply returns through the same route. Receiving permission does not verify the outbound From domain.

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 that the event is email.received, the secret belongs to that webhook, original bytes/headers reach the verifier, and the key can read the received email. A signed metadata event followed by a 403 content fetch does not establish an agent turn. Look at webhook attempts and Receiving API logs separately.

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.

Review both receiving and sending domain state, protect the full-access key, monitor webhook failures/content fetches and outbound bounces. Rotate the API key and webhook secret separately. When moving from a managed to custom receiving address, update MAILBOX/Reply-To and use a new database before changing live routing.

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.