feat(email): expose durable webhook deliveries (DLQ + redrive) + list direction filter

Surfaces for the run402 durable mailbox-webhook delivery change. Webhook
delivery is now at-least-once with a dead-letter queue; consumers dedupe on the
canonical envelope's idempotency_key (also the Run402-Webhook-Id header).

- SDK: email.webhooks.listDeliveries / redriveDelivery; direction filter on
  email.list (EmailSummary now carries direction). scoped.ts mirrors both.
- CLI: run402 email webhooks deliveries [--status] / redrive <id>;
  run402 email list --direction <inbound|outbound>.
- MCP: new list_mailbox_webhook_deliveries + redrive_mailbox_webhook_delivery
  tools; direction on list_emails. Registered in src/index.ts; sync.test SURFACE
  + SDK_BY_CAPABILITY updated.
- Docs: llms-mcp.txt, sdk/llms-sdk.txt, cli/llms-cli.txt, SKILL.md,
  openclaw/SKILL.md document the at-least-once + idempotency contract, the
  canonical envelope, the deliveries/redrive surface, and the inbound
  reconciliation backstop.

Pairs with run402 commit (gateway + Lambdas). Lockstep publish pending.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: volinskey

SKILL.md

@@ -509,6 +509,7 @@ Function authoring limits per tier: prototype 10s / 128 MB / 1 scheduled fn / 15
 - **`send_email`** — template (`project_invite`, `magic_link`, `notification`) or raw HTML. Single recipient. Optional `mailbox` selector.
 - **`list_emails`** / **`get_email`** / **`get_email_raw`** — read messages. `get_email_raw` returns RFC-822 bytes for DKIM / zk-email verification.
 - **`register_mailbox_webhook`** / **`list_mailbox_webhooks`** / **`get_mailbox_webhook`** / **`update_mailbox_webhook`** / **`delete_mailbox_webhook`** — email-event webhooks (delivery, bounced, complained, reply_received).
+- **`list_mailbox_webhook_deliveries`** / **`redrive_mailbox_webhook_delivery`** — durable-delivery visibility + replay. Delivery is at-least-once (bounded retries + exponential backoff); failures land in `failed_permanent`, the dead-letter queue. The delivered body is the canonical envelope `{ id, type, created_at, schema_version, idempotency_key, payload }` — consumers MUST dedupe on `idempotency_key`. `list_emails` accepts an optional `direction` (`inbound`|`outbound`); `inbound` lists received replies as the reconciliation backstop if a `reply_received` webhook is lost.
 - **`register_sender_domain`** / **`sender_domain_status`** / **`remove_sender_domain`** — send from your own domain (DKIM verified).
 - **`enable_sender_domain_inbound`** / **`disable_sender_domain_inbound`** — receive replies on your custom sender domain.
 

cli-argv.test.mjs

@@ -291,6 +291,32 @@ describe("email webhooks argv validation", () => {
     assert.equal(err.details.flag, "--url");
     assert.equal(calls.length, 0, "invalid argv must not hit the network");
   });
+
+  it("webhooks redrive rejects missing delivery_id before network", async () => {
+    const { run } = await import("./cli/lib/webhooks.mjs");
+    const err = await expectExit1(() => run("redrive", ["--project", "prj_test123"]));
+
+    assert.equal(err.code, "BAD_USAGE");
+    assert.equal(calls.length, 0, "invalid argv must not hit the network");
+  });
+
+  it("webhooks deliveries rejects unknown flag before network", async () => {
+    const { run } = await import("./cli/lib/webhooks.mjs");
+    const err = await expectExit1(() => run("deliveries", ["--statuz", "pending"]));
+
+    assert.equal(err.code, "UNKNOWN_FLAG");
+    assert.equal(err.details.flag, "--statuz");
+    assert.equal(calls.length, 0, "invalid argv must not hit the network");
+  });
+
+  it("webhooks deliveries rejects missing --status value before network", async () => {
+    const { run } = await import("./cli/lib/webhooks.mjs");
+    const err = await expectExit1(() => run("deliveries", ["--status"]));
+
+    assert.equal(err.code, "BAD_FLAG");
+    assert.equal(err.details.flag, "--status");
+    assert.equal(calls.length, 0, "invalid argv must not hit the network");
+  });
 });
 
 describe("ai argv validation (GH-280)", () => {

cli/lib/email.mjs

@@ -13,8 +13,10 @@ Subcommands:
   info   [--project <id>]            Show mailbox info (ID, address, slug)
   status [--project <id>]            Alias for 'info' (prefer 'info')
   send   --to <email> [mode flags]   Send an email (template or raw HTML)
-  list   [--limit <n>] [--after <cursor>] [--project <id>]
-                                      List sent/received messages (paginated)
+  list   [--limit <n>] [--after <cursor>] [--direction <inbound|outbound>] [--project <id>]
+                                      List messages (paginated). Returns BOTH
+                                      sent + received by default; --direction
+                                      inbound is the reconciliation backstop.
   get    <message_id> [--project <id>]  Get a message with replies
   get-raw <message_id> --output <file> [--project <id>]
                                       Fetch raw RFC-822 bytes (inbound only).
@@ -35,6 +37,10 @@ Webhook subcommands:
                                                   Update a webhook
   webhooks register --url <url> --events <e1,e2> [--project <id>]
                                                   Register a new webhook
+  webhooks deliveries [--status <s>] [--project <id>]
+                                                  List durable delivery rows (DLQ visibility)
+  webhooks redrive <delivery_id> [--project <id>]
+                                                  Re-queue a dead-lettered delivery
 
 Send modes:
   Template:  --template <name> --var key=value [--var ...]  OR --vars '{"k":"v",...}'
@@ -286,16 +292,18 @@ async function send(args) {
 }
 
 async function list(args) {
-  const valueFlags = ["--project", "--limit", "--after", "--mailbox"];
+  const valueFlags = ["--project", "--limit", "--after", "--mailbox", "--direction"];
   validateArgs(args, valueFlags);
   const projectId = resolveProjectId(strictFlagValue(args, "--project"));
   const limit = strictFlagValue(args, "--limit");
   const after = strictFlagValue(args, "--after");
   const mailbox = strictFlagValue(args, "--mailbox");
+  const direction = strictFlagValue(args, "--direction");
   try {
     const data = await getSdk().email.list(projectId, {
       limit: limit ? parseIntegerFlag("--limit", limit) : undefined,
       after: after ?? undefined,
+      direction: direction ?? undefined,
       mailbox: mailbox ?? undefined,
     });
     console.log(JSON.stringify(data, null, 2));

cli/lib/webhooks.mjs

@@ -9,13 +9,22 @@ Usage:
   run402 email webhooks <action> [args...]
 
 Actions:
-  list     [--mailbox <slug|id>] [--project <id>]            List webhooks
-  get      <webhook_id> [--mailbox <slug|id>] [--project <id>]   Get a webhook
-  delete   <webhook_id> [--mailbox <slug|id>] [--project <id>]   Delete a webhook
-  update   <webhook_id> [--url <url>] [--events <e1,e2>] [--mailbox <slug|id>]  Update a webhook
-  register --url <url> --events <e1,e2> [--mailbox <slug|id>] [--project <id>]  Register a new webhook
+  list       [--mailbox <slug|id>] [--project <id>]            List webhooks
+  get        <webhook_id> [--mailbox <slug|id>] [--project <id>]   Get a webhook
+  delete     <webhook_id> [--mailbox <slug|id>] [--project <id>]   Delete a webhook
+  update     <webhook_id> [--url <url>] [--events <e1,e2>] [--mailbox <slug|id>]  Update a webhook
+  register   --url <url> --events <e1,e2> [--mailbox <slug|id>] [--project <id>]  Register a new webhook
+  deliveries [--status <s>] [--mailbox <slug|id>] [--project <id>]  List durable delivery rows (DLQ visibility)
+  redrive    <delivery_id> [--mailbox <slug|id>] [--project <id>]   Re-queue a dead-lettered delivery
 
 Valid events: delivery, bounced, complained, reply_received
+Delivery statuses: pending, in_flight, delivered, failed_permanent (the DLQ)
+
+Webhook delivery is durable + at-least-once: failures retry with backoff, then
+land in failed_permanent (the dead-letter queue). The delivered body is the
+canonical envelope { id, type, created_at, schema_version, idempotency_key,
+payload } — consumers MUST dedupe on idempotency_key. Use 'deliveries' to
+inspect what was lost and 'redrive' to replay a dead-lettered delivery.
 
 Pass --mailbox <slug|id> to target a specific mailbox when the project has more than one.
 
@@ -24,6 +33,8 @@ Examples:
   run402 email webhooks register --url https://example.com/hook --events delivery,bounced
   run402 email webhooks update whk_123 --url https://new.example.com/hook
   run402 email webhooks delete whk_123
+  run402 email webhooks deliveries --status failed_permanent
+  run402 email webhooks redrive wd_123
 `;
 
 const SUB_HELP = {
@@ -196,16 +207,60 @@ async function register(args) {
   }
 }
 
+async function deliveries(args) {
+  const valueFlags = ["--project", "--mailbox", "--status", "--limit", "--after"];
+  validateArgs(args, valueFlags);
+  const projectId = resolveProjectId(strictFlagValue(args, "--project"));
+  const mailbox = strictFlagValue(args, "--mailbox");
+  const status = strictFlagValue(args, "--status");
+  const limitRaw = strictFlagValue(args, "--limit");
+  const after = strictFlagValue(args, "--after");
+  try {
+    const data = await getSdk().email.webhooks.listDeliveries(projectId, {
+      status: status ?? undefined,
+      limit: limitRaw ? Number(limitRaw) : undefined,
+      after: after ?? undefined,
+      mailbox: mailbox ?? undefined,
+    });
+    console.log(JSON.stringify(data, null, 2));
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+async function redrive(args) {
+  const valueFlags = ["--project", "--mailbox"];
+  validateArgs(args, valueFlags);
+  const deliveryId = positionalArgs(args, valueFlags)[0] ?? null;
+  const projectId = resolveProjectId(strictFlagValue(args, "--project"));
+  const mailbox = strictFlagValue(args, "--mailbox");
+  if (!deliveryId) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing delivery_id.",
+      hint: "run402 email webhooks redrive <delivery_id>",
+    });
+  }
+  try {
+    const data = await getSdk().email.webhooks.redriveDelivery(projectId, deliveryId, { mailbox: mailbox ?? undefined });
+    console.log(JSON.stringify(data, null, 2));
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
 export async function run(sub, args) {
   args = normalizeArgv(args);
   if (!sub || sub === '--help' || sub === '-h') { console.log(HELP); process.exit(0); }
   if (Array.isArray(args) && (args.includes("--help") || args.includes("-h"))) { console.log(SUB_HELP[sub] || HELP); process.exit(0); }
   switch (sub) {
-    case "list":     await list(args); break;
-    case "get":      await get(args); break;
-    case "delete":   await del(args); break;
-    case "update":   await update(args); break;
-    case "register": await register(args); break;
+    case "list":       await list(args); break;
+    case "get":        await get(args); break;
+    case "delete":     await del(args); break;
+    case "update":     await update(args); break;
+    case "register":   await register(args); break;
+    case "deliveries": await deliveries(args); break;
+    case "redrive":    await redrive(args); break;
     default:
       console.error(`Unknown webhooks action: ${sub}\n`);
       console.log(HELP);

cli/llms-cli.txt

@@ -1226,7 +1226,7 @@ Templates: `project_invite` (project_name, invite_url), `magic_link` (project_na
 - `run402 email status [--mailbox <slug|id>] [--project <id>]` — show mailbox info (ID, address, slug)
 - `run402 email send --template <name> --to <email> [--var key=value ...] [--from-name <name>] [--mailbox <slug|id>] [--project <id>]`
 - `run402 email send --to <email> --subject <subject> --html <html> [--text <text>] [--from-name <name>] [--mailbox <slug|id>] [--project <id>]`
-- `run402 email list [--mailbox <slug|id>] [--project <id>]`
+- `run402 email list [--direction <inbound|outbound>] [--mailbox <slug|id>] [--project <id>]` — lists BOTH sent + received by default; `--direction inbound` lists received replies (the reconciliation backstop if a reply_received webhook is lost)
 - `run402 email get <message_id> [--mailbox <slug|id>] [--project <id>]`
 - `run402 email reply <message_id> --html <html> [--text <text>] [--subject <subject>] [--from-name <name>] [--mailbox <slug|id>] [--project <id>]` — reply to an inbound message (threads via In-Reply-To)
 - `run402 email get-raw <message_id> --output <file> [--mailbox <slug|id>] [--project <id>]` — fetch raw RFC-822 bytes of an inbound message (for DKIM/zk-email verification). `--output` is required: bytes are written to the file; stdout receives a JSON envelope `{ message_id, bytes, output }` so the CLI stays pipeable. Inbound only; outbound returns 404.
@@ -1236,6 +1236,8 @@ Templates: `project_invite` (project_name, invite_url), `magic_link` (project_na
 - `run402 email webhooks delete <webhook_id> [--mailbox <slug|id>] [--project <id>]` — delete a webhook
 - `run402 email webhooks update <webhook_id> [--url <url>] [--events <e1,e2>] [--mailbox <slug|id>] [--project <id>]` — update webhook URL and/or events
 - `run402 email webhooks register --url <url> --events <e1,e2> [--mailbox <slug|id>] [--project <id>]` — register a new webhook. Valid events: delivery, bounced, complained, reply_received
+- `run402 email webhooks deliveries [--status <pending|in_flight|delivered|failed_permanent>] [--mailbox <slug|id>] [--project <id>]` — list durable delivery rows. Delivery is at-least-once with bounded retries + backoff; `failed_permanent` is the dead-letter queue. The delivered body is the canonical envelope `{ id, type, created_at, schema_version, idempotency_key, payload }` — consumers MUST dedupe on `idempotency_key`.
+- `run402 email webhooks redrive <delivery_id> [--mailbox <slug|id>] [--project <id>]` — re-queue a dead-lettered (failed_permanent) delivery for another attempt
 
 Raw HTML: `--subject` (max 998 chars) + `--html` (max 1MB). Plaintext auto-generated from HTML if `--text` omitted. `--from-name` sets display name on From header (both modes): `"My App" <slug@mail.run402.com>`.
 

llms-mcp.txt

@@ -391,6 +391,8 @@ Fixed platform-managed jobs. These tools do not run arbitrary Docker images; the
 - `list_emails` / `get_email` — read messages. Both take an optional `mailbox`.
 - `get_email_raw` — return raw RFC-822 bytes for DKIM / zk-email verification (inbound only). Params: `project_id`, `message_id`, `mailbox?`.
 - `register_mailbox_webhook` / `list_mailbox_webhooks` / `get_mailbox_webhook` / `update_mailbox_webhook` / `delete_mailbox_webhook` — email-event webhooks (events: `delivery`, `bounced`, `complained`, `reply_received`). Each takes an optional `mailbox`.
+- `list_mailbox_webhook_deliveries` / `redrive_mailbox_webhook_delivery` — durable-delivery visibility + replay. Webhook delivery is **at-least-once** with bounded retries + exponential backoff; failures that exhaust the budget (or fail permanently) land in `failed_permanent` — the dead-letter queue. `list_mailbox_webhook_deliveries` (optional `status` filter) inspects pending/delivered/dead-lettered rows; `redrive_mailbox_webhook_delivery` re-queues a dead-lettered delivery after you fix the consumer. The delivered body is the canonical envelope `{ id, type, created_at, schema_version, idempotency_key, payload }` — **consumers MUST dedupe on `idempotency_key`** (also sent as the `Run402-Webhook-Id` header). Mailbox webhooks are unsigned.
+- `list_emails` also takes an optional `direction` (`inbound` | `outbound`); omit for both. `direction: inbound` lists received replies — the reconciliation backstop if a `reply_received` webhook is ever lost.
 - `register_sender_domain` / `sender_domain_status` / `remove_sender_domain` — send from your own DKIM-verified domain.
 - `enable_sender_domain_inbound` / `disable_sender_domain_inbound` — receive replies on your custom sender domain. Returns the MX record to add.
 

openclaw/SKILL.md

@@ -734,6 +734,16 @@ run402 email webhooks register --url https://… --events delivery,bounced,reply
 run402 email webhooks list
 run402 email webhooks update <id> --events delivery,bounced,complained,reply_received
 run402 email webhooks delete <id>
+
+# Durable delivery is at-least-once (bounded retries + exponential backoff);
+# failures land in failed_permanent — the dead-letter queue. The delivered body
+# is the canonical envelope { id, type, created_at, schema_version,
+# idempotency_key, payload } — dedupe on idempotency_key.
+run402 email webhooks deliveries --status failed_permanent   # inspect the DLQ
+run402 email webhooks redrive <delivery_id>                  # replay a dead-lettered delivery
+
+# Reconciliation backstop if a reply_received webhook is ever lost:
+run402 email list --direction inbound
 ```
 
 ### Custom sender domain

sdk/llms-sdk.txt

@@ -987,7 +987,10 @@ getMailbox(projectId): Promise<MailboxInfo>
 deleteMailbox(projectId, mailboxId?): Promise<void>
 
 send(projectId, opts: SendEmailOptions): Promise<SendEmailResult>
-list(projectId, opts?: { limit?, after? }): Promise<EmailSummary[]>
+list(projectId, opts?: { limit?, after?, direction? }): Promise<EmailSummary[]>
+  // direction?: "inbound" | "outbound" — omit for BOTH. direction:"inbound" lists
+  // received replies (each EmailSummary carries `direction`) and is the
+  // reconciliation backstop if a reply_received webhook is ever lost.
 get(projectId, messageId): Promise<EmailDetail>
 getRaw(projectId, messageId): Promise<RawEmailResult> // bytes + content_type
 
@@ -997,6 +1000,16 @@ webhooks.list(projectId): Promise<MailboxWebhooksResult>
 webhooks.get(projectId, webhookId): Promise<MailboxWebhookSummary>
 webhooks.update(projectId, webhookId, opts: { url?, events? }): Promise<MailboxWebhookSummary>
 webhooks.delete(projectId, webhookId): Promise<void>
+webhooks.listDeliveries(projectId, opts?: { status?, limit?, after? }): Promise<WebhookDeliveriesResult>
+  // Durable delivery is AT-LEAST-ONCE with bounded retries + exponential backoff.
+  // Failures that exhaust the budget (or fail permanently) become status
+  // "failed_permanent" — the dead-letter queue. status?: pending | in_flight |
+  // delivered | failed_permanent. The delivered body is the canonical envelope
+  // { id, type, created_at, schema_version, idempotency_key, payload }; consumers
+  // MUST dedupe on idempotency_key (also the Run402-Webhook-Id header). Mailbox
+  // webhooks are unsigned (verifyWebhook is for operator notifications only).
+webhooks.redriveDelivery(projectId, deliveryId): Promise<RedriveDeliveryResult>
+  // Re-queue a dead-lettered delivery for another attempt (after fixing the consumer).
 
 // CLI-style aliases:
 create(projectId, slug): Promise<CreateMailboxResult | MailboxInfo>