Reply Threading

Overview

When you enable reply threading on a sending domain (e.g. support.foo.com), every outbound message can opt in to a signed reply-to address of the form <token>@r.mail.support.foo.com. When the recipient hits reply, their client addresses that token. Wraps' inbound Lambda verifies the HMAC and surfaces a replyToken object on the email.received event so you can thread replies into the right conversation without a database lookup.

Trust Model

Enable Per Domain

Reply threading is enabled per sending domain. Inbound receiving must already be set up for the same domain first.

One domain

npx @wraps.dev/cli email reply init --domain support.foo.com

If inbound is not yet enabled for support.foo.com, run wraps email inbound add support.foo.com first.

npx @wraps.dev/cli email inbound add support.foo.com

Every inbound domain

Enable reply threading on every currently-enabled inbound domain in one command:

npx @wraps.dev/cli email reply init --all

Signing From the SDK

Once reply threading is enabled for a domain, opt in per-send by passing a conversationId. The SDK pulls the signing secret from SSM, generates the signed reply-to address, and sets ReplyToAddresses for you.

import { WrapsEmail } from "@wraps.dev/email";const email = new WrapsEmail({  region: "us-east-1",  replyThreading: {}, // auto-reads /wraps/email/reply-secret/{domain}});const conversationId = email.replyThreading.newConversation();await email.send({  from: "agent@support.foo.com",  to: "user@example.com",  subject: "Your ticket",  html: "<p>...</p>",  conversationId, // opt-in: this turns on signing});// Later, any reply to that message arrives with//   replyToken: { conversationId, sendId, status: "valid" }

Generate a new conversationId at the start of each conversation and reuse it on every outbound message in that thread. The SDK derives the sending domain from params.from, so one WrapsEmail instance handles any number of enabled domains.

Event Shape

Inbound replies arrive on the standard email.received EventBridge event with two new fields:

{  "emailId": "inb_abc123",  "replyToken": {    "conversationId": "aGVsbG8gd29y",    "sendId": "MDEyMzQ1Njc",    "status": "valid"  },  "autoReply": false}

Status Values

replyToken.status is a discriminated union. Pattern-match on it explicitly — do not treat "present" as "trusted".

Filter Pattern

The single check you almost always want:

if (event.detail.replyToken?.status === "valid") {  // safe to trust conversationId for threading  await threadIntoConversation(event.detail.replyToken.conversationId);}

Any other value — including a non-null replyToken with a non-valid status — should be treated as an unverified reply and fall back to whatever logic you use for plain inbound mail.

Auto-Reply Detection

Every inbound event includes an autoReply boolean. Lambda flags it truewhen the message looks like a vacation responder or bulk mailer — specifically, if any of these headers are present:

• Auto-Submitted: auto-replied
• Precedence: bulk
• X-Autoreply

Use this to avoid response loops:

if (event.detail.autoReply) {  // vacation responder, bulk mailer, or other auto-reply  // skip triggering any response to avoid loops  return;}

Rotation

Rotate the signing secret for a domain at any time:

npx @wraps.dev/cli email reply rotate --domain support.foo.com

Debugging

Decode a reply-to address locally without touching AWS. Useful when support receives a screenshot and needs to identify the conversation:

npx @wraps.dev/cli email reply decode <token>@r.mail.support.foo.com

Prints the decoded version, kid, conversationId, sendId, exp, HMAC (hex), and the sending domain. The HMAC is not verified— decode is a pure format-level operation.

Status

Audit every enabled domain in one command. Verifies the SSM parameter exists, the r.mail.{domain} recipient is present in the catch-all receipt rule, and the MX record resolves.

npx @wraps.dev/cli email reply status

Longer-Lived Tokens

Signed reply-to addresses expire 90 days after they are generated by default. Tokens that arrive after their exp return status: "expired". Override per-send if your workflow needs a longer window:

// Default: 90-day TTL on every signed reply-to addressawait email.send({ from, to, subject, html, conversationId });// Opt-in: custom TTL (in seconds)await email.send({  from,  to,  subject,  html,  conversationId,  replyTtlSeconds: 60 * 60 * 24 * 365, // 1 year});// Opt-in: never expires (use with caution)await email.send({  from,  to,  subject,  html,  conversationId,  replyTtlSeconds: 0,});

Security

Replay Defense (Optional)

Wraps does not provide built-in replay protection. A captured valid token can be resent until its exp or the secret rotates. If your workflow needs at-most-once semantics, pair sendId with a DynamoDB TTL idempotency table in your own application:

// Application-layer replay defense (optional, not provided by Wraps)import {  DynamoDBClient,  PutItemCommand,} from "@aws-sdk/client-dynamodb";const ddb = new DynamoDBClient({});async function handleReply(event) {  const { replyToken } = event.detail;  if (replyToken?.status !== "valid") return;  // Reject if we've already processed this sendId  try {    await ddb.send(      new PutItemCommand({        TableName: "reply-sendids",        Item: {          sendId: { S: replyToken.sendId },          ttl: { N: String(Math.floor(Date.now() / 1000) + 90 * 86_400) },        },        ConditionExpression: "attribute_not_exists(sendId)",      })    );  } catch (err) {    if (err.name === "ConditionalCheckFailedException") {      // replayed sendId — drop      return;    }    throw err;  }  await threadIntoConversation(replyToken.conversationId);}

This is application-layer, not Wraps-provided. Dedupe on sendId, not conversationId — you want many replies per conversation but each specific outbound message replied to at most once.

Next Steps