> ## 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 Amazon SES to a Voiceflow agent

> Connect Amazon SES inbound email to Voiceflow using S3 and a hosted polling worker, then deliver text replies with SES.

## Overview

Receive support email through an Amazon SES receipt rule, store its MIME message in S3, then let a hosted worker run Voiceflow and reply with SES. This walkthrough polls S3; it does not require a public webhook.

**Note:** 

**Other receiving routes.** SES also offers [Lambda and SNS receipt actions](https://docs.aws.amazon.com/ses/latest/dg/receiving-email-action.html). This completed walkthrough uses S3 polling. An SES sending identity, SMTP credential or Voiceflow send tool alone does not receive support mail.

<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. |
| AWS administrator | DNS, SES identities/rule sets, S3 and IAM access in a region that supports SES receiving. |
| Receiving address | A dedicated subdomain, for example `support@reply.example.com`; do not replace an existing mailbox domain’s MX during a pilot. |
| Worker role | S3 ListBucket/GetObject for the inbound prefix, and SES SendRawEmail for the verified sending identity. |

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. Prepare the receiving domain

Select one [SES receiving region](https://docs.aws.amazon.com/ses/latest/dg/regions.html#region-receive-email), and use it as `AWS_REGION`. Verify the domain in SES with its required DNS records. Publish the receiving subdomain's MX with priority 10 pointing to `inbound-smtp.REGION.amazonaws.com`, replacing REGION with the selected region. Domain identity verification and receiving MX are separate requirements.

Create a private S3 bucket in that region. Set `SES_BUCKET` to its name and `SES_PREFIX=inbound/`. Give SES write permission using AWS's [S3 receipt policy](https://docs.aws.amazon.com/ses/latest/dg/receiving-email-permissions.html), restricted to your account/rule ARN and bucket. Keep public access blocked.

### 2. Activate a receipt rule

In SES **Email receiving**, create a rule set and a rule matching only the pilot recipient. Enable the rule and add **Deliver to S3 bucket** with your bucket and `inbound/` prefix. Save it, then make the rule set active. Enable spam/virus scanning and follow your organization's rejection policy before mail reaches the worker.

Leave the receipt action’s optional **Message encryption** off for this example: it uses client-side encryption that this Node reader does not decrypt. S3 server-side encryption at rest is a separate control. See the [S3 action contract](https://docs.aws.amazon.com/ses/latest/dg/receiving-email-action-s3.html).

### 3. Authorize receiving and sending independently

Attach a workload IAM role to the host; the AWS SDK uses its default credential chain. Grant `s3:ListBucket` on the bucket with the prefix condition, `s3:GetObject` on `bucket/inbound/*`, and `ses:SendRawEmail` on the verified sending identity. SES's write permission does not grant the worker read access.

Set `PROVIDER=amazon-ses`. Use the received address for `MAILBOX` and `REPLY_TO`; use a verified identity for `REPLY_FROM`. Configure DKIM for that sender. In the SES sandbox, the test recipient must also be verified; request [production sending access](https://docs.aws.amazon.com/ses/latest/dg/request-production-access.html) before public support. Send a pilot message and check that a new S3 object appears before testing Voiceflow.

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

The worker lists the configured prefix, reads new MIME objects after the cutoff and deduplicates both object keys and Internet Message-IDs. Sender/mailbox-scoped references select Voiceflow sessions. It replies using SES `SendRawEmail` with the original subject and reply headers; SES can replace the outgoing Message-ID. Customer replies must target the receiving address, so `REPLY_TO` stays on the SES receiving domain.

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

If no S3 object appears, check receiving region, MX, active rule set, recipient match and SES PutObject permission. If the object exists but the queue is empty, check the worker IAM role, prefix and cutoff. Optional SES client-side message encryption is outside this reader; do not bypass encryption by exposing the bucket.

### 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 production sending access, DKIM, sending quotas and bounce/complaint monitoring independently from receipt-rule activation. Drain the pilot prefix before changing the live recipient rule. Keep the S3 lifecycle long enough to investigate failed jobs.

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