Implementation guide
Attach email replies to the right application object
Let a customer reply to an order notification. Preserve the order context, receive attachments, and store one pending reply for each inbound message.
The notification already knows which order it belongs to.
Your application sends an update about order_82921. The customer hits Reply and attaches
a delivery note. You want that message alongside the order, without asking them to sign in, find the
order, and paste the same answer into a form.
The missing piece is a durable mapping from the reply address to the application object. A subject such as “Re: Your order” cannot identify the object reliably. A single support mailbox also needs additional routing logic.
In this example, your backend creates an opaque Linje reply address carrying
{"order-id":"order_82921"}. Your existing sender uses it as Reply-To.
When the customer replies, the webhook includes the original metadata.
- Order notification
- Opaque Reply-To
- Customer reply
- Pending order reply
The order and customer are illustrative. The downloadable example seeds one demonstration order; it does not connect to your order system or send any live email by itself.
Use the same verified receiver.
Start with the Node.js email-to-webhook guide and its complete source download. It provides a local simulator, raw-body HMAC verification, SQLite storage, and an attachment downloader.
For a real reply, complete that guide's inbox setup first. You need a Linje project token, an
active inbox in that project, and its generated ID in the receiver's .env. Keep the
receiver running behind your public HTTPS webhook. This article starts at that point.
The local simulator already includes route.metadata.order-id, so you can also inspect
the object mapping without creating a route or sending email:
node --env-file=.env simulate.mjs
node inspect.mjs
One invocation simulates repeated delivery of a single reply. It produces one pending reply row, not three. Real route creation is the next step.
Create one reply address for the object.
Generate a random UUIDv4 once for this logical route. Keep that key and the exact request if you need to retry; a new key creates a different route. Substitute your actual inbox ID:
umask 077
export LINJE_PROJECT_TOKEN='your-project-token'
export ROUTE_KEY="$(node -e 'console.log(require("node:crypto").randomUUID())')"
curl -fsS https://api.linje.systems/v1/reply-routes \
-H "Authorization: Bearer $LINJE_PROJECT_TOKEN" \
-H "Idempotency-Key: $ROUTE_KEY" \
-H 'Content-Type: application/json' \
--data-binary '{
"inbox-id": "the-returned-inbox-id",
"metadata": {"order-id": "order_82921"}
}' > route.json
node -e '
const route = JSON.parse(require("node:fs").readFileSync("route.json"))["reply-route"];
console.log("Route ID:", route.id);
console.log("Reply address:", route.address);
'
The response contains reply-route.id and reply-route.address. The opaque
address contains no readable order ID. Persist the route ID, returned address, and retry key in your
application's order context before sending the notification.
The raw address is returned on creation and exact idempotent retries while the route exists. List and detail responses omit it. Retrying the same key with different metadata returns 409. Metadata is immutable for that route, so later replies keep their original meaning.
In a real application, create routes only after authenticating and authorizing the user or job that owns the object. Keep metadata minimal; it will appear in your webhook payloads and storage.
Set Reply-To in the sender you already use.
Leave your existing SMTP or transactional email provider in place. Its outbound message needs
the generated address in the standard Reply-To header. The provider-specific SDK field
may be named differently; the resulting email headers should look like this:
From: orders@your-verified-domain.example
To: customer@example.net
Reply-To: r+<opaque-token>@in.linje.systems
Subject: Your order update
Please reply with the delivery note for your order.
Copy the exact address from your route response; do not construct it from the order ID. The customer replies normally. A new email sent directly to the same route address also carries the object context, even without a matching email thread header.
If you already send with Linje, its message API takes reply-to as an array. In your
own outbound integration, the request fields would be:
{
"idempotency-key": "order-82921-delivery-note-request",
"from": "orders@your-verified-domain.example",
"to": ["customer@example.net"],
"reply-to": ["the-exact-address-from-your-route-response"],
"subject": "Your order update",
"text": "Please reply with the delivery note for your order."
}
These are illustrative addresses. For a real send, use a verified sender domain and a recipient you control. Reply-route creation and outbound sending are separate retryable operations. Preserve the route result before sending, and use your sender's idempotency mechanism for the notification.
Read the route metadata from the verified event.
The receiver sees the normal inbound envelope plus route. Here is the relevant part
of an illustrative payload:
{
"schema": "linje.inbound-email.v1",
"event-id": "event-identifier",
"inbound-id": "inbound-identifier",
"inbox-id": "your-inbox-id",
"route": {
"id": "route_identifier",
"metadata": {"order-id": "order_82921"}
},
"content": {"text": "Here is the delivery note."},
"attachments": []
}
In the complete receiver, the transaction looks up the order and inserts the pending reply alongside the event:
export function saveEvent(db, event) {
db.exec("BEGIN IMMEDIATE");
try {
// A timeout after COMMIT may cause another delivery. The durable key survives restarts.
const result = db.prepare(`
INSERT INTO inbound_events (inbound_id, event_id, received_at, payload)
VALUES (?, ?, ?, ?) ON CONFLICT(inbound_id) DO NOTHING
`).run(event["inbound-id"], event["event-id"], Date.now(), JSON.stringify(event));
if (result.changes === 0) {
db.exec("COMMIT");
return "duplicate";
}
const orderId = event.route?.metadata?.["order-id"];
if (typeof orderId === "string" && db.prepare("SELECT id FROM orders WHERE id = ?").get(orderId)) {
// Correlation identifies the object. The email remains untrusted input for review.
db.prepare("INSERT INTO order_replies (inbound_id, order_id, text) VALUES (?, ?, ?)")
.run(event["inbound-id"], orderId, typeof event.content?.text === "string" ? event.content.text : "");
}
db.exec("COMMIT");
return "stored";
} catch (error) {
db.exec("ROLLBACK");
throw error;
}
}
The demo seeds only order_82921. If the object is unknown, or there is no route,
the email stays in inbound_events and inspection shows it as unmatched. It does not
invent a new order. Replace that lookup with your own project-scoped object lookup and a review
path for deleted, closed, or inaccessible objects.
Use route.metadata for this association. Linje can also provide a separate
correlation object when thread headers match a Linje-sent message. That optional
header-based match is independent of the reply route and is not required when you keep another
outbound provider.
A reply identifies context; your app decides what to do.
A delivery note is evidence for a person or workflow to review. Receiving it should not silently
approve a claim, cancel an order, or change a delivery address. The example stores the reply as
pending_review and never changes order state.
The webhook signature authenticates the Linje delivery. It does not authenticate the person who sent the email. A route address can be forwarded, and an email's From address can be spoofed. Apply your application's identity and authorization rules before sensitive actions.
Treat text, HTML, subjects, and attachments as untrusted input. The example stores plain text
without rendering it; it does not strip quoted history or signatures. Escape content when displaying
it. Download files with download.mjs from the first guide and apply your own file policy.
Test the reply flow while the route is active.
Send one real notification to yourself with the generated Reply-To address. Reply with a small
attachment, and verify the inbound ID, order mapping, and one new pending row using
node inspect.mjs. Download the attachment with download.mjs and compare
its bytes with the file you sent.
Replay that inbound message using the first guide: the row count should stay unchanged. Then send a second reply and confirm that it creates a second new row on the same order. If you ran the local simulator earlier, its synthetic rows will also be present; identify the real replies by their inbound IDs.
Keep the route active until these checks are complete. The next section disables it.
Close the reply route deliberately.
Choose whether a route belongs to the whole order, one conversation, or one document request.
An order may stay replyable for months; a completed document request may need to stop accepting
answers earlier. Linje supports disabling the route or setting expires-at-ms.
export ROUTE_ID='the-returned-route-id'
curl -fsS -X PATCH \
"https://api.linje.systems/v1/reply-routes/$ROUTE_ID" \
-H "Authorization: Bearer $LINJE_PROJECT_TOKEN" \
-H 'Content-Type: application/json' \
--data-binary '{"active":false}'
A disabled, expired, or unknown address does not deliver a correlated reply to your inbox webhook. Disabling does not withdraw emails already sent or erase replies already received. Plan how your application handles a late answer before choosing an expiry policy.
Add this to one existing notification.
Pick a notification that already invites a useful response. Keep your sender, create a route, and verify one real reply against the correct object before extending the pattern.
Create a Linje project Build the receiver first
Reference: reply-route API · inbound email API · public OpenAPI contract.