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

> Receive Postmark inbound email on your HTTPS relay, run Voiceflow and send text replies through a separate outbound transactional stream.

## Overview

Receive messages at a Postmark inbound address, queue them on your HTTPS relay, then run Voiceflow and send a Postmark text reply. This walkthrough uses an Inbound Message Stream and a separate outbound transactional stream.

**Note:** 

**Using your own domain?** Postmark’s [inbound forwarding domain](https://postmarkapp.com/developer/user-guide/inbound/configure-an-inbound-server) is another receiving configuration. This walkthrough starts with the server’s generated inbound address; an outbound Server API token alone does not receive 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. |
| Postmark server | An Inbound Message Stream with its generated receiving address and configuration access. |
| Outbound identity | A verified sender/domain and an outbound transactional stream. |
| Credentials | Server API token for sending; an independently generated HTTP Basic password for your inbound endpoint. |

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. Choose the receiving stream

In your Postmark server, open the **Inbound Message Stream → Settings** and copy its generated inbound email address. Set `PROVIDER=postmark`, `MAILBOX` and `REPLY_TO` to that address. For the first test, send directly to it; forwarding rules from an existing help address need an additional test of the forwarded recipient and headers.

Set `REPLY_FROM` to a verified sending address, `POSTMARK_SERVER_TOKEN` to this server's token, and use the server's `outbound` transactional Message Stream for this example. Verify the sender/domain and its DKIM records before testing recipient delivery.

### 2. Save an authenticated inbound URL

Generate `WEBHOOK_PASSWORD` with `openssl rand -hex 32`, and set `WEBHOOK_USER=relay`. In the Inbound stream's settings, save the webhook URL:

```text
https://relay:YOUR_WEBHOOK_PASSWORD@YOUR_RELAY_HOST/inbound
```

Replace the placeholders with your real host/password; keep this URL private. Postmark supports [HTTP Basic authentication](https://postmarkapp.com/developer/webhooks/webhooks-overview) on HTTPS webhook URLs. The relay checks the Authorization header independently of the outbound Server token. Make sure the reverse proxy preserves it.

### 3. Check original message identity

The [inbound webhook](https://postmarkapp.com/developer/webhooks/inbound-webhook) sends JSON with `MessageID`, `OriginalRecipient`, body fields, headers and attachment metadata/content. The adapter uses the event ID for delivery deduplication and the original Internet `Message-ID` in `Headers` for email threading. Missing original identity is held rather than replaced with the Postmark UUID.

Start the host below. Use Postmark’s webhook test to check transport, then send real pilot mail: a synthetic webhook test does not prove receiving DNS or customer delivery.

<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 adapter uses `OriginalRecipient` for routing and `StrippedTextReply` when available, otherwise `TextBody`. Postmark’s [reply extraction](https://postmarkapp.com/developer/user-guide/inbound/parse-an-email) is best effort and limited to supported plain-text replies; HTML-only and attachments stay in review. Sender-scoped Internet references select the session. `/email` sends through the outbound stream with the receiving address in ReplyTo and the thread headers in Headers.

| 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 saved Inbound stream URL, Basic password, OriginalRecipient and proxy Authorization header. Postmark retries failed inbound POSTs and stops on 403; inspect Inbound Error and use its retry action after fixing configuration. Do not use a deliberately invalid URL to pause support without a replacement receiving route.

### 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 sender approval, the transactional stream and the real receiving address. Monitor Inbound Errors and outbound bounces; a successful API message ID establishes acceptance only. Rotate the server token separately from the webhook password and repeat the customer test.

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