mailery 0.17.1 → 0.18.0

package/dist/index.js

@@ -88,6 +88,42 @@ __export(mongo_exports, {
 function canBeObjectId(s) {
   return typeof s === "string" && /^[a-f0-9]{24}$/i.test(s);
 }
+function getPath(doc, path3) {
+  let cur = doc;
+  for (const part of path3.split(".")) {
+    if (cur === null || typeof cur !== "object") return void 0;
+    cur = cur[part];
+  }
+  return cur;
+}
+function isObjectIdLike(v) {
+  return !!v && typeof v === "object" && typeof v.toHexString === "function" && v._bsontype === "ObjectId";
+}
+function packScalar(v) {
+  if (v instanceof Date) return { d: v.toISOString() };
+  if (isObjectIdLike(v)) return { o: v.toHexString() };
+  if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") return v;
+  return null;
+}
+function unpackScalar(v) {
+  if (v && typeof v === "object") {
+    if ("d" in v) return new Date(v.d);
+    if ("o" in v) return new ObjectId(v.o);
+  }
+  return v;
+}
+function encodeSortCursor(value, id) {
+  return Buffer.from(JSON.stringify({ v: packScalar(value), i: packScalar(id) }), "utf8").toString("base64url");
+}
+function decodeSortCursor(cursor) {
+  try {
+    const parsed = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+    if (!parsed || typeof parsed !== "object" || !("v" in parsed) || !("i" in parsed)) return null;
+    return { value: unpackScalar(parsed.v), id: unpackScalar(parsed.i) };
+  } catch {
+    return null;
+  }
+}
 var MongoContactAdapter;
 var init_mongo = __esm({
   "src/server/adapters/mongo.ts"() {
@@ -137,7 +173,10 @@ var init_mongo = __esm({
         }
         return out;
       }
+      /** `query` honours `opts.sort` — see `querySorted`. */
+      supportsSort = true;
       async query(filter, opts) {
+        if (opts.sort) return this.querySorted(filter, opts.limit, opts.cursor, opts.sort);
         const query = this.translateFilterFn(filter);
         const limit = Math.min(opts.limit, this.batchSize);
         if (opts.cursor) {
@@ -156,6 +195,52 @@ var init_mongo = __esm({
         const query = this.translateFilterFn(filter);
         return await this.col.countDocuments(query);
       }
+      /**
+       * Keyset pagination in (sort.field, idField) order. The cursor encodes the
+       * last row's sort value and id, and the next page is every row strictly
+       * after that position. Mongo sorts a null or missing value lowest, so
+       * `desc` puts contacts without the field last and `asc` puts them first;
+       * the position predicate follows the same rule, so they are neither
+       * skipped nor repeated.
+       *
+       * The field should hold one BSON type (or be absent): range operators only
+       * compare within a type. A value that moves while a pass is paging (a
+       * contact whose `updatedAt` changes mid-dispatch) can be seen twice or not
+       * at all in that pass; broadcast dispatch tolerates both (the per-recipient
+       * dedupe key stops a second send, and a later pass picks up a skipped one).
+       * Index `{ <field>: -1, <idField>: 1 }` on a large collection.
+       */
+      async querySorted(filter, limitIn, cursor, sort) {
+        const base = this.translateFilterFn(filter);
+        const limit = Math.min(limitIn, this.batchSize);
+        const dir = sort.direction === "desc" ? -1 : 1;
+        let query = base;
+        if (cursor) {
+          const pos = decodeSortCursor(cursor);
+          if (!pos) throw new Error("MongoContactAdapter: malformed sort cursor");
+          query = { $and: [base, this.afterPosition(sort.field, dir, pos.value, pos.id)] };
+        }
+        const docs = await this.col.find(query).sort({ [sort.field]: dir, [this.idField]: 1 }).limit(limit + 1).toArray();
+        const hasMore = docs.length > limit;
+        const slice = hasMore ? docs.slice(0, limit) : docs;
+        const last = slice[slice.length - 1];
+        return {
+          contacts: slice.map((d) => this.toContactFn(d)),
+          nextCursor: hasMore && last ? encodeSortCursor(getPath(last, sort.field), last[this.idField]) : void 0
+        };
+      }
+      afterPosition(field, dir, value, id) {
+        const idF = this.idField;
+        const isNull = value === null || value === void 0;
+        if (dir === -1) {
+          if (isNull) return { [field]: null, [idF]: { $gt: id } };
+          return {
+            $or: [{ [field]: { $lt: value } }, { [field]: value, [idF]: { $gt: id } }, { [field]: null }]
+          };
+        }
+        if (isNull) return { $or: [{ [field]: null, [idF]: { $gt: id } }, { [field]: { $ne: null } }] };
+        return { $or: [{ [field]: { $gt: value } }, { [field]: value, [idF]: { $gt: id } }] };
+      }
       addTags;
       removeTags;
       // -------------------------------------------------------------------------
@@ -505,6 +590,35 @@ var sendOneOffInputSchema = z.object({
   providerOverride: z.string().optional(),
   dedupeKey: z.string().min(1).max(512)
 });
+var subscriptionStatusEnum = z.enum(["subscribed", "unsubscribed", "pending_doi", "bounced", "complained"]);
+var fieldNameSchema = (strict) => (strict ? z.string().min(1) : z.string()).max(256).regex(/^(?!\$)[^\0]*$/, "must not start with $");
+var segmentValueSchema = z.union([z.string(), z.number(), z.boolean(), z.null()]);
+function segmentFilterSchema(strict) {
+  const str = strict ? z.string().min(1).max(256) : z.string().max(256);
+  const days = z.number().int().positive().max(36500).optional();
+  const self = z.lazy(
+    () => z.discriminatedUnion("kind", [
+      z.object({ kind: z.literal("fieldEquals"), field: fieldNameSchema(strict), value: segmentValueSchema }),
+      z.object({ kind: z.literal("fieldIn"), field: fieldNameSchema(strict), values: z.array(segmentValueSchema).max(1e3) }),
+      z.object({ kind: z.literal("fieldExists"), field: fieldNameSchema(strict) }),
+      z.object({ kind: z.literal("hasTag"), tag: str }),
+      z.object({ kind: z.literal("notHasTag"), tag: str }),
+      z.object({ kind: z.literal("subscriptionStatus"), equals: subscriptionStatusEnum }),
+      z.object({ kind: z.literal("firedEvent"), eventName: str, withinDays: days }),
+      z.object({ kind: z.literal("notFiredEvent"), eventName: str, withinDays: days }),
+      z.object({ kind: z.literal("subscribedAfter"), date: z.coerce.date() }),
+      z.object({ kind: z.literal("subscribedBefore"), date: z.coerce.date() }),
+      z.object({ kind: z.literal("opened"), templateSlug: slugSchema.optional(), withinDays: days }),
+      z.object({ kind: z.literal("notOpened"), templateSlug: slugSchema.optional(), withinDays: days }),
+      z.object({ kind: z.literal("any"), filters: strict ? z.array(self).min(1).max(50) : z.array(self).max(50) }),
+      z.object({ kind: z.literal("not"), filter: self })
+    ])
+  );
+  return self;
+}
+function segmentDefinitionSchema(strict) {
+  return z.object({ filters: z.array(segmentFilterSchema(strict)).max(50) });
+}
 var flowStepSchema = z.lazy(
   () => z.discriminatedUnion("type", [
     z.object({
@@ -673,6 +787,13 @@ var CIRCUIT_BREAKER_DEFAULTS = {
   windowMinutes: 60,
   minSendsBeforeEval: 100
 };
+var BROADCAST_STOP_RULE_DEFAULTS = {
+  enabled: true,
+  hardBounceRatePct: 2,
+  complaintRatePct: 0.1,
+  unsubscribeRatePct: 1,
+  minSample: 100
+};
 function resolveConfig(c) {
   return {
     ...c,
@@ -700,7 +821,8 @@ function resolveConfig(c) {
     storeRenderedBody: c.storeRenderedBody ?? DEFAULTS.storeRenderedBody,
     requireSignedTrackingUrls: c.requireSignedTrackingUrls ?? DEFAULTS.requireSignedTrackingUrls,
     trackingUrlLifetimeDays: c.trackingUrlLifetimeDays ?? DEFAULTS.trackingUrlLifetimeDays,
-    circuitBreaker: { ...CIRCUIT_BREAKER_DEFAULTS, ...c.circuitBreaker ?? {} }
+    circuitBreaker: { ...CIRCUIT_BREAKER_DEFAULTS, ...c.circuitBreaker ?? {} },
+    broadcastStopRules: { ...BROADCAST_STOP_RULE_DEFAULTS, ...c.broadcastStopRules ?? {} }
   };
 }
 
@@ -918,11 +1040,13 @@ function resolveProvider(providers, name) {
 function registeredProviderNames(providers) {
   return Object.keys(providers).filter((name) => resolveProvider(providers, name) !== null).sort();
 }
+var SEND_ID_RE = /^[a-f0-9]{24}$/i;
 function signUnsubscribeToken(payload, secret) {
   const body = JSON.stringify({
     e: payload.email.toLowerCase(),
     s: payload.scope,
-    x: payload.expiresAt.getTime()
+    x: payload.expiresAt.getTime(),
+    ...payload.sendId && SEND_ID_RE.test(payload.sendId) ? { i: payload.sendId } : {}
   });
   const bodyB64 = b64url(Buffer.from(body, "utf8"));
   const hmac = crypto2.createHmac("sha256", secret).update(bodyB64).digest();
@@ -953,7 +1077,8 @@ function verifyUnsubscribeToken(token, secret, now = /* @__PURE__ */ new Date())
   return {
     email: body.e,
     scope: body.s,
-    expiresAt: new Date(body.x)
+    expiresAt: new Date(body.x),
+    ...typeof body.i === "string" && SEND_ID_RE.test(body.i) ? { sendId: body.i } : {}
   };
 }
 var TRACKING_SCOPES = ["open", "click"];
@@ -1728,6 +1853,211 @@ function effectiveOverallStatus(docs) {
   if (buckets.some((d) => d.status === "degraded")) return "degraded";
   return "healthy";
 }
+function emptyBroadcastStats() {
+  return withRates({
+    total: 0,
+    accepted: 0,
+    delivered: 0,
+    bounced: 0,
+    hardBounced: 0,
+    softBounced: 0,
+    complained: 0,
+    unsubscribed: 0,
+    opened: 0,
+    clicked: 0,
+    outcomes: 0
+  });
+}
+var pct = (n, d) => d > 0 ? Math.round(n / d * 1e4) / 100 : 0;
+function withRates(c) {
+  return {
+    ...c,
+    rates: {
+      deliveryRatePct: pct(c.delivered, c.accepted),
+      bounceRatePct: pct(c.bounced, c.outcomes),
+      hardBounceRatePct: pct(c.hardBounced, c.outcomes),
+      complaintRatePct: pct(c.complained, c.outcomes),
+      unsubscribeRatePct: pct(c.unsubscribed, c.outcomes),
+      openRatePct: pct(c.opened, c.delivered),
+      clickRatePct: pct(c.clicked, c.delivered)
+    }
+  };
+}
+var set = (field) => ({ $ifNull: [field, false] });
+var DELIVERED = {
+  $or: [set("$deliveredAt"), { $eq: ["$status", "delivered"] }, set("$complainedAt"), { $eq: ["$status", "complained"] }]
+};
+var BOUNCED = { $or: [{ $eq: ["$status", "bounced"] }, { $in: [{ $ifNull: ["$bounceType", null] }, ["hard", "soft"]] }] };
+var count = (expr) => ({ $sum: { $cond: [expr, 1, 0] } });
+async function aggregateBroadcastStats(collections, broadcastId) {
+  const rows = await collections.sends.aggregate([
+    { $match: broadcastId ? { broadcastId } : { broadcastId: { $ne: null } } },
+    {
+      $group: {
+        _id: "$broadcastId",
+        total: { $sum: 1 },
+        accepted: count(set("$sentAt")),
+        delivered: count(DELIVERED),
+        bounced: count(BOUNCED),
+        hardBounced: count({ $eq: ["$bounceType", "hard"] }),
+        softBounced: count({ $eq: ["$bounceType", "soft"] }),
+        complained: count({ $or: [set("$complainedAt"), { $eq: ["$status", "complained"] }] }),
+        unsubscribed: count(set("$unsubscribedAt")),
+        opened: count(set("$openedAt")),
+        clicked: count(set("$firstClickAt")),
+        outcomes: count({ $or: [DELIVERED, BOUNCED] })
+      }
+    }
+  ]).toArray();
+  const out = /* @__PURE__ */ new Map();
+  for (const { _id, ...c } of rows) {
+    if (_id) out.set(String(_id), withRates(c));
+  }
+  return out;
+}
+async function broadcastStatsFor(collections, broadcastId) {
+  return (await aggregateBroadcastStats(collections, broadcastId)).get(String(broadcastId)) ?? emptyBroadcastStats();
+}
+function effectiveStopRules(config, b) {
+  return { ...config.broadcastStopRules, ...b.stopRules ?? {} };
+}
+var RULE_COUNTS = [
+  ["complaintRatePct", "complained"],
+  ["hardBounceRatePct", "hardBounced"],
+  ["unsubscribeRatePct", "unsubscribed"]
+];
+function evaluateStopRules(stats, rules) {
+  const sample = stats.outcomes;
+  const evaluated = rules.enabled && sample > 0 && sample >= rules.minSample;
+  const breaches = [];
+  if (evaluated) {
+    for (const [rule, key] of RULE_COUNTS) {
+      const n = stats[key];
+      const exactPct = n / sample * 100;
+      if (exactPct > rules[rule]) {
+        breaches.push({ rule, count: n, ratePct: Math.round(exactPct * 100) / 100, thresholdPct: rules[rule] });
+      }
+    }
+  }
+  return { rules, sample, evaluated, breaches };
+}
+var RULE_LABEL = {
+  complaintRatePct: "complaint rate",
+  hardBounceRatePct: "hard bounce rate",
+  unsubscribeRatePct: "unsubscribe rate"
+};
+var PAUSE_PRECEDENCE = {
+  manual: 1,
+  cap_reached: 1,
+  stop_rule: 2,
+  circuit_breaker: 2
+};
+async function pauseBroadcast(ctx, broadcastId, reason, actor = "system:broadcast") {
+  const weaker = Object.keys(PAUSE_PRECEDENCE).filter(
+    (k) => PAUSE_PRECEDENCE[k] < PAUSE_PRECEDENCE[reason.code]
+  );
+  const b = await ctx.collections.broadcasts.findOneAndUpdate(
+    {
+      _id: broadcastId,
+      $or: [{ status: { $in: ["sending", "sent"] } }, { status: "paused", "pauseReason.code": { $in: weaker } }]
+    },
+    { $set: { status: "paused", pausedAt: reason.at, pauseReason: reason, updatedAt: /* @__PURE__ */ new Date() } },
+    { returnDocument: "after" }
+  );
+  if (!b) return { paused: false, heldSends: 0 };
+  const held = await holdQueuedSends(ctx, broadcastId, reason.code);
+  if (ctx.audit) {
+    await ctx.audit({
+      actor,
+      action: "broadcast.pause",
+      resource: { collection: "mailer_broadcasts", id: String(broadcastId), slug: b.slug },
+      diffSummary: `${reason.code}: ${reason.message} \xB7 held ${held} queued send(s)`
+    }).catch(() => {
+    });
+  }
+  if (ctx.config.onBroadcastPaused) {
+    try {
+      await ctx.config.onBroadcastPaused({ broadcastId: String(broadcastId), slug: b.slug, reason, heldSends: held });
+    } catch {
+    }
+  }
+  return { paused: true, heldSends: held };
+}
+async function holdQueuedSends(ctx, broadcastId, code) {
+  const res = await ctx.collections.sends.updateMany(
+    { broadcastId, status: "queued" },
+    { $set: { status: "held", errorMessage: `held: broadcast paused (${code})`, updatedAt: /* @__PURE__ */ new Date() } }
+  );
+  return res.modifiedCount;
+}
+async function releaseHeldSends(ctx, broadcastId) {
+  const held = await ctx.collections.sends.find({ broadcastId, status: "held" }, { projection: { _id: 1, notBefore: 1 } }).toArray();
+  if (held.length === 0) return 0;
+  await ctx.collections.sends.updateMany(
+    { _id: { $in: held.map((s) => s._id) }, status: "held" },
+    { $set: { status: "queued", errorMessage: null, updatedAt: /* @__PURE__ */ new Date() } }
+  );
+  const now = Date.now();
+  await Promise.all(
+    held.map((s) => {
+      const delay = s.notBefore ? Math.max(0, new Date(s.notBefore).getTime() - now) : 0;
+      return ctx.queues.send.add(
+        "send",
+        { sendId: String(s._id) },
+        {
+          attempts: ctx.config.sendRetryAttempts,
+          backoff: { type: "exponential", delay: 6e4 },
+          ...delay > 0 ? { delay } : {}
+        }
+      );
+    })
+  );
+  return held.length;
+}
+async function evaluateBroadcastStopRules(ctx, broadcastId) {
+  const b = await ctx.collections.broadcasts.findOne({ _id: broadcastId });
+  if (!b || !["sending", "sent", "paused"].includes(b.status)) return null;
+  if (b.status === "paused" && b.pauseReason && PAUSE_PRECEDENCE[b.pauseReason.code] >= 2) return null;
+  const stats = await broadcastStatsFor(ctx.collections, broadcastId);
+  const evaluation = evaluateStopRules(stats, effectiveStopRules(ctx.config, b));
+  if (evaluation.breaches.length === 0) return evaluation;
+  const now = /* @__PURE__ */ new Date();
+  if (b.status === "sent" && await ctx.collections.sends.countDocuments({ broadcastId, status: "queued" }) === 0) {
+    await ctx.collections.broadcasts.updateOne(
+      { _id: broadcastId, stopRuleBreach: { $in: [null] } },
+      { $set: { stopRuleBreach: { at: now, sample: evaluation.sample, breaches: evaluation.breaches } } }
+    );
+    return evaluation;
+  }
+  const first = evaluation.breaches[0];
+  await pauseBroadcast(ctx, broadcastId, {
+    code: "stop_rule",
+    message: `${RULE_LABEL[first.rule]} ${first.ratePct}% is over ${first.thresholdPct}% (${first.count} of ${evaluation.sample} sends with an outcome)`,
+    at: now,
+    details: { breaches: evaluation.breaches, sample: evaluation.sample, rules: evaluation.rules }
+  });
+  return evaluation;
+}
+var STOP_RULE_WINDOW_MS = 14 * 24 * 60 * 60 * 1e3;
+async function evaluateActiveBroadcastStopRules(ctx) {
+  const live = await ctx.collections.broadcasts.find(
+    { status: { $in: ["sending", "sent", "paused"] }, startedAt: { $gte: new Date(Date.now() - STOP_RULE_WINDOW_MS) } },
+    { projection: { _id: 1 } }
+  ).limit(200).toArray();
+  for (const { _id } of live) {
+    await evaluateBroadcastStopRules(ctx, _id).catch((err) => {
+      console.error("mailery: broadcast stop-rule evaluation failed", { id: String(_id), err });
+    });
+  }
+}
+async function attributeUnsubscribeToSend(ctx, sendId, email) {
+  if (!ObjectId.isValid(sendId)) return;
+  const _id = new ObjectId(sendId);
+  const send = await ctx.collections.sends.findOne({ _id }, { projection: { emailAtSend: 1, broadcastId: 1 } });
+  if (!send || send.emailAtSend.toLowerCase() !== email.toLowerCase()) return;
+  await ctx.collections.sends.updateOne({ _id, unsubscribedAt: null }, { $set: { unsubscribedAt: /* @__PURE__ */ new Date() } });
+  if (send.broadcastId) await evaluateBroadcastStopRules(ctx, send.broadcastId);
+}
 
 // src/server/runner/webhook.ts
 function dimsFromSend(send) {
@@ -1882,6 +2212,11 @@ async function applyWebhookEvent(event, ctx) {
       );
       break;
   }
+  if (send?.broadcastId && (event.type === "bounce" || event.type === "complaint" || event.type === "spam_report" || event.type === "unsubscribe")) {
+    await evaluateBroadcastStopRules(ctx, send.broadcastId).catch((err) => {
+      console.error("mailery: broadcast stop-rule evaluation failed", { id: String(send.broadcastId), err });
+    });
+  }
 }
 async function suppressOnce(ctx, email, reason, scope) {
   const normalized = email.toLowerCase();
@@ -2293,11 +2628,30 @@ async function isSuppressed(collections, email, kind) {
   if (byEmail) return { suppressed: true, scope: byEmail.scope, reason: byEmail.reason };
   const hashed = await collections.suppressions.findOne({
     emailHash: sha256Hex(normalized),
-    scope: { $in: allowed }
+    scope: { $in: allowed },
+    $or: [{ expiresAt: null }, { expiresAt: { $gt: /* @__PURE__ */ new Date() } }]
   });
   if (hashed) return { suppressed: true, scope: hashed.scope, reason: hashed.reason };
   return { suppressed: false };
 }
+async function suppressedEmails(collections, emails, kind) {
+  const normalized = [...new Set(emails.map((e) => e.toLowerCase()))];
+  if (normalized.length === 0) return /* @__PURE__ */ new Set();
+  const allowed = SCOPES_BY_KIND[kind];
+  const live = { $or: [{ expiresAt: null }, { expiresAt: { $gt: /* @__PURE__ */ new Date() } }] };
+  const byHash = new Map(normalized.map((e) => [sha256Hex(e), e]));
+  const [plain, hashed] = await Promise.all([
+    collections.suppressions.distinct("email", { email: { $in: normalized }, scope: { $in: allowed }, ...live }),
+    collections.suppressions.distinct("emailHash", { emailHash: { $in: [...byHash.keys()] }, scope: { $in: allowed }, ...live })
+  ]);
+  const out = /* @__PURE__ */ new Set();
+  for (const e of plain) if (typeof e === "string") out.add(e);
+  for (const h of hashed) {
+    const e = byHash.get(String(h));
+    if (e) out.add(e);
+  }
+  return out;
+}
 
 // src/server/runner/send.ts
 async function handleSend(run, step, contact, flow, ctx) {
@@ -2374,6 +2728,27 @@ async function dispatchSend(sendId, ctx) {
     await markFailed(send._id, "template_missing", ctx);
     return;
   }
+  if (send.broadcastId) {
+    const broadcast = await ctx.collections.broadcasts.findOne(
+      { _id: send.broadcastId },
+      { projection: { status: 1, pauseReason: 1 } }
+    );
+    const holding = broadcast?.status === "paused" && broadcast.pauseReason?.code !== "cap_reached";
+    if (holding || broadcast?.status === "cancelled") {
+      const held = holding;
+      await ctx.collections.sends.updateOne(
+        { _id: send._id },
+        {
+          $set: {
+            status: held ? "held" : "cancelled",
+            errorMessage: held ? `held: broadcast paused (${broadcast.pauseReason?.code ?? "unknown"})` : "cancelled: broadcast cancelled",
+            updatedAt: /* @__PURE__ */ new Date()
+          }
+        }
+      );
+      return;
+    }
+  }
   const supp = await isSuppressed(ctx.collections, send.emailAtSend, send.kind);
   if (supp.suppressed) {
     await ctx.collections.sends.updateOne(
@@ -2384,6 +2759,19 @@ async function dispatchSend(sendId, ctx) {
   }
   if (send.kind === "marketing") {
     const bucket = await getBucketStatus(ctx, send.fromEmail, send.kind);
+    if (bucket?.status === "tripped" && send.broadcastId) {
+      await ctx.collections.sends.updateOne(
+        { _id: send._id },
+        { $set: { status: "held", errorMessage: "held: circuit breaker tripped", updatedAt: /* @__PURE__ */ new Date() } }
+      );
+      await pauseBroadcast(ctx, send.broadcastId, {
+        code: "circuit_breaker",
+        message: `the ${bucket.senderDomain ?? "sender"} ${send.kind} circuit breaker is tripped: ${bucket.trippedReason ?? "no reason recorded"}`,
+        at: /* @__PURE__ */ new Date(),
+        details: { bucket: bucket._id }
+      });
+      return;
+    }
     if (bucket?.status === "tripped") {
       await ctx.collections.sends.updateOne(
         { _id: send._id },
@@ -2416,7 +2804,7 @@ async function dispatchSend(sendId, ctx) {
       eventName: run?.triggerEvent?.name,
       eventProperties: run?.triggerEvent?.properties
     });
-    renderCtx = buildRenderContext(contact, run, send.vars ?? {}, ctx, resolved);
+    renderCtx = buildRenderContext(contact, run, send.vars ?? {}, ctx, resolved, String(send._id));
     rendered = await renderTemplate(template, renderCtx, { helpers: ctx.handlebarsHelpers });
   } catch (err) {
     await markFailed(send._id, `render error: ${String(err?.message ?? err)}`, ctx);
@@ -2507,11 +2895,11 @@ function pickProviderName(stepOverride, tpl, ctx) {
   }
   return ctx.config.defaultProvider;
 }
-function buildRenderContext(contact, run, vars, ctx, resolved = {}) {
+function buildRenderContext(contact, run, vars, ctx, resolved = {}, sendId) {
   const scope = "marketing";
   const expiresAt = new Date(Date.now() + ctx.config.unsubscribeTokenLifetimeDays * 24 * 60 * 60 * 1e3);
   const token = signUnsubscribeToken(
-    { email: contact.email, scope, expiresAt },
+    { email: contact.email, scope, expiresAt, ...sendId ? { sendId } : {} },
     ctx.config.unsubscribeSecret
   );
   const unsubscribeUrl = `${ctx.config.publicUrl}/m/unsub/${token}`;
@@ -2887,6 +3275,184 @@ async function sweepStrandedFlowRuns(ctx) {
     }
   }
 }
+
+// src/server/runner/segment.ts
+function planSegment(seg) {
+  const hostFilter = {};
+  const postFilters = [];
+  const hostFields = /* @__PURE__ */ new Set();
+  const takeField = (field) => {
+    if (hostFields.has(field)) return false;
+    hostFields.add(field);
+    return true;
+  };
+  for (const f of seg.filters ?? []) {
+    switch (f.kind) {
+      case "hasTag":
+        if (hostFilter.hasTag === void 0) {
+          hostFilter.hasTag = f.tag;
+          continue;
+        }
+        break;
+      case "fieldEquals":
+        if (!hostFilter.fieldEquals && takeField(f.field)) {
+          hostFilter.fieldEquals = { field: f.field, value: f.value };
+          continue;
+        }
+        break;
+      case "fieldIn":
+        if (!hostFilter.fieldIn && takeField(f.field)) {
+          hostFilter.fieldIn = { field: f.field, values: f.values };
+          continue;
+        }
+        break;
+      case "fieldExists":
+        if (!hostFilter.fieldExists && takeField(f.field)) {
+          hostFilter.fieldExists = f.field;
+          continue;
+        }
+        break;
+    }
+    postFilters.push(f);
+  }
+  return { hostFilter, postFilters };
+}
+async function applyPostFilters(contacts, filters, ctx, now = /* @__PURE__ */ new Date()) {
+  if (filters.length === 0 || contacts.length === 0) return contacts;
+  const externalIds = contacts.map((c) => c.externalId);
+  const leaves = /* @__PURE__ */ new Map();
+  collectLookups(filters, leaves);
+  const cache = /* @__PURE__ */ new Map();
+  await Promise.all(
+    [...leaves].map(async ([key, f]) => {
+      cache.set(key, await lookup(f, externalIds, ctx, now));
+    })
+  );
+  return contacts.filter((c) => filters.every((f) => matches(c, f, cache)));
+}
+function lookupKey(f) {
+  switch (f.kind) {
+    case "subscriptionStatus":
+      return `sub:${f.equals}`;
+    case "firedEvent":
+    case "notFiredEvent":
+      return `evt:${f.withinDays ?? ""}:${f.eventName}`;
+    case "opened":
+    case "notOpened":
+      return `open:${f.withinDays ?? ""}:${f.templateSlug ?? ""}`;
+    case "subscribedAfter":
+      return `subAfter:${toDate(f.date).getTime()}`;
+    case "subscribedBefore":
+      return `subBefore:${toDate(f.date).getTime()}`;
+    default:
+      return null;
+  }
+}
+function collectLookups(filters, out) {
+  for (const f of filters) {
+    if (f.kind === "any") collectLookups(f.filters, out);
+    else if (f.kind === "not") collectLookups([f.filter], out);
+    else {
+      const key = lookupKey(f);
+      if (key && !out.has(key)) out.set(key, f);
+    }
+  }
+}
+async function lookup(f, externalIds, ctx, now) {
+  const c = ctx.collections;
+  const inPage = { $in: externalIds };
+  const since = (days) => days ? new Date(now.getTime() - days * 864e5) : null;
+  let ids;
+  switch (f.kind) {
+    case "subscriptionStatus":
+      ids = await c.subscriptions.distinct("externalId", { externalId: inPage, status: f.equals });
+      break;
+    case "firedEvent":
+    case "notFiredEvent": {
+      const cutoff = since(f.withinDays);
+      ids = await c.events.distinct("externalId", {
+        externalId: inPage,
+        name: f.eventName,
+        ...cutoff ? { occurredAt: { $gt: cutoff } } : {}
+      });
+      break;
+    }
+    case "opened":
+    case "notOpened": {
+      const cutoff = since(f.withinDays);
+      ids = await c.sends.distinct("externalId", {
+        externalId: inPage,
+        openedAt: cutoff ? { $gt: cutoff } : { $ne: null },
+        ...f.templateSlug ? { templateSlug: f.templateSlug } : {}
+      });
+      break;
+    }
+    case "subscribedAfter":
+      ids = await c.subscriptions.distinct("externalId", { externalId: inPage, subscribedAt: { $gt: toDate(f.date) } });
+      break;
+    case "subscribedBefore":
+      ids = await c.subscriptions.distinct("externalId", { externalId: inPage, subscribedAt: { $lt: toDate(f.date) } });
+      break;
+    default:
+      ids = [];
+  }
+  return new Set(ids.map(String));
+}
+function matches(c, f, cache) {
+  switch (f.kind) {
+    case "subscriptionStatus":
+    case "firedEvent":
+    case "opened":
+    case "subscribedAfter":
+    case "subscribedBefore":
+      return cache.get(lookupKey(f))?.has(c.externalId) ?? false;
+    case "notFiredEvent":
+    case "notOpened":
+      return !(cache.get(lookupKey(f))?.has(c.externalId) ?? false);
+    case "hasTag":
+      return c.tags.includes(f.tag);
+    case "notHasTag":
+      return !c.tags.includes(f.tag);
+    case "fieldEquals":
+      return valuesEqual(fieldValue(c, f.field), f.value);
+    case "fieldIn": {
+      const v = fieldValue(c, f.field);
+      return f.values.some((x) => valuesEqual(v, x));
+    }
+    case "fieldExists":
+      return fieldValue(c, f.field) !== void 0;
+    case "any":
+      return f.filters.some((sub) => matches(c, sub, cache));
+    case "not":
+      return !matches(c, f.filter, cache);
+    default:
+      throw new Error(`mailery: unknown segment filter kind "${f.kind}"`);
+  }
+}
+function fieldValue(c, path3) {
+  let cur = c.fields;
+  for (const part of path3.split(".")) {
+    if (cur === null || typeof cur !== "object") return void 0;
+    cur = cur[part];
+  }
+  return cur;
+}
+function valuesEqual(a, b) {
+  if (a instanceof Date || b instanceof Date) {
+    const ta = a instanceof Date ? a.getTime() : new Date(a).getTime();
+    const tb = b instanceof Date ? b.getTime() : new Date(b).getTime();
+    return !Number.isNaN(ta) && ta === tb;
+  }
+  if (a && typeof a === "object" && typeof a.toHexString === "function") {
+    return String(a) === String(b);
+  }
+  return a === b;
+}
+function toDate(d) {
+  return d instanceof Date ? d : new Date(d);
+}
+
+// src/server/runner/broadcasts.ts
 var STALLED_BROADCAST_THRESHOLD_MS = 10 * 60 * 1e3;
 async function processScheduledBroadcasts(ctx) {
   const now = /* @__PURE__ */ new Date();
@@ -2894,7 +3460,7 @@ async function processScheduledBroadcasts(ctx) {
   for (const b of due) {
     const claimed = await ctx.collections.broadcasts.findOneAndUpdate(
       { _id: b._id, status: "scheduled" },
-      { $set: { status: "sending", startedAt: now, updatedAt: now } },
+      { $set: { status: "sending", startedAt: now, updatedAt: now, dispatchLeaseId: null } },
       { returnDocument: "after" }
     );
     if (!claimed) continue;
@@ -2902,8 +3468,14 @@ async function processScheduledBroadcasts(ctx) {
   }
 }
 async function startBroadcastDispatch(broadcast, ctx) {
+  const bumped = await ctx.collections.broadcasts.findOneAndUpdate(
+    { _id: broadcast._id },
+    { $inc: { dispatchGeneration: 1 } },
+    { returnDocument: "after" }
+  );
+  const current = bumped ?? broadcast;
   if (ctx.config.queue.driver === "noop") {
-    await runBroadcastDispatch(broadcast, ctx);
+    await runBroadcastDispatch(current, ctx);
     return;
   }
   await ctx.queues.advance.add(
@@ -2912,7 +3484,7 @@ async function startBroadcastDispatch(broadcast, ctx) {
     {
       attempts: 3,
       backoff: { type: "exponential", delay: 6e4 },
-      jobId: `broadcast-dispatch:${broadcast._id}`
+      jobId: `broadcast-dispatch:${broadcast._id}:${current.dispatchGeneration ?? 0}`
     }
   );
 }
@@ -2925,10 +3497,11 @@ async function resumeStalledBroadcasts(ctx) {
   const cutoff = new Date(Date.now() - STALLED_BROADCAST_THRESHOLD_MS);
   const stalled = await ctx.collections.broadcasts.find({ status: "sending", updatedAt: { $lt: cutoff } }).toArray();
   for (const b of stalled) {
-    await ctx.collections.broadcasts.updateOne(
-      { _id: b._id },
-      { $set: { updatedAt: /* @__PURE__ */ new Date() } }
+    const reset = await ctx.collections.broadcasts.updateOne(
+      { _id: b._id, status: "sending", updatedAt: { $lt: cutoff } },
+      { $set: { dispatchLeaseId: null, updatedAt: /* @__PURE__ */ new Date() } }
     );
+    if (reset.modifiedCount === 0) continue;
     await startBroadcastDispatch(b, ctx);
   }
 }
@@ -2938,166 +3511,196 @@ async function runBroadcastDispatch(broadcast, ctx) {
   } catch (err) {
     console.error("mailery: broadcast dispatch failed", { id: String(broadcast._id), err });
     await ctx.collections.broadcasts.updateOne(
-      { _id: broadcast._id },
-      { $set: { status: "failed", updatedAt: /* @__PURE__ */ new Date() } }
+      { _id: broadcast._id, status: "sending" },
+      {
+        $set: {
+          status: "failed",
+          failureReason: `dispatch error: ${String(err?.message ?? err)}`,
+          updatedAt: /* @__PURE__ */ new Date(),
+          dispatchLeaseId: null
+        }
+      }
     );
   }
 }
+function broadcastDedupeKey(broadcastId, externalId) {
+  return `broadcast:${broadcastId}:${externalId}`;
+}
+var SENDABLE_EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+function isSendableEmail(email) {
+  return typeof email === "string" && SENDABLE_EMAIL_RE.test(email);
+}
+async function* eligibleRecipientPages(broadcast, kind, ctx) {
+  const { hostFilter, postFilters } = planSegment(broadcast.segmentDefinition);
+  const sort = broadcast.order ?? void 0;
+  if (sort && !ctx.adapter.supportsSort) {
+    throw new Error("mailery: this broadcast has an order but the contact adapter does not support sorted queries");
+  }
+  let cursor;
+  for (; ; ) {
+    const page = await ctx.adapter.query(hostFilter, {
+      limit: ctx.config.broadcastEnqueueBatchSize,
+      cursor,
+      ...sort ? { sort: { field: sort.field, direction: sort.direction } } : {}
+    });
+    if (page.contacts.length === 0) break;
+    const passed = (await applyPostFilters(page.contacts, postFilters, ctx)).filter((c) => isSendableEmail(c.email));
+    const suppressed = await suppressedEmails(ctx.collections, passed.map((c) => c.email), kind);
+    yield passed.filter((c) => !suppressed.has(c.email.toLowerCase()));
+    if (!page.nextCursor) break;
+    cursor = page.nextCursor;
+  }
+}
+async function alreadyDispatched(ctx, broadcastId, contacts) {
+  if (contacts.length === 0) return /* @__PURE__ */ new Set();
+  const keys = contacts.map((c) => broadcastDedupeKey(broadcastId, c.externalId));
+  const found = await ctx.collections.sends.distinct("dedupeKey", { dedupeKey: { $in: keys } });
+  return new Set(found.map(String));
+}
+async function countBroadcastRecipients(broadcast, kind, ctx) {
+  const t0 = Date.now();
+  const { hostFilter } = planSegment(broadcast.segmentDefinition);
+  const [hostMatched, sendsSoFar] = await Promise.all([
+    ctx.adapter.count(hostFilter),
+    broadcast._id ? ctx.collections.sends.countDocuments({ broadcastId: broadcast._id }) : Promise.resolve(0)
+  ]);
+  let eligible = 0;
+  let alreadySent = 0;
+  for await (const page of eligibleRecipientPages(broadcast, kind, ctx)) {
+    eligible += page.length;
+    if (broadcast._id) alreadySent += (await alreadyDispatched(ctx, broadcast._id, page)).size;
+  }
+  const cap = typeof broadcast.recipientCap === "number" ? broadcast.recipientCap : null;
+  const uncapped = eligible - alreadySent;
+  const recipientCount = cap === null ? uncapped : Math.max(0, Math.min(uncapped, cap - sendsSoFar));
+  return {
+    hostMatched,
+    eligible,
+    alreadySent,
+    sendsSoFar,
+    recipientCap: cap,
+    uncappedRecipientCount: uncapped,
+    recipientCount,
+    computedMs: Date.now() - t0
+  };
+}
 async function dispatchBroadcast(broadcast, ctx) {
   const template = await ctx.collections.templates.findOne({ slug: broadcast.templateSlug });
-  if (!template) {
+  const failure = !template ? `template "${broadcast.templateSlug}" not found` : template.kind !== "marketing" ? `template "${broadcast.templateSlug}" is ${template.kind}, not marketing` : null;
+  if (failure || !template) {
     await ctx.collections.broadcasts.updateOne(
-      { _id: broadcast._id },
-      { $set: { status: "failed", updatedAt: /* @__PURE__ */ new Date() } }
+      { _id: broadcast._id, status: "sending" },
+      { $set: { status: "failed", failureReason: failure, updatedAt: /* @__PURE__ */ new Date(), dispatchLeaseId: null } }
     );
     return;
   }
-  const hostFilter = toAdapterFilter(broadcast.segmentDefinition);
-  const postFilters = broadcast.segmentDefinition.filters.filter((f) => isMailerSide(f));
-  let cursor = void 0;
-  let total = 0;
-  const batchSize = ctx.config.broadcastEnqueueBatchSize;
+  const leaseId = new ObjectId().toHexString();
+  const staleCutoff = new Date(Date.now() - STALLED_BROADCAST_THRESHOLD_MS);
+  const b = await ctx.collections.broadcasts.findOneAndUpdate(
+    {
+      _id: broadcast._id,
+      status: "sending",
+      $or: [{ dispatchLeaseId: null }, { dispatchLeaseId: { $exists: false } }, { updatedAt: { $lt: staleCutoff } }]
+    },
+    { $set: { dispatchLeaseId: leaseId, updatedAt: /* @__PURE__ */ new Date() } },
+    { returnDocument: "after" }
+  );
+  if (!b) return;
+  const holdsLease = async () => (await ctx.collections.broadcasts.updateOne(
+    { _id: b._id, status: "sending", dispatchLeaseId: leaseId },
+    { $set: { updatedAt: /* @__PURE__ */ new Date() } }
+  )).matchedCount === 1;
   const maxWaiting = ctx.config.broadcastEnqueueMaxWaiting;
-  const respectTimezone = broadcast.respectRecipientTimezone === true;
-  const scheduledMs = broadcast.scheduledAt?.getTime() ?? Date.now();
-  for (; ; ) {
-    await ctx.collections.broadcasts.updateOne(
-      { _id: broadcast._id },
-      { $set: { updatedAt: /* @__PURE__ */ new Date() } }
-    );
-    const page = await ctx.adapter.query(hostFilter, { limit: batchSize, cursor });
-    if (page.contacts.length === 0) break;
-    const eligible = await applyPostFilters(page.contacts, postFilters, ctx);
-    if (eligible.length > 0) {
+  const respectTimezone = b.respectRecipientTimezone === true;
+  const scheduledMs = b.scheduledAt?.getTime() ?? Date.now();
+  const cap = typeof b.recipientCap === "number" ? b.recipientCap : null;
+  let capReached = false;
+  try {
+    for await (const eligible of eligibleRecipientPages(b, template.kind, ctx)) {
+      if (!await holdsLease()) return;
+      const bucket = await getBucketStatus(ctx, template.fromEmail, template.kind);
+      if (bucket?.status === "tripped") {
+        await pauseBroadcast(ctx, b._id, {
+          code: "circuit_breaker",
+          message: `the ${bucket.senderDomain ?? "sender"} ${template.kind} circuit breaker is tripped: ${bucket.trippedReason ?? "no reason recorded"}`,
+          at: /* @__PURE__ */ new Date(),
+          details: { bucket: bucket._id }
+        });
+        return;
+      }
+      const seen = await alreadyDispatched(ctx, b._id, eligible);
+      let fresh = eligible.filter((c) => !seen.has(broadcastDedupeKey(b._id, c.externalId)));
+      if (fresh.length === 0) continue;
+      if (cap !== null) {
+        const room = cap - await ctx.collections.sends.countDocuments({ broadcastId: b._id });
+        if (room <= 0) {
+          capReached = true;
+          break;
+        }
+        if (fresh.length > room) {
+          fresh = fresh.slice(0, room);
+          capReached = true;
+        }
+      }
       while (await ctx.queues.send.getWaitingCount() > maxWaiting) {
-        await ctx.collections.broadcasts.updateOne(
-          { _id: broadcast._id },
-          { $set: { updatedAt: /* @__PURE__ */ new Date() } }
-        );
+        if (!await holdsLease()) return;
         await sleep(2e3);
       }
-      const sendDocs = await Promise.all(
-        eligible.map(async (contact) => buildSendDoc(broadcast, template, contact, ctx, scheduledMs, respectTimezone))
-      );
       const inserted = [];
-      for (const { doc, delayMs } of sendDocs) {
-        if (!doc) continue;
+      for (const contact of fresh) {
+        const { doc, delayMs } = buildSendDoc(b, template, contact, ctx, scheduledMs, respectTimezone);
         try {
           await ctx.collections.sends.insertOne(doc);
           inserted.push({ sendId: doc._id, delayMs });
         } catch (err) {
-          if (err?.code !== 11e3) throw err;
-        }
-      }
-      if (inserted.length > 0) {
-        await Promise.all(
-          inserted.map(
-            ({ sendId, delayMs }) => ctx.queues.send.add(
-              "send",
-              { sendId: String(sendId) },
-              {
-                attempts: ctx.config.sendRetryAttempts,
-                backoff: { type: "exponential", delay: 6e4 },
-                ...delayMs > 0 ? { delay: delayMs } : {}
-              }
-            )
-          )
-        );
-      }
-      total += inserted.length;
-    }
-    if (!page.nextCursor) break;
-    cursor = page.nextCursor;
-  }
-  await ctx.collections.broadcasts.updateOne(
-    { _id: broadcast._id },
-    {
-      $set: {
-        status: "sent",
-        completedAt: /* @__PURE__ */ new Date(),
-        recipientCount: total,
-        updatedAt: /* @__PURE__ */ new Date()
-      }
-    }
-  );
-}
-function toAdapterFilter(seg) {
-  const out = {};
-  for (const f of seg.filters) {
-    switch (f.kind) {
-      case "hasTag":
-        out.hasTag = f.tag;
-        break;
-      case "fieldEquals":
-        out.fieldEquals = { field: f.field, value: f.value };
-        break;
-      case "fieldIn":
-        out.fieldIn = { field: f.field, values: f.values };
-        break;
-      case "fieldExists":
-        out.fieldExists = f.field;
-        break;
-    }
-  }
-  return out;
-}
-function isMailerSide(f) {
-  return f.kind === "subscriptionStatus" || f.kind === "firedEvent" || f.kind === "notFiredEvent" || f.kind === "subscribedAfter" || f.kind === "subscribedBefore" || f.kind === "opened" || f.kind === "notOpened" || f.kind === "notHasTag" || f.kind === "any" || f.kind === "not";
-}
-async function applyPostFilters(contacts, filters, ctx) {
-  if (filters.length === 0) return contacts;
-  const externalIds = contacts.map((c) => c.externalId);
-  const cache = {};
-  for (const f of filters) {
-    if (f.kind === "subscriptionStatus") {
-      const docs = await ctx.collections.subscriptions.find({ externalId: { $in: externalIds }, status: f.equals }).project({ externalId: 1 }).toArray();
-      cache[`sub:${f.equals}`] = new Set(docs.map((d) => d.externalId));
-    }
-    if (f.kind === "firedEvent" || f.kind === "notFiredEvent") {
-      const query = { externalId: { $in: externalIds }, name: f.eventName };
-      if (f.withinDays) {
-        query.occurredAt = { $gt: new Date(Date.now() - f.withinDays * 864e5) };
-      }
-      const docs = await ctx.collections.events.find(query).project({ externalId: 1 }).toArray();
-      cache[`evt:${f.eventName}`] = new Set(docs.map((d) => d.externalId));
-    }
-  }
-  return contacts.filter((c) => filters.every((f) => filterMatches(c, f, cache)));
-}
-function filterMatches(c, f, cache) {
-  switch (f.kind) {
-    case "subscriptionStatus":
-      return cache[`sub:${f.equals}`]?.has(c.externalId) ?? false;
-    case "firedEvent":
-      return cache[`evt:${f.eventName}`]?.has(c.externalId) ?? false;
-    case "notFiredEvent":
-      return !cache[`evt:${f.eventName}`]?.has(c.externalId);
-    case "notHasTag":
-      return !c.tags.includes(f.tag);
-    case "opened":
-    case "notOpened":
-      return true;
-    case "subscribedAfter":
-    case "subscribedBefore":
-      return true;
-    // V2
-    case "any":
-      return f.filters.some((sub) => filterMatches(c, sub, cache));
-    case "not":
-      return !filterMatches(c, f.filter, cache);
-    default:
-      return true;
+          if (err?.code !== 11e3) throw err;
+        }
+      }
+      await Promise.all(
+        inserted.map(
+          ({ sendId, delayMs }) => ctx.queues.send.add(
+            "send",
+            { sendId: String(sendId) },
+            {
+              attempts: ctx.config.sendRetryAttempts,
+              backoff: { type: "exponential", delay: 6e4 },
+              ...delayMs > 0 ? { delay: delayMs } : {}
+            }
+          )
+        )
+      );
+      if (capReached) break;
+    }
+    const now = /* @__PURE__ */ new Date();
+    const total = await ctx.collections.sends.countDocuments({ broadcastId: b._id });
+    const set2 = capReached ? {
+      status: "paused",
+      pausedAt: now,
+      pauseReason: {
+        code: "cap_reached",
+        message: `${total} send(s) reached recipientCap ${cap}; eligible recipients remain \u2014 raise recipientCap and resume to send the next wave`,
+        at: now,
+        details: { recipientCap: cap, sendsSoFar: total }
+      }
+    } : { status: "sent", completedAt: now };
+    await ctx.collections.broadcasts.updateOne(
+      { _id: b._id, status: "sending", dispatchLeaseId: leaseId },
+      { $set: { ...set2, recipientCount: total, updatedAt: now, dispatchLeaseId: null } }
+    );
+  } finally {
+    await ctx.collections.broadcasts.updateOne(
+      { _id: b._id, dispatchLeaseId: leaseId },
+      { $set: { dispatchLeaseId: null } }
+    );
   }
 }
-async function buildSendDoc(broadcast, template, contact, ctx, scheduledMs, respectTimezone) {
-  const supp = await isSuppressed(ctx.collections, contact.email, template.kind);
-  if (supp.suppressed) return { doc: null, delayMs: 0 };
+function buildSendDoc(broadcast, template, contact, ctx, scheduledMs, respectTimezone) {
   const sendId = new ObjectId();
-  const dedupeKey = `broadcast:${broadcast._id}:${contact.externalId}`;
-  let delayMs = Math.max(0, scheduledMs - Date.now());
+  const dedupeKey = broadcastDedupeKey(broadcast._id, contact.externalId);
+  const now = Date.now();
+  let delayMs = Math.max(0, scheduledMs - now);
   if (respectTimezone && contact.timezone) {
-    const offsetMs = perRecipientOffsetMs(scheduledMs, contact.timezone);
-    delayMs = Math.max(0, scheduledMs + offsetMs - Date.now());
+    delayMs = Math.max(0, recipientSlotMs(scheduledMs, contact.timezone, now) - now);
   }
   const doc = {
     _id: sendId,
@@ -3132,16 +3735,29 @@ async function buildSendDoc(broadcast, template, contact, ctx, scheduledMs, resp
     queuedAt: /* @__PURE__ */ new Date(),
     updatedAt: /* @__PURE__ */ new Date(),
     sentAt: null,
-    deliveredAt: null
+    deliveredAt: null,
+    notBefore: new Date(Date.now() + delayMs)
   };
   return { doc, delayMs };
 }
+var DAY_MS = 24 * 60 * 60 * 1e3;
+var TZ_SLOT_GRACE_MS = 15 * 60 * 1e3;
+function recipientSlotMs(scheduledMs, timezone, nowMs) {
+  let anchor = scheduledMs;
+  let target = anchor + perRecipientOffsetMs(anchor, timezone);
+  const earliest = nowMs - TZ_SLOT_GRACE_MS;
+  if (target < earliest) {
+    anchor += Math.ceil((earliest - target) / DAY_MS) * DAY_MS;
+    target = anchor + perRecipientOffsetMs(anchor, timezone);
+    if (target < earliest) target += DAY_MS;
+  }
+  return target;
+}
 function perRecipientOffsetMs(scheduledMs, timezone) {
-  const DAY_MS2 = 24 * 60 * 60 * 1e3;
   try {
     const scheduled = new Date(scheduledMs);
-    const utc = scheduled.toLocaleString("en-US", { timeZone: "UTC", hour12: false });
-    const local = scheduled.toLocaleString("en-US", { timeZone: timezone, hour12: false });
+    const utc = scheduled.toLocaleString("en-US", { timeZone: "UTC", hourCycle: "h23" });
+    const local = scheduled.toLocaleString("en-US", { timeZone: timezone, hourCycle: "h23" });
     const parse = (s) => {
       const m = s.match(/(\d+)\/(\d+)\/(\d+),\s*(\d+):(\d+):(\d+)/);
       if (!m) return 0;
@@ -3150,7 +3766,7 @@ function perRecipientOffsetMs(scheduledMs, timezone) {
     const utcMs = parse(utc);
     const localMs = parse(local);
     const offsetMs = utcMs - localMs;
-    return (offsetMs % DAY_MS2 + DAY_MS2) % DAY_MS2;
+    return (offsetMs % DAY_MS + DAY_MS) % DAY_MS;
   } catch {
     return 0;
   }
@@ -3262,9 +3878,9 @@ async function runDnsblChecks(ctx, opts = {}) {
   let listedCount = 0;
   async function processPair(p) {
     const queryName = buildQueryName(p.target, p.targetKind, p.list.host);
-    const lookup = queryName ? await queryDnsbl(resolver, queryName) : { result: "error", returnCodes: [], errorMessage: "unsupported target format" };
-    if (lookup.transient) return;
-    if (lookup.result === "listed") listedCount++;
+    const lookup2 = queryName ? await queryDnsbl(resolver, queryName) : { result: "error", returnCodes: [], errorMessage: "unsupported target format" };
+    if (lookup2.transient) return;
+    if (lookup2.result === "listed") listedCount++;
     await ctx.collections.dnsblChecks.updateOne(
       { target: p.target, list: p.list.host },
       {
@@ -3273,9 +3889,9 @@ async function runDnsblChecks(ctx, opts = {}) {
           targetKind: p.targetKind,
           list: p.list.host,
           listLabel: p.list.label,
-          result: lookup.result,
-          returnCodes: lookup.returnCodes,
-          errorMessage: lookup.errorMessage,
+          result: lookup2.result,
+          returnCodes: lookup2.returnCodes,
+          errorMessage: lookup2.errorMessage,
           runAt: /* @__PURE__ */ new Date()
         }
       },
@@ -3919,17 +4535,17 @@ function parseDmarcReport(xml) {
   const day = new Date(midMs).toISOString().slice(0, 10);
   for (const rec of records) {
     const row = rec?.row ?? {};
-    const count = Number(row.count ?? 0) || 0;
-    totalMessages += count;
+    const count2 = Number(row.count ?? 0) || 0;
+    totalMessages += count2;
     const evald = row.policy_evaluated ?? {};
     const dkim = evald.dkim ?? "none";
     const spf = evald.spf ?? "none";
     const aligned = dkim === "pass" || spf === "pass";
     if (aligned) {
-      passCount += count;
+      passCount += count2;
       continue;
     }
-    failCount += count;
+    failCount += count2;
     const sourceIp = String(row.source_ip ?? "").trim();
     if (!sourceIp) continue;
     const headerFrom = String(rec?.identifiers?.header_from ?? "").toLowerCase();
@@ -3938,7 +4554,7 @@ function parseDmarcReport(xml) {
       reportId,
       domain,
       sourceIp,
-      count,
+      count: count2,
       headerFrom,
       dkimResult: dkim,
       spfResult: spf,
@@ -4083,11 +4699,11 @@ function suggestPolicyProgression(input) {
     return null;
   }
   if (currentPolicy === "quarantine") {
-    const pct = currentPct ?? 100;
+    const pct2 = currentPct ?? 100;
     if (alignmentRate < 0.995) return null;
-    if (pct < 25) return { policy: "quarantine", pct: 25, reason: `Alignment held at ${(alignmentRate * 100).toFixed(2)}% \u2014 safe to ramp pct from ${pct} to 25.` };
-    if (pct < 50) return { policy: "quarantine", pct: 50, reason: `Alignment held at ${(alignmentRate * 100).toFixed(2)}% \u2014 safe to ramp pct from ${pct} to 50.` };
-    if (pct < 100) return { policy: "quarantine", pct: 100, reason: `Alignment held at ${(alignmentRate * 100).toFixed(2)}% \u2014 safe to ramp pct from ${pct} to 100.` };
+    if (pct2 < 25) return { policy: "quarantine", pct: 25, reason: `Alignment held at ${(alignmentRate * 100).toFixed(2)}% \u2014 safe to ramp pct from ${pct2} to 25.` };
+    if (pct2 < 50) return { policy: "quarantine", pct: 50, reason: `Alignment held at ${(alignmentRate * 100).toFixed(2)}% \u2014 safe to ramp pct from ${pct2} to 50.` };
+    if (pct2 < 100) return { policy: "quarantine", pct: 100, reason: `Alignment held at ${(alignmentRate * 100).toFixed(2)}% \u2014 safe to ramp pct from ${pct2} to 100.` };
     if (alignmentRate >= 0.999) {
       return { policy: "reject", pct: 100, reason: `Alignment at ${(alignmentRate * 100).toFixed(3)}% with policy=quarantine pct=100 \u2014 safe to move to p=reject.` };
     }
@@ -4398,6 +5014,9 @@ async function runTick(ctx) {
   await resumeStalledBroadcasts(ctx).catch((err) => {
     console.error("mailery: stalled-broadcast resume failed", err);
   });
+  await evaluateActiveBroadcastStopRules(ctx).catch((err) => {
+    console.error("mailery: broadcast stop-rule sweep failed", err);
+  });
   await evaluateHealth(ctx).catch((err) => {
     console.error("mailery: health evaluation failed", err);
   });
@@ -6105,7 +6724,7 @@ function humanDuration(ms) {
 }
 
 // src/server/runner/hygiene.ts
-var DAY_MS = 864e5;
+var DAY_MS2 = 864e5;
 var HYGIENE_BUCKETS = [
   { label: "Engaged (last 30 days)", maxDays: 30 },
   { label: "Engaged (31-60 days)", minDays: 30, maxDays: 60 },
@@ -6118,7 +6737,7 @@ async function computeListHygiene(ctx, opts = {}) {
   const now = opts.now ?? Date.now();
   const sunsetDays = opts.sunsetThresholdDays ?? 180;
   const recentDays = opts.recentWindowDays ?? 90;
-  const recentCutoff = new Date(now - recentDays * DAY_MS);
+  const recentCutoff = new Date(now - recentDays * DAY_MS2);
   const totalSubscribers = await ctx.collections.subscriptions.countDocuments({ status: "subscribed" });
   const subscribedIds = /* @__PURE__ */ new Set();
   {
@@ -6191,11 +6810,11 @@ async function computeListHygiene(ctx, opts = {}) {
     if (lastEngaged == null) {
       const firstSent = row.firstSent ? new Date(row.firstSent).getTime() : null;
       buckets[5].count++;
-      if (firstSent != null && now - firstSent > sunsetDays * DAY_MS) {
+      if (firstSent != null && now - firstSent > sunsetDays * DAY_MS2) {
         isSunset = true;
       }
     } else {
-      const daysSince = (now - lastEngaged) / DAY_MS;
+      const daysSince = (now - lastEngaged) / DAY_MS2;
       if (daysSince <= 30) buckets[0].count++;
       else if (daysSince <= 60) buckets[1].count++;
       else if (daysSince <= 90) buckets[2].count++;
@@ -6394,6 +7013,462 @@ async function evaluateMailTesterGate(ctx, input) {
   }
   return { allowed: true, reason: null, score: cached, code: null };
 }
+var BroadcastOperationError = class extends Error {
+  constructor(code, message, status = 400, details) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.details = details;
+    this.name = "BroadcastOperationError";
+  }
+  code;
+  status;
+  details;
+};
+var DEFAULT_SEGMENT = {
+  filters: [{ kind: "subscriptionStatus", equals: "subscribed" }]
+};
+var MAX_RECIPIENT_CAP = 1e7;
+var ORDER_FIELD_RE = /^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*$/;
+var recipientCapSchema = z.number().int().positive().max(MAX_RECIPIENT_CAP).nullable();
+var orderSchema = z.object({
+  field: z.string().max(128).regex(ORDER_FIELD_RE, "must be a plain field path, e.g. updatedAt"),
+  direction: z.enum(["asc", "desc"])
+}).nullable();
+var pctSchema = z.number().min(0).max(100);
+var stopRulesSchema = z.object({
+  enabled: z.boolean().optional(),
+  hardBounceRatePct: pctSchema.optional(),
+  complaintRatePct: pctSchema.optional(),
+  unsubscribeRatePct: pctSchema.optional(),
+  minSample: z.number().int().min(1).max(1e6).optional()
+}).strict().nullable();
+var agentCreateBroadcastSchema = z.object({
+  slug: slugSchema,
+  name: z.string().min(1).max(200),
+  templateSlug: slugSchema,
+  segmentDefinition: z.object({ filters: z.array(z.any()) }).optional(),
+  respectRecipientTimezone: z.boolean().optional(),
+  recipientCap: recipientCapSchema.optional(),
+  order: orderSchema.optional(),
+  stopRules: stopRulesSchema.optional()
+});
+var agentPatchBroadcastSchema = z.object({
+  name: z.string().min(1).max(200).optional(),
+  templateSlug: slugSchema.optional(),
+  segmentDefinition: z.object({ filters: z.array(z.any()) }).optional(),
+  respectRecipientTimezone: z.boolean().optional(),
+  recipientCap: recipientCapSchema.optional(),
+  order: orderSchema.optional(),
+  stopRules: stopRulesSchema.optional()
+});
+var agentResumeBroadcastSchema = z.object({
+  recipientCap: recipientCapSchema.optional(),
+  stopRules: stopRulesSchema.optional(),
+  confirmedCount: z.number().int().nonnegative()
+});
+var agentPauseBroadcastSchema = z.object({
+  reason: z.string().max(500).optional()
+});
+function checkWaveSettings(mailer, input) {
+  if (input.stopRules !== void 0 && !stopRulesSchema.safeParse(input.stopRules).success) {
+    throw new BroadcastOperationError(
+      "invalid_stop_rules",
+      "stopRules must be {enabled?, hardBounceRatePct?, complaintRatePct?, unsubscribeRatePct?, minSample?} (percentages 0-100), or null"
+    );
+  }
+  if (input.recipientCap !== void 0 && !recipientCapSchema.safeParse(input.recipientCap).success) {
+    throw new BroadcastOperationError("invalid_recipient_cap", `recipientCap must be a positive integer up to ${MAX_RECIPIENT_CAP}, or null`);
+  }
+  if (input.order !== void 0) {
+    if (!orderSchema.safeParse(input.order).success) {
+      throw new BroadcastOperationError("invalid_order", 'order must be {field: "<host field path>", direction: "asc" | "desc"}, or null');
+    }
+    if (input.order !== null && !mailer.adapter.supportsSort) {
+      throw new BroadcastOperationError(
+        "adapter_cannot_sort",
+        "the contact adapter does not declare supportsSort, so a broadcast cannot be sent in an order; omit order to send in the adapter's own order",
+        422
+      );
+    }
+  }
+}
+var agentScheduleBroadcastSchema = z.object({
+  scheduledAt: z.string().min(1),
+  confirmedCount: z.number().int().nonnegative(),
+  respectRecipientTimezone: z.boolean().optional()
+});
+function parseSegment(seg, strict) {
+  const r = segmentDefinitionSchema(strict).safeParse(seg);
+  if (!r.success) {
+    throw new BroadcastOperationError(
+      "invalid_segment",
+      `segmentDefinition: ${r.error.issues.map((i) => `${i.path.join(".") || "filters"}: ${i.message}`).join("; ")}`,
+      400
+    );
+  }
+  return r.data;
+}
+function assertSubscribedSegment(seg) {
+  const filters = Array.isArray(seg?.filters) ? seg.filters : [];
+  const ok = filters.some((f) => f && f.kind === "subscriptionStatus" && f.equals === "subscribed");
+  if (!ok) {
+    throw new BroadcastOperationError(
+      "segment_requires_subscribed",
+      'the agent API only schedules broadcasts to subscribed contacts: add {"kind": "subscriptionStatus", "equals": "subscribed"} to segmentDefinition.filters (top level)',
+      422
+    );
+  }
+}
+async function loadBroadcast(mailer, slug) {
+  const b = await mailer.collections.broadcasts.findOne({ slug });
+  if (!b) throw new BroadcastOperationError("not_found", `no broadcast with slug "${slug}"`, 404);
+  return b;
+}
+async function loadBroadcastTemplate(mailer, b) {
+  const tpl = await mailer.collections.templates.findOne({ slug: b.templateSlug });
+  if (!tpl) {
+    throw new BroadcastOperationError("template_not_found", `template "${b.templateSlug}" does not exist`, 409);
+  }
+  return tpl;
+}
+async function countRecipients(mailer, b, segment, overrides = {}) {
+  const tpl = await loadBroadcastTemplate(mailer, b);
+  const count2 = await countBroadcastRecipients(
+    {
+      _id: b._id,
+      segmentDefinition: segment ?? b.segmentDefinition,
+      order: b.order ?? null,
+      recipientCap: overrides.recipientCap !== void 0 ? overrides.recipientCap : b.recipientCap ?? null
+    },
+    tpl.kind,
+    mailer.getRunnerContext()
+  );
+  const heldSends = b._id ? await mailer.collections.sends.countDocuments({ broadcastId: b._id, status: "held" }) : 0;
+  return { ...count2, heldSends, templateKind: tpl.kind };
+}
+function stopRuleStatus(mailer, b, stats) {
+  return evaluateStopRules(stats, effectiveStopRules(mailer.config, b));
+}
+async function pauseBroadcastByOperator(mailer, slug, input, actor) {
+  const b = await loadBroadcast(mailer, slug);
+  if (b.status !== "sending" && b.status !== "sent") {
+    throw new BroadcastOperationError("not_pausable", `broadcast is ${b.status}; only a sending or sent broadcast can be paused (cancel a draft or scheduled one)`, 409);
+  }
+  const out = await pauseBroadcast(
+    mailer.getRunnerContext(),
+    b._id,
+    { code: "manual", message: input.reason?.trim() || `paused by ${actor}`, at: /* @__PURE__ */ new Date(), details: { actor } },
+    actor
+  );
+  if (!out.paused) throw new BroadcastOperationError("not_pausable", "broadcast changed state while being paused", 409);
+  return { broadcast: await mailer.collections.broadcasts.findOne({ _id: b._id }) ?? b, heldSends: out.heldSends };
+}
+async function createBroadcast(mailer, input, actor, opts = {}) {
+  const { slug, name, templateSlug } = input;
+  if (!slug || !name || !templateSlug) {
+    throw new BroadcastOperationError("validation_failed", "slug, name, templateSlug required");
+  }
+  const segmentDefinition = input.segmentDefinition ? parseSegment(input.segmentDefinition, !!opts.strictSegment) : DEFAULT_SEGMENT;
+  if (opts.requireSubscribed) assertSubscribedSegment(segmentDefinition);
+  checkWaveSettings(mailer, input);
+  await assertBroadcastTemplate(mailer, templateSlug, { mustExist: false });
+  const now = /* @__PURE__ */ new Date();
+  const doc = {
+    slug,
+    name,
+    templateSlug,
+    segmentDefinition,
+    status: "draft",
+    scheduledAt: null,
+    startedAt: null,
+    completedAt: null,
+    confirmationRequired: true,
+    confirmedCount: null,
+    confirmedAt: null,
+    confirmedBy: null,
+    recipientCount: null,
+    stats: { sent: 0, delivered: 0, opened: 0, clicked: 0, bounced: 0, complained: 0, unsubscribed: 0 },
+    createdAt: now,
+    createdBy: actor,
+    updatedAt: now
+  };
+  if (input.respectRecipientTimezone) doc.respectRecipientTimezone = true;
+  if (input.recipientCap !== void 0) doc.recipientCap = input.recipientCap;
+  if (input.order !== void 0) doc.order = input.order;
+  if (input.stopRules !== void 0) doc.stopRules = input.stopRules;
+  try {
+    const res = await mailer.collections.broadcasts.insertOne(doc);
+    doc._id = res.insertedId;
+  } catch (err) {
+    if (err?.code === 11e3) throw new BroadcastOperationError("slug_taken", `slug "${slug}" is taken`, 409);
+    throw err;
+  }
+  await mailer.audit({
+    actor,
+    action: "broadcast.create",
+    resource: { collection: "mailer_broadcasts", id: doc._id, slug }
+  });
+  return doc;
+}
+async function patchBroadcast(mailer, slug, patch, actor, opts = {}) {
+  const b = await loadBroadcast(mailer, slug);
+  if (b.status !== "draft") {
+    throw new BroadcastOperationError("not_draft", `broadcast is ${b.status}; only a draft can be edited`, 409);
+  }
+  const segmentDefinition = patch.segmentDefinition ? parseSegment(patch.segmentDefinition, !!opts.strictSegment) : void 0;
+  if (opts.requireSubscribed && segmentDefinition) assertSubscribedSegment(segmentDefinition);
+  checkWaveSettings(mailer, patch);
+  if (typeof patch.templateSlug === "string") await assertBroadcastTemplate(mailer, patch.templateSlug, { mustExist: false });
+  const set2 = { updatedAt: /* @__PURE__ */ new Date() };
+  if (patch.recipientCap !== void 0) set2.recipientCap = patch.recipientCap;
+  if (patch.order !== void 0) set2.order = patch.order;
+  if (patch.stopRules !== void 0) set2.stopRules = patch.stopRules;
+  if (typeof patch.name === "string") set2.name = patch.name;
+  if (typeof patch.templateSlug === "string") set2.templateSlug = patch.templateSlug;
+  if (segmentDefinition) set2.segmentDefinition = segmentDefinition;
+  if (typeof patch.respectRecipientTimezone === "boolean") set2.respectRecipientTimezone = patch.respectRecipientTimezone;
+  const res = await mailer.collections.broadcasts.findOneAndUpdate(
+    { _id: b._id, status: "draft" },
+    { $set: set2 },
+    { returnDocument: "after" }
+  );
+  if (!res) throw new BroadcastOperationError("not_draft", "broadcast left draft while being edited", 409);
+  await mailer.audit({
+    actor,
+    action: "broadcast.update",
+    resource: { collection: "mailer_broadcasts", id: b._id, slug },
+    diffSummary: Object.keys(set2).filter((k) => k !== "updatedAt").join(", ")
+  });
+  return res;
+}
+async function scheduleBroadcast(mailer, slug, input, actor, opts = {}) {
+  const b = await loadBroadcast(mailer, slug);
+  if (b.status !== "draft") {
+    throw new BroadcastOperationError("not_draft", `broadcast is ${b.status}; only a draft can be scheduled`, 409);
+  }
+  if (opts.requireSubscribed) assertSubscribedSegment(b.segmentDefinition);
+  parseSegment(b.segmentDefinition, true);
+  await assertBroadcastTemplate(mailer, b.templateSlug, { mustExist: true });
+  if (!input.scheduledAt) throw new BroadcastOperationError("scheduledAt_required", "scheduledAt is required");
+  const scheduled = new Date(input.scheduledAt);
+  if (Number.isNaN(scheduled.getTime())) throw new BroadcastOperationError("bad_scheduledAt", "scheduledAt is not a date");
+  if (typeof input.confirmedCount !== "number") {
+    throw new BroadcastOperationError("confirmedCount_required", "confirmedCount (number) is required");
+  }
+  const confirmedCount = input.confirmedCount;
+  const threshold = mailer.config.broadcastConfirmationThreshold;
+  if (opts.requireExactCount) {
+    const { recipientCount } = await countRecipients(mailer, b);
+    if (confirmedCount !== recipientCount) {
+      throw new BroadcastOperationError(
+        "count_mismatch",
+        `confirmedCount ${confirmedCount} does not match the ${recipientCount} recipient(s) this broadcast would send to now; recount with POST /broadcasts/${b.slug}/count`,
+        409,
+        { expected: recipientCount, confirmedCount }
+      );
+    }
+  }
+  const set2 = {
+    status: "scheduled",
+    scheduledAt: scheduled,
+    confirmedCount,
+    confirmedAt: /* @__PURE__ */ new Date(),
+    confirmedBy: actor,
+    updatedAt: /* @__PURE__ */ new Date()
+  };
+  if (input.respectRecipientTimezone) set2.respectRecipientTimezone = true;
+  const res = await mailer.collections.broadcasts.findOneAndUpdate(
+    { _id: b._id, status: "draft" },
+    { $set: set2 },
+    { returnDocument: "after" }
+  );
+  if (!res) throw new BroadcastOperationError("not_draft", "broadcast left draft while being scheduled", 409);
+  await mailer.audit({
+    actor,
+    action: "broadcast.schedule",
+    resource: { collection: "mailer_broadcasts", id: b._id, slug: b.slug },
+    diffSummary: `scheduled at ${scheduled.toISOString()} \xB7 confirmedCount=${confirmedCount} \xB7 threshold=${threshold}`
+  });
+  return res;
+}
+async function resumeBroadcast(mailer, slug, input, actor, opts = {}) {
+  const b = await loadBroadcast(mailer, slug);
+  if (b.status !== "paused") {
+    throw new BroadcastOperationError("not_paused", `broadcast is ${b.status}; only a paused broadcast can be resumed`, 409);
+  }
+  if (opts.requireSubscribed) assertSubscribedSegment(b.segmentDefinition);
+  checkWaveSettings(mailer, { recipientCap: input.recipientCap, stopRules: input.stopRules });
+  const cap = input.recipientCap !== void 0 ? input.recipientCap : b.recipientCap ?? null;
+  const stopRules = input.stopRules === void 0 ? b.stopRules ?? null : input.stopRules === null ? null : { ...b.stopRules ?? {}, ...input.stopRules };
+  if (b.pauseReason?.code === "stop_rule") {
+    const evaluation = evaluateStopRules(
+      await broadcastStatsFor(mailer.collections, b._id),
+      effectiveStopRules(mailer.config, { stopRules })
+    );
+    if (evaluation.breaches.length > 0) {
+      throw new BroadcastOperationError(
+        "stop_rule_still_breached",
+        `the stop rules still fire (${evaluation.breaches.map((x) => `${x.rule} ${x.ratePct}% > ${x.thresholdPct}%`).join(", ")}); investigate, then resume with adjusted stopRules to override`,
+        409,
+        { evaluation }
+      );
+    }
+  }
+  if (b.pauseReason?.code === "circuit_breaker") {
+    const tpl = await loadBroadcastTemplate(mailer, b);
+    const bucket = await getBucketStatus(mailer.getRunnerContext(), tpl.fromEmail, tpl.kind);
+    if (bucket?.status === "tripped") {
+      throw new BroadcastOperationError(
+        "circuit_breaker_tripped",
+        `the ${bucket.senderDomain ?? "sender"} ${tpl.kind} circuit breaker is still tripped (${bucket.trippedReason ?? "no reason recorded"}); resume it first (POST /api/health/resume)`,
+        409,
+        { bucket: bucket._id, trippedReason: bucket.trippedReason }
+      );
+    }
+  }
+  const sendsSoFar = await mailer.collections.sends.countDocuments({ broadcastId: b._id });
+  if (cap !== null && cap <= sendsSoFar && b.pauseReason?.code === "cap_reached") {
+    throw new BroadcastOperationError(
+      "cap_not_raised",
+      `${sendsSoFar} send(s) already count against recipientCap ${cap}; pass a higher recipientCap (or null for no cap) to send the next wave`,
+      409,
+      { recipientCap: cap, sendsSoFar }
+    );
+  }
+  if (cap !== null && cap < sendsSoFar) {
+    throw new BroadcastOperationError("cap_below_sent", `recipientCap ${cap} is below the ${sendsSoFar} send(s) already made`, 400);
+  }
+  let expected = null;
+  if (opts.requireExactCount) {
+    if (typeof input.confirmedCount !== "number") {
+      throw new BroadcastOperationError("confirmedCount_required", "confirmedCount (number) is required");
+    }
+    const count2 = await countRecipients(mailer, b, void 0, { recipientCap: cap });
+    expected = count2.recipientCount + count2.heldSends;
+    if (input.confirmedCount !== expected) {
+      throw new BroadcastOperationError(
+        "count_mismatch",
+        `confirmedCount ${input.confirmedCount} does not match the ${expected} send(s) resuming would release now (${count2.recipientCount} new + ${count2.heldSends} held)`,
+        409,
+        { expected, recipientCount: count2.recipientCount, heldSends: count2.heldSends, confirmedCount: input.confirmedCount }
+      );
+    }
+  }
+  const now = /* @__PURE__ */ new Date();
+  const resumed = await mailer.collections.broadcasts.findOneAndUpdate(
+    { _id: b._id, status: "paused" },
+    {
+      $set: {
+        status: "sending",
+        recipientCap: cap,
+        stopRules,
+        pausedAt: null,
+        pauseReason: null,
+        dispatchLeaseId: null,
+        updatedAt: now,
+        ...typeof input.confirmedCount === "number" ? { confirmedCount: input.confirmedCount, confirmedAt: now, confirmedBy: actor } : {}
+      }
+    },
+    { returnDocument: "after" }
+  );
+  if (!resumed) throw new BroadcastOperationError("not_paused", "broadcast left paused while being resumed", 409);
+  await mailer.audit({
+    actor,
+    action: "broadcast.resume",
+    resource: { collection: "mailer_broadcasts", id: b._id, slug: b.slug },
+    diffSummary: `was paused (${b.pauseReason?.code ?? "unknown"}) \xB7 recipientCap ${b.recipientCap ?? "none"} \u2192 ${cap ?? "none"} \xB7 sendsSoFar=${sendsSoFar}${expected !== null ? ` \xB7 confirmedCount=${expected}` : ""}`
+  });
+  const ctx = mailer.getRunnerContext();
+  await releaseHeldSends(ctx, b._id);
+  await startBroadcastDispatch(resumed, ctx);
+  return await mailer.collections.broadcasts.findOne({ _id: b._id }) ?? resumed;
+}
+async function cancelBroadcast(mailer, slug, actor) {
+  const b = await loadBroadcast(mailer, slug);
+  if (b.status === "cancelled") return { broadcast: b, cancelledSends: 0 };
+  const pending = await mailer.collections.sends.countDocuments({ broadcastId: b._id, status: { $in: ["queued", "held"] } });
+  if ((b.status === "sent" || b.status === "failed") && pending === 0) {
+    throw new BroadcastOperationError("already_finished", `broadcast is ${b.status} with nothing left to send; there is nothing to cancel`, 409);
+  }
+  await mailer.collections.broadcasts.updateOne({ _id: b._id }, { $set: { status: "cancelled", updatedAt: /* @__PURE__ */ new Date() } });
+  const now = /* @__PURE__ */ new Date();
+  const cancelled = await mailer.collections.sends.updateMany(
+    { broadcastId: b._id, status: { $in: ["queued", "held"] } },
+    { $set: { status: "cancelled", errorMessage: `cancelled: broadcast cancelled by ${actor}`, updatedAt: now } }
+  );
+  await mailer.audit({
+    actor,
+    action: "broadcast.cancel",
+    resource: { collection: "mailer_broadcasts", id: b._id, slug: b.slug },
+    diffSummary: `was ${b.status}; cancelled ${cancelled.modifiedCount} queued/held send(s)`
+  });
+  const after = await mailer.collections.broadcasts.findOne({ _id: b._id });
+  return { broadcast: after ?? b, cancelledSends: cancelled.modifiedCount };
+}
+async function assertBroadcastTemplate(mailer, templateSlug, opts) {
+  const tpl = await mailer.collections.templates.findOne({ slug: templateSlug });
+  if (!tpl) {
+    if (opts.mustExist) throw new BroadcastOperationError("template_not_found", `template "${templateSlug}" does not exist`, 409);
+    return;
+  }
+  if (tpl.kind !== "marketing") {
+    throw new BroadcastOperationError(
+      "template_not_marketing",
+      `template "${templateSlug}" is ${tpl.kind}; a broadcast needs a marketing template (List-Unsubscribe, marketing opt-outs, circuit breaker)`,
+      409
+    );
+  }
+  if (opts.mustExist && !tpl.body?.html && !tpl.body?.mjml) {
+    throw new BroadcastOperationError("template_not_published", `template "${templateSlug}" has no published body`, 409);
+  }
+}
+async function computeBroadcastStats(mailer, idFilter) {
+  return aggregateBroadcastStats(mailer.collections, idFilter);
+}
+function capProgress(b, stats) {
+  const cap = typeof b.recipientCap === "number" ? b.recipientCap : null;
+  return {
+    recipientCap: cap,
+    sendsSoFar: stats.total,
+    remaining: cap === null ? null : Math.max(0, cap - stats.total)
+  };
+}
+async function broadcastStatusBreakdown(mailer, broadcastId) {
+  const rows = await mailer.collections.sends.aggregate([
+    { $match: { broadcastId } },
+    { $group: { _id: "$status", n: { $sum: 1 } } }
+  ]).toArray();
+  return Object.fromEntries(rows.map((r) => [r._id, r.n]));
+}
+function broadcastSummary(b) {
+  return {
+    id: String(b._id),
+    slug: b.slug,
+    name: b.name,
+    templateSlug: b.templateSlug,
+    status: b.status,
+    segmentDefinition: b.segmentDefinition,
+    respectRecipientTimezone: b.respectRecipientTimezone === true,
+    recipientCap: b.recipientCap ?? null,
+    order: b.order ?? null,
+    pausedAt: b.pausedAt ?? null,
+    pauseReason: b.pauseReason ?? null,
+    stopRules: b.stopRules ?? null,
+    stopRuleBreach: b.stopRuleBreach ?? null,
+    failureReason: b.failureReason ?? null,
+    scheduledAt: b.scheduledAt,
+    startedAt: b.startedAt,
+    completedAt: b.completedAt,
+    confirmedCount: b.confirmedCount,
+    confirmedAt: b.confirmedAt,
+    confirmedBy: b.confirmedBy,
+    recipientCount: b.recipientCount,
+    createdAt: b.createdAt,
+    createdBy: b.createdBy,
+    updatedAt: b.updatedAt
+  };
+}
 
 // src/server/api/admin.ts
 var __filename$1 = fileURLToPath(import.meta.url);
@@ -7196,19 +8271,19 @@ function createAdminApiRouter(mailer, opts = {}) {
       const flow = await c.flows.findOne({ slug: req.params.slug });
       if (!flow) return res.status(404).json({ error: "not_found" });
       const { steps, notes, trigger, name, description, goal, audience } = req.body ?? {};
-      const set = {
+      const set2 = {
         "draft.lastModifiedBy": req.actor,
         "draft.lastModifiedAt": /* @__PURE__ */ new Date(),
         updatedAt: /* @__PURE__ */ new Date()
       };
-      if (Array.isArray(steps)) set["draft.steps"] = steps;
-      if (typeof notes === "string") set["draft.notes"] = notes;
-      if (trigger?.eventName) set.trigger = { type: "event", eventName: trigger.eventName, once: trigger.once !== false };
-      if (typeof name === "string") set.name = name;
-      if (typeof description === "string") set.description = description;
-      if (typeof goal === "string") set.goal = goal;
-      if (typeof audience === "string") set.audience = audience;
-      await c.flows.updateOne({ _id: flow._id }, { $set: set });
+      if (Array.isArray(steps)) set2["draft.steps"] = steps;
+      if (typeof notes === "string") set2["draft.notes"] = notes;
+      if (trigger?.eventName) set2.trigger = { type: "event", eventName: trigger.eventName, once: trigger.once !== false };
+      if (typeof name === "string") set2.name = name;
+      if (typeof description === "string") set2.description = description;
+      if (typeof goal === "string") set2.goal = goal;
+      if (typeof audience === "string") set2.audience = audience;
+      await c.flows.updateOne({ _id: flow._id }, { $set: set2 });
       await mailer.audit({
         actor: req.actor,
         action: "flow.draft.update",
@@ -7369,25 +8444,25 @@ function createAdminApiRouter(mailer, opts = {}) {
           }
         );
       }
-      const set = {
+      const set2 = {
         "draft.lastModifiedBy": req.actor,
         "draft.lastModifiedAt": /* @__PURE__ */ new Date(),
         updatedAt: /* @__PURE__ */ new Date()
       };
-      if (typeof subject === "string") set["draft.subject"] = subject;
-      if (typeof preheader === "string") set["draft.preheader"] = preheader;
-      if (typeof mjml === "string") set["draft.mjml"] = mjml;
-      if (typeof html === "string") set["draft.html"] = html;
-      if (editorJson !== void 0) set["draft.editorJson"] = editorJson;
-      if (typeof notes === "string") set["draft.notes"] = notes;
-      if (typeof name === "string") set.name = name;
-      if (typeof fromName === "string") set.fromName = fromName;
-      if (typeof fromEmail === "string") set.fromEmail = fromEmail;
-      if (typeof replyTo === "string" || replyTo === null) set.replyTo = replyTo;
-      if (kind === "marketing" || kind === "transactional") set.kind = kind;
+      if (typeof subject === "string") set2["draft.subject"] = subject;
+      if (typeof preheader === "string") set2["draft.preheader"] = preheader;
+      if (typeof mjml === "string") set2["draft.mjml"] = mjml;
+      if (typeof html === "string") set2["draft.html"] = html;
+      if (editorJson !== void 0) set2["draft.editorJson"] = editorJson;
+      if (typeof notes === "string") set2["draft.notes"] = notes;
+      if (typeof name === "string") set2.name = name;
+      if (typeof fromName === "string") set2.fromName = fromName;
+      if (typeof fromEmail === "string") set2.fromEmail = fromEmail;
+      if (typeof replyTo === "string" || replyTo === null) set2.replyTo = replyTo;
+      if (kind === "marketing" || kind === "transactional") set2.kind = kind;
       if (typeof fromEmail === "string" || kind === "marketing" || kind === "transactional") {
-        const resultingKind = set.kind ?? tpl.kind;
-        const resultingFromEmail = set.fromEmail ?? tpl.fromEmail;
+        const resultingKind = set2.kind ?? tpl.kind;
+        const resultingFromEmail = set2.fromEmail ?? tpl.fromEmail;
         const senderCheck = validateSenderDomain(resultingFromEmail, resultingKind, mailer.config.senderDomains);
         if (!senderCheck.ok) {
           return res.status(400).json({
@@ -7397,10 +8472,10 @@ function createAdminApiRouter(mailer, opts = {}) {
           });
         }
       }
-      if (TEMPLATE_BODY_FORMATS.includes(bodyFormat)) set.bodyFormat = bodyFormat;
-      if (typeof trackOpens === "boolean") set.trackOpens = trackOpens;
-      if (typeof trackClicks === "boolean") set.trackClicks = trackClicks;
-      await c.templates.updateOne({ _id: tpl._id }, { $set: set });
+      if (TEMPLATE_BODY_FORMATS.includes(bodyFormat)) set2.bodyFormat = bodyFormat;
+      if (typeof trackOpens === "boolean") set2.trackOpens = trackOpens;
+      if (typeof trackClicks === "boolean") set2.trackClicks = trackClicks;
+      await c.templates.updateOne({ _id: tpl._id }, { $set: set2 });
       await mailer.audit({
         actor: req.actor,
         action: "template.draft.update",
@@ -7878,125 +8953,60 @@ function createAdminApiRouter(mailer, opts = {}) {
   );
   r.post(
     "/broadcasts",
-    asyncHandler(async (req, res) => {
-      const { slug, name, templateSlug, segmentDefinition } = req.body ?? {};
-      if (!slug || !name || !templateSlug) {
-        return res.status(400).json({ error: "validation_failed", message: "slug, name, templateSlug required" });
-      }
-      const now = /* @__PURE__ */ new Date();
-      try {
-        await c.broadcasts.insertOne({
-          slug,
-          name,
-          templateSlug,
-          segmentDefinition: segmentDefinition ?? { filters: [{ kind: "subscriptionStatus", equals: "subscribed" }] },
-          status: "draft",
-          scheduledAt: null,
-          startedAt: null,
-          completedAt: null,
-          confirmationRequired: true,
-          confirmedCount: null,
-          confirmedAt: null,
-          confirmedBy: null,
-          recipientCount: null,
-          stats: { sent: 0, delivered: 0, opened: 0, clicked: 0, bounced: 0, complained: 0, unsubscribed: 0 },
-          createdAt: now,
-          createdBy: req.actor,
-          updatedAt: now
-        });
-      } catch (err) {
-        if (err?.code === 11e3) return res.status(409).json({ error: "slug_taken" });
-        throw err;
-      }
-      await mailer.audit({
-        actor: req.actor,
-        action: "broadcast.create",
-        resource: { collection: "mailer_broadcasts", slug }
-      });
+    broadcastHandler(async (req, res) => {
+      const { slug, name, templateSlug, segmentDefinition, respectRecipientTimezone, recipientCap, order } = req.body ?? {};
+      await createBroadcast(
+        mailer,
+        { slug, name, templateSlug, segmentDefinition, respectRecipientTimezone, recipientCap, order },
+        req.actor
+      );
       return res.json({ ok: true, slug });
     })
   );
   r.patch(
     "/broadcasts/:slug",
-    asyncHandler(async (req, res) => {
-      const b = await c.broadcasts.findOne({ slug: req.params.slug });
-      if (!b) return res.status(404).json({ error: "not_found" });
-      if (b.status !== "draft") return res.status(409).json({ error: "not_draft" });
-      const { name, templateSlug, segmentDefinition } = req.body ?? {};
-      const set = { updatedAt: /* @__PURE__ */ new Date() };
-      if (typeof name === "string") set.name = name;
-      if (typeof templateSlug === "string") set.templateSlug = templateSlug;
-      if (segmentDefinition) set.segmentDefinition = segmentDefinition;
-      await c.broadcasts.updateOne({ _id: b._id }, { $set: set });
+    broadcastHandler(async (req, res) => {
+      const { name, templateSlug, segmentDefinition, respectRecipientTimezone, recipientCap, order } = req.body ?? {};
+      await patchBroadcast(
+        mailer,
+        String(req.params.slug),
+        { name, templateSlug, segmentDefinition, respectRecipientTimezone, recipientCap, order },
+        req.actor
+      );
       return res.json({ ok: true });
     })
   );
   r.post(
     "/broadcasts/:slug/segment/count",
-    asyncHandler(async (req, res) => {
-      const segmentDefinition = req.body?.segmentDefinition;
-      if (!segmentDefinition?.filters) return res.status(400).json({ error: "segment_required" });
-      const t0 = Date.now();
-      const hostFilter = {};
-      for (const f of segmentDefinition.filters) {
-        if (f.kind === "hasTag") hostFilter.hasTag = f.tag;
-        if (f.kind === "fieldEquals") hostFilter.fieldEquals = { field: f.field, value: f.value };
-      }
-      const hasMailerFilters = segmentDefinition.filters.some(
-        (f) => ["subscriptionStatus", "firedEvent", "notFiredEvent", "notHasTag", "opened", "notOpened", "subscribedAfter", "subscribedBefore"].includes(f.kind)
-      );
-      const upperBound = await mailer.adapter.count(hostFilter);
+    broadcastHandler(async (req, res) => {
+      const raw = req.body?.segmentDefinition;
+      if (!raw?.filters) return res.status(400).json({ error: "segment_required" });
+      const segment = parseSegment(raw, false);
+      const b = await loadBroadcast(mailer, String(req.params.slug));
+      const count2 = await countRecipients(mailer, b, segment);
       return res.json({
-        upperBound,
-        approximate: hasMailerFilters,
-        computedMs: Date.now() - t0
+        upperBound: count2.recipientCount,
+        approximate: false,
+        computedMs: count2.computedMs,
+        hostMatched: count2.hostMatched,
+        eligible: count2.eligible,
+        alreadySent: count2.alreadySent,
+        recipientCount: count2.recipientCount
       });
     })
   );
   r.post(
     "/broadcasts/:slug/schedule",
-    asyncHandler(async (req, res) => {
-      const b = await c.broadcasts.findOne({ slug: req.params.slug });
-      if (!b) return res.status(404).json({ error: "not_found" });
-      if (b.status !== "draft") return res.status(409).json({ error: "not_draft" });
+    broadcastHandler(async (req, res) => {
       const { scheduledAt, confirmedCount, respectRecipientTimezone } = req.body ?? {};
-      if (!scheduledAt) return res.status(400).json({ error: "scheduledAt_required" });
-      const scheduled = new Date(scheduledAt);
-      if (Number.isNaN(scheduled.getTime())) return res.status(400).json({ error: "bad_scheduledAt" });
-      const threshold = mailer.config.broadcastConfirmationThreshold;
-      if (typeof confirmedCount !== "number") {
-        return res.status(400).json({ error: "confirmedCount_required" });
-      }
-      const set = {
-        status: "scheduled",
-        scheduledAt: scheduled,
-        confirmedCount,
-        confirmedAt: /* @__PURE__ */ new Date(),
-        confirmedBy: req.actor,
-        updatedAt: /* @__PURE__ */ new Date()
-      };
-      if (respectRecipientTimezone) set.respectRecipientTimezone = true;
-      await c.broadcasts.updateOne({ _id: b._id }, { $set: set });
-      await mailer.audit({
-        actor: req.actor,
-        action: "broadcast.schedule",
-        resource: { collection: "mailer_broadcasts", id: b._id, slug: b.slug },
-        diffSummary: `scheduled at ${scheduled.toISOString()} \xB7 confirmedCount=${confirmedCount} \xB7 threshold=${threshold}`
-      });
+      await scheduleBroadcast(mailer, String(req.params.slug), { scheduledAt, confirmedCount, respectRecipientTimezone }, req.actor);
       return res.json({ ok: true });
     })
   );
   r.post(
     "/broadcasts/:slug/cancel",
-    asyncHandler(async (req, res) => {
-      const b = await c.broadcasts.findOne({ slug: req.params.slug });
-      if (!b) return res.status(404).json({ error: "not_found" });
-      await c.broadcasts.updateOne({ _id: b._id }, { $set: { status: "cancelled", updatedAt: /* @__PURE__ */ new Date() } });
-      await mailer.audit({
-        actor: req.actor,
-        action: "broadcast.cancel",
-        resource: { collection: "mailer_broadcasts", id: b._id, slug: b.slug }
-      });
+    broadcastHandler(async (req, res) => {
+      await cancelBroadcast(mailer, String(req.params.slug), req.actor);
       return res.json({ ok: true });
     })
   );
@@ -8133,35 +9143,15 @@ async function computeTemplateStats(mailer, slugFilter) {
   }
   return out;
 }
-function emptyBroadcastStats() {
-  return { delivered: 0, opened: 0, clicked: 0, bounced: 0 };
-}
-async function computeBroadcastStats(mailer, idFilter) {
-  const out = /* @__PURE__ */ new Map();
-  const match = { broadcastId: { $ne: null } };
-  if (idFilter) match.broadcastId = idFilter;
-  const rows = await mailer.collections.sends.aggregate([
-    { $match: match },
-    {
-      $group: {
-        _id: "$broadcastId",
-        delivered: { $sum: { $cond: [{ $eq: ["$status", "delivered"] }, 1, 0] } },
-        opened: { $sum: { $cond: [{ $ifNull: ["$openedAt", false] }, 1, 0] } },
-        clicked: { $sum: { $cond: [{ $ifNull: ["$firstClickAt", false] }, 1, 0] } },
-        bounced: { $sum: { $cond: [{ $eq: ["$status", "bounced"] }, 1, 0] } }
+function broadcastHandler(fn) {
+  return (req, res, next) => {
+    fn(req, res, next).catch((err) => {
+      if (err instanceof BroadcastOperationError) {
+        return res.status(err.status).json({ error: err.code, message: err.message, ...err.details ?? {} });
       }
-    }
-  ]).toArray();
-  for (const row of rows) {
-    if (!row._id) continue;
-    out.set(String(row._id), {
-      delivered: row.delivered,
-      opened: row.opened,
-      clicked: row.clicked,
-      bounced: row.bounced
+      next(err);
     });
-  }
-  return out;
+  };
 }
 
 // src/server/api/wrap.ts
@@ -8538,7 +9528,16 @@ function unitToMs2(value, unit) {
 }
 
 // src/server/api/agent.ts
-var VERSION = "0.17.1" ;
+var VERSION = "0.18.0" ;
+var broadcastCountSchema = z.object({
+  recipientCap: z.number().int().positive().max(1e7).nullable().optional()
+});
+var broadcastTestSendSchema = z.object({
+  contactIds: z.array(z.string().min(1).max(256)).min(1).max(10),
+  vars: z.record(z.string(), z.unknown()).optional(),
+  /** 'queue' leaves the sends queued for the worker instead of dispatching inline. */
+  dispatch: z.enum(["now", "queue"]).optional()
+});
 var agentTagsInputSchema = z.object({
   add: z.array(z.string().min(1).max(128)).max(25).default([]),
   remove: z.array(z.string().min(1).max(128)).max(25).default([])
@@ -8803,7 +9802,7 @@ function createAgentRouter(mailer, opts) {
       }
       const now = /* @__PURE__ */ new Date();
       const publishedBy = input.publishedBy ?? actorOf(req);
-      const set = {
+      const set2 = {
         slug,
         name: input.name,
         description: input.description,
@@ -8834,7 +9833,7 @@ function createAgentRouter(mailer, opts) {
       const result = await c.templates.updateOne(
         { slug },
         {
-          $set: set,
+          $set: set2,
           $setOnInsert: {
             createdAt: now,
             stats: { sent: 0, delivered: 0, opened: 0, clicked: 0, bounced: 0, complained: 0, unsubscribed: 0, lastSentAt: null }
@@ -9216,6 +10215,152 @@ function createAgentRouter(mailer, opts) {
       res.json({ contact: { externalId: contact.externalId, email: contact.email }, removed, subscription });
     })
   );
+  router.get(
+    "/broadcasts",
+    wrap2(async (_req, res) => {
+      const docs = await c.broadcasts.find().sort({ createdAt: -1 }).limit(200).toArray();
+      const stats = await computeBroadcastStats(mailer);
+      res.json(docs.map((b) => ({ ...broadcastSummary(b), stats: stats.get(String(b._id)) ?? emptyBroadcastStats() })));
+    })
+  );
+  router.get(
+    "/broadcasts/:slug",
+    wrap2(async (req, res) => {
+      const b = await loadBroadcast(mailer, String(req.params.slug));
+      const [statsMap, statusBreakdown] = await Promise.all([
+        computeBroadcastStats(mailer, b._id),
+        broadcastStatusBreakdown(mailer, b._id)
+      ]);
+      const stats = statsMap.get(String(b._id)) ?? emptyBroadcastStats();
+      res.json({
+        broadcast: broadcastSummary(b),
+        stats,
+        statusBreakdown,
+        capProgress: capProgress(b, stats),
+        stopRules: stopRuleStatus(mailer, b, stats)
+      });
+    })
+  );
+  router.post(
+    "/broadcasts",
+    wrap2(async (req, res) => {
+      const parsed = agentCreateBroadcastSchema.safeParse(req.body ?? {});
+      if (!parsed.success) return res.status(400).json({ error: "validation_failed", message: zodMessage(parsed.error) });
+      const b = await createBroadcast(mailer, parsed.data, actorOf(req), { requireSubscribed: true, strictSegment: true });
+      res.status(201).json({ broadcast: broadcastSummary(b) });
+    })
+  );
+  router.patch(
+    "/broadcasts/:slug",
+    wrap2(async (req, res) => {
+      const parsed = agentPatchBroadcastSchema.safeParse(req.body ?? {});
+      if (!parsed.success) return res.status(400).json({ error: "validation_failed", message: zodMessage(parsed.error) });
+      const b = await patchBroadcast(mailer, String(req.params.slug), parsed.data, actorOf(req), { requireSubscribed: true, strictSegment: true });
+      res.json({ broadcast: broadcastSummary(b) });
+    })
+  );
+  router.post(
+    "/broadcasts/:slug/schedule",
+    wrap2(async (req, res) => {
+      const parsed = agentScheduleBroadcastSchema.safeParse(req.body ?? {});
+      if (!parsed.success) return res.status(400).json({ error: "validation_failed", message: zodMessage(parsed.error) });
+      const b = await scheduleBroadcast(mailer, String(req.params.slug), parsed.data, actorOf(req), {
+        requireSubscribed: true,
+        requireExactCount: true
+      });
+      res.json({ broadcast: broadcastSummary(b) });
+    })
+  );
+  router.post(
+    "/broadcasts/:slug/count",
+    wrap2(async (req, res) => {
+      const parsed = broadcastCountSchema.safeParse(req.body ?? {});
+      if (!parsed.success) return res.status(400).json({ error: "validation_failed", message: zodMessage(parsed.error) });
+      const b = await loadBroadcast(mailer, String(req.params.slug));
+      const count2 = await countRecipients(
+        mailer,
+        b,
+        void 0,
+        parsed.data.recipientCap !== void 0 ? { recipientCap: parsed.data.recipientCap } : {}
+      );
+      res.json({
+        slug: b.slug,
+        status: b.status,
+        ...count2,
+        confirmationThreshold: mailer.config.broadcastConfirmationThreshold
+      });
+    })
+  );
+  router.post(
+    "/broadcasts/:slug/test-send",
+    wrap2(async (req, res) => {
+      const parsed = broadcastTestSendSchema.safeParse(req.body ?? {});
+      if (!parsed.success) return res.status(400).json({ error: "validation_failed", message: zodMessage(parsed.error) });
+      const b = await loadBroadcast(mailer, String(req.params.slug));
+      const tpl = await loadBroadcastTemplate(mailer, b);
+      if (!tpl.body?.html && !tpl.body?.mjml) {
+        return res.status(409).json({ error: "not_published", message: `template "${tpl.slug}" has no published body` });
+      }
+      const contacts = [];
+      for (const id of parsed.data.contactIds) {
+        const contact = await loadContact(res, id);
+        if (!contact) return;
+        if (!guardTestContact(res, contact)) return;
+        contacts.push(contact);
+      }
+      const ctx = mailer.getRunnerContext();
+      const dispatchNow = parsed.data.dispatch !== "queue";
+      const sends = [];
+      for (const contact of contacts) {
+        const { sendId } = await mailer.sendOneOff({
+          templateSlug: tpl.slug,
+          externalId: contact.externalId,
+          dedupeKey: `broadcast-test:${b._id}:${contact.externalId}:${crypto2.randomUUID()}`,
+          vars: parsed.data.vars
+        });
+        const _id = new ObjectId(sendId);
+        await c.sends.updateOne({ _id }, { $set: { manualSendBy: `broadcast-test:${b.slug}` } });
+        if (dispatchNow) await dispatchSend(_id, ctx);
+        const row = await c.sends.findOne({ _id });
+        if (row) sends.push(sendSummary(row));
+      }
+      await mailer.audit({
+        actor: actorOf(req),
+        action: "agent.broadcast.test-send",
+        resource: { collection: "mailer_broadcasts", id: b._id, slug: b.slug },
+        diffSummary: `template=${tpl.slug} to=${contacts.map((x) => x.email).join(", ")} dispatch=${dispatchNow ? "now" : "queue"}`
+      });
+      res.status(201).json({ broadcast: { slug: b.slug, status: b.status }, templateSlug: tpl.slug, dispatched: dispatchNow, sends });
+    })
+  );
+  router.post(
+    "/broadcasts/:slug/pause",
+    wrap2(async (req, res) => {
+      const parsed = agentPauseBroadcastSchema.safeParse(req.body ?? {});
+      if (!parsed.success) return res.status(400).json({ error: "validation_failed", message: zodMessage(parsed.error) });
+      const out = await pauseBroadcastByOperator(mailer, String(req.params.slug), parsed.data, actorOf(req));
+      res.json({ broadcast: broadcastSummary(out.broadcast), heldSends: out.heldSends });
+    })
+  );
+  router.post(
+    "/broadcasts/:slug/resume",
+    wrap2(async (req, res) => {
+      const parsed = agentResumeBroadcastSchema.safeParse(req.body ?? {});
+      if (!parsed.success) return res.status(400).json({ error: "validation_failed", message: zodMessage(parsed.error) });
+      const b = await resumeBroadcast(mailer, String(req.params.slug), parsed.data, actorOf(req), {
+        requireSubscribed: true,
+        requireExactCount: true
+      });
+      res.json({ broadcast: broadcastSummary(b) });
+    })
+  );
+  router.post(
+    "/broadcasts/:slug/cancel",
+    wrap2(async (req, res) => {
+      const out = await cancelBroadcast(mailer, String(req.params.slug), actorOf(req));
+      res.json({ broadcast: broadcastSummary(out.broadcast), cancelledSends: out.cancelledSends });
+    })
+  );
   router.post(
     "/tick",
     wrap2(async (_req, res) => {
@@ -9305,6 +10450,9 @@ function createAgentRouter(mailer, opts) {
     if (err instanceof FlowOperationError) {
       return res.status(err.status).json({ error: err.code, message: err.message });
     }
+    if (err instanceof BroadcastOperationError) {
+      return res.status(err.status).json({ error: err.code, message: err.message, ...err.details ?? {} });
+    }
     if (err?.name === "ZodError") {
       return res.status(400).json({ error: "validation_failed", issues: err.issues });
     }
@@ -9673,6 +10821,9 @@ function runSummary(r) {
     history: r.history
   };
 }
+function zodMessage(error) {
+  return error.issues.map((i) => `${i.path.join(".") || "body"}: ${i.message}`).join("; ");
+}
 function objectOrUndefined(v) {
   return v && typeof v === "object" && !Array.isArray(v) ? v : void 0;
 }
@@ -9711,6 +10862,16 @@ var ENDPOINTS = [
   { method: "POST", path: "/contacts/:externalId/unsubscribe", summary: "Unsubscribe a test contact (marketing scope).", testContactsOnly: true },
   { method: "POST", path: "/contacts/:externalId/tags", summary: "Add or remove tags on a test contact ({add: [...], remove: [...]}), so a gated flow lets it through.", testContactsOnly: true },
   { method: "POST", path: "/contacts/:externalId/reset", summary: "Delete a test contact's runs, sends, events ({events: [names]} to narrow) and suppressions, then resubscribe. Each part can be turned off with false.", testContactsOnly: true },
+  { method: "GET", path: "/broadcasts", summary: "Every broadcast (newest first, up to 200) with its stats." },
+  { method: "GET", path: "/broadcasts/:slug", summary: "One broadcast: stats (delivered, bounced hard/soft, complained, unsubscribed, opened, clicked, with rates), a per-status count of its send rows, pause reason and cap progress." },
+  { method: "POST", path: "/broadcasts", summary: "Create a draft broadcast: {slug, name, templateSlug, segmentDefinition?, respectRecipientTimezone?}." },
+  { method: "PATCH", path: "/broadcasts/:slug", summary: "Edit a draft broadcast (name, templateSlug, segmentDefinition, respectRecipientTimezone). 409 once it has left draft." },
+  { method: "POST", path: "/broadcasts/:slug/count", summary: "The true recipient count: host filter, post-filters, suppression, minus contacts already sent to, within the cap ({recipientCap} previews another cap). Schedule wants recipientCount; resume wants recipientCount + heldSends." },
+  { method: "POST", path: "/broadcasts/:slug/schedule", summary: "Schedule a draft: {scheduledAt, confirmedCount, respectRecipientTimezone?}. 409 count_mismatch unless confirmedCount equals POST /broadcasts/:slug/count \u2192 recipientCount. The segment must be limited to subscribed contacts." },
+  { method: "POST", path: "/broadcasts/:slug/test-send", summary: `Send the broadcast's template, rendered as each of {contactIds} (test contacts only), through the real pipeline without scheduling it; not counted in the broadcast's stats. {dispatch: "queue"} to leave them queued.`, testContactsOnly: true },
+  { method: "POST", path: "/broadcasts/:slug/pause", summary: "Pause a sending broadcast by hand ({reason?}); its queued sends are held." },
+  { method: "POST", path: "/broadcasts/:slug/resume", summary: "Re-open a paused broadcast: {recipientCap?, stopRules?, confirmedCount}. Next wave: raise recipientCap (null = no cap). confirmedCount = /count recipientCount + heldSends. A stop-rule pause re-opens only when the (adjusted) rules no longer fire; a circuit-breaker pause only once the breaker is reset." },
+  { method: "POST", path: "/broadcasts/:slug/cancel", summary: "Cancel a broadcast." },
   { method: "POST", path: "/tick", summary: "Run the runner tick now (trigger scan, sweeps, outbox, webhook backlog)." },
   { method: "GET", path: "/webhooks/status", summary: "Provider webhook ingest: last event received, counts by type (24h), unprocessed backlog." },
   { method: "GET", path: "/status", summary: "One document with setup checks, health, every flow (enabled, version, watermark, gate, active runs), every template, and 24h counts." }
@@ -9951,12 +11112,15 @@ function createPublicRouter(mailer, opts = {}) {
         return;
       }
       const now = /* @__PURE__ */ new Date();
+      await mailer.collections.sends.updateOne(
+        { _id: sendId, status: "sent" },
+        { $set: { status: "delivered" } }
+      );
       await mailer.collections.sends.updateOne(
         { _id: sendId },
         {
           $set: {
-            openedAt: send.openedAt ?? now,
-            status: "delivered"
+            openedAt: send.openedAt ?? now
           },
           $inc: { openCount: 1 },
           // Per-open user agent, so `hasOpenedExcludingBots` has a signal to
@@ -10095,6 +11259,11 @@ function createPublicRouter(mailer, opts = {}) {
       }
     }
     res.status(200).type("html").send("<!doctype html><html><body><p>You are unsubscribed.</p></body></html>");
+    if (!dbError && decoded.sendId) {
+      void attributeUnsubscribeToSend(mailer.getRunnerContext(), decoded.sendId, decoded.email).catch((err) => {
+        logger.warn?.({ err, sendId: decoded.sendId }, "mailery: unsubscribe attribution failed");
+      });
+    }
   }));
   router.get("/confirm-doi/:token", wrap(logger, async (req, res) => {
     const token = req.params.token;
@@ -10426,7 +11595,7 @@ var DEDUPE_POLICIES = [
 ];
 
 // src/server/index.ts
-var VERSION2 = "0.17.1" ;
+var VERSION2 = "0.18.0" ;
 
 export { DEDUPE_POLICIES, DEFAULT_BOT_UA_RE, FLOW_STEP_KINDS, FlowOperationError, MIN_AGENT_TOKEN_LENGTH, Mailer, MongoContactAdapter, NullProvider, PREDICATE_KINDS, RESERVED_VAR_KEYS, SEGMENT_FILTER_KINDS, SendGridProvider, TRACKING_SIG_LENGTH, VERSION2 as VERSION, applyTracking, applyWebhookEvent, armFlow, compileMailyTemplate, compileTemplate, computeDeliveryTime, createAdminApiRouter, createAdminRouter, createAgentRouter, createPublicRouter, defaultFlowStep, defaultPredicate, defaultSegmentFilter, defineVars, derivePlaintext, disarmFlow, dispatchSend, drainPendingUnsubscribes, ensureIndexes, gateFlow, getCollections, isCanaryGate, predicateKind, processNewlyFiredEventTriggers, processOneRunStep, referencedPaths, renderForContact, renderTemplate, runTick, sendgridInboundParser, sha256Hex, signTrackingToken, signUnsubscribeToken, simulateFlow, stampWatermarkIfNull, sweepStrandedFlowRuns, ungateFlow, validateSenderDomain, varsJsonSchema, verifyTemplate, verifyTrackingToken, verifyUnsubscribeToken };
 //# sourceMappingURL=index.js.map