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

> Receive email at a Mailjet Parse address, run Voiceflow through your hosted relay and send text replies with a verified Mailjet sender.

## Overview

Create a Mailjet Parse address, send its incoming JSON to your relay and deliver Voiceflow text replies through Send API v3.1. This walkthrough uses the generated Parse address and a separately verified sender.

**Note:** 

**Availability.** Mailjet documents [Parse API access for Premium 50k and above](https://dev.mailjet.com/docs/email-api/parse-api/basic-setup). Confirm your plan before starting. A sending account alone does not establish inbound Parse access. A [custom receiving domain](https://dev.mailjet.com/docs/email-api/parse-api/use-own-domain) is an alternative configuration; the steps below use the generated address.

<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. |
| Mailjet account | Parse API access on the required plan, plus its public API key and private secret key. |
| Sending identity | A verified sender/domain with its authentication records. |
| HTTPS receiver | Your relay host and a separate HTTP Basic username/password. |

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 sending and endpoint credentials

Verify a sending domain/address in Mailjet and configure its sender authentication. Set `PROVIDER=mailjet`, `REPLY_FROM` to that sender, and `MAILJET_API_KEY`/`MAILJET_SECRET_KEY` to its account credentials. The API key pair authenticates API calls, not incoming webhooks.

Set `RELAY_ORIGIN` to your HTTPS host, `WEBHOOK_USER=relay` and `WEBHOOK_PASSWORD` to a value generated by `openssl rand -hex 32`. The helper registers the HTTPS webhook with these Basic credentials in its URL. Keep the resulting provider configuration private and preserve Authorization through the proxy.

### 2. Create the Parse address

Run once:

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

The helper calls `POST https://api.mailjet.com/v3/REST/parseroute` with the authenticated `/inbound` URL. Save the returned route ID and `Email` address. Set `MAILBOX` and `REPLY_TO` to that generated address, such as the address under `parse-in1.mailjet.com` returned by your account. Do not copy another account's example address.

Mailjet provides one generated Parse address per API key. If one already exists, inspect/update that route rather than repeatedly creating routes. The URL must have a path; the supplied `/inbound` satisfies that requirement.

### 3. Check the receiving payload

The [Parse payload](https://dev.mailjet.com/docs/email-api/parse-api/delivered-to-webhook) is JSON containing `Recipient`, `From`, `Headers`, `Text-part`, `Html-part` and Parts. Headers may be strings or arrays. The adapter normalizes them, accepts the exact generated recipient and holds files/HTML-only messages. Start the host below; send directly to the generated address and check its queue entry before introducing forwarding rules.

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

Internet Message-ID and references join only the same mailbox/sender scope; subject alone does not join mail. The adapter calls [Send API v3.1](https://dev.mailjet.com/docs/email-api/send-api-v31/send-v3-1-overview) with From, one To recipient, ReplyTo set to the Parse address, TextPart and thread Headers. Mailjet [forbids a custom Message-ID](https://dev.mailjet.com/docs/email-api/send-api-v31/add-email-headers), so the adapter omits that header and relies on the original reference chain. A client that removes older References may start a new session. It checks each message’s success status as well as HTTP status. Recipient delivery remains a separate check.

| 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 plan access, the parseroute ID/address, non-root webhook URL and HTTP Basic password. Check that `Recipient` matches the configured mailbox and that the proxy keeps Authorization. A successful Send API call cannot prove that the Parse route is active.

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

Confirm the required plan remains active, sender verification and the generated address used by ReplyTo. Monitor Parse failures and Send API per-message errors/bounces. Rotate API credentials separately from the webhook password and repeat the real receiving/reply 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.
