alerts

Check fixed rules on the records each read returns and call your own notifier with what fired, using the four built-in rules or rules you write.

alerts({ rules, notify }) from outbound-sdk/alerts checks every record a read returns against a list of rules and calls your notify function with the alerts that fired. A rule is arithmetic on one record the read returned: a rate against a threshold, a status against a value. No model is involved. The plugin fetches nothing, schedules nothing and remembers nothing: rules run only on the reads you make.

Sample

Runs on the shared seed, where one campaign has 18 bounces in 200 sends and one sender is disconnected.

import { createOutbound } from "outbound-sdk";
import {
  alerts,
  bounceRateAbove,
  noSends,
  replyRateBelow,
  senderNotActive,
} from "outbound-sdk/alerts";
import type { Alert, AlertRule } from "outbound-sdk/alerts";
import { memory } from "outbound-sdk/memory";

import { seed } from "../plugins-index/seed.ts";

// A rule of your own: any function from a record to an alert or null.
// This one fires for a campaign that carries no tag.
const untaggedCampaign: AlertRule = {
  check: (record) =>
    "channel" in record && "tags" in record && record.tags.length === 0
      ? {
          message: `${record.name} has no tag, so no client rule can match it`,
          rule: "untagged-campaign",
          subject: record.ref,
          threshold: 1,
          value: 0,
        }
      : null,
  name: "untagged-campaign",
};

const fired: Alert[] = [];

const outbound = createOutbound({
  adapter: memory({ data: seed, workspaceId: "agency" }),
  plugins: [
    alerts({
      // Post to Slack, page someone, write a row. Here: keep them.
      notify: (found) => {
        fired.push(...found);
      },
      rules: [
        bounceRateAbove(0.05),
        replyRateBelow(0.02),
        senderNotActive(),
        noSends(),
        untaggedCampaign,
      ],
    }),
  ],
});

// Rules run on whatever these reads return. Nothing else is fetched.
for await (const campaign of outbound.campaigns.listAll()) {
  await outbound.campaign(campaign.ref).stats({
    from: "2026-11-12",
    to: "2026-11-13",
  });
}

await outbound.senders.list();

await outbound.campaign("cmp_ecom").stats({
  by: "day",
  from: "2026-11-11",
  to: "2026-11-13",
});

for (const alert of fired) {
  console.log(`[${alert.rule}] ${alert.subject}: ${alert.message}`);
}

// evaluate() checks records you already hold, and does not call notify.
const page = await outbound.senders.list();
const notified = fired.length;
const found = outbound.alerts.evaluate(page.items);

console.log(
  "\nevaluate:",
  found.map((alert) => alert.rule)
);

console.log("notify called by evaluate:", fired.length > notified);

[untagged-campaign] memory:agency:cmp_ecom: Ecommerce ops has no tag, so no client rule can match it
[bounce-rate-above] memory:agency:cmp_ecom: Bounce rate is 9.0%, above 5.0%
[reply-rate-below] memory:agency:cmp_ecom: Reply rate is 1.0%, below 2.0%
[sender-not-active] memory:agency:snd_ben: Sender is disconnected
[no-sends] memory:agency:cmp_ecom: Nothing was sent on 2026-11-11
[bounce-rate-above] memory:agency:cmp_ecom: Bounce rate is 9.0%, above 5.0%
[reply-rate-below] memory:agency:cmp_ecom: Reply rate is 1.0%, below 2.0%
[bounce-rate-above] memory:agency:cmp_ecom: Bounce rate is 9.0%, above 5.0%
[reply-rate-below] memory:agency:cmp_ecom: Reply rate is 1.0%, below 2.0%

evaluate: [ 'sender-not-active' ]
notify called by evaluate: false

The bounce and reply alerts appear three times: once for the two-day total, and once for each day of the by-day read, which is a separate read returning separate rows. By default nothing removes repeats. Pass dedupe to be told once per rule and subject.

Options

Built-in rules

Both rate rules skip a row with fewer sends than minSent (default 50), and a row whose rate is null because the vendor did not report a count. A missing count never fires a rule.

noSends() needs the vendor to return a row for the silent day. A vendor that leaves empty days out of its daily stats gives it nothing to check.

Alerts and your own rules

An Alert is:

An AlertRule is { name, check }, where check(record) returns an Alert or null. It receives every kind of record the instance returns, so it starts by telling them apart, as untaggedCampaign does in the sample. A rule sees one record at a time. Anything that needs two records, or a change since last week, is not a rule: see insights.

What it adds

Use evaluate to check records you already hold, or to test a rule.

What it changes

It changes no capability, no record and nothing in meta. Records pass through untouched.

With other plugins

• Inside cache, rules run once per real read. Before cache, they run on every read, cache hits included.
• Listed after redact, rules see unmasked records. An alert message you build from a lead’s fields carries them unmasked to your notifier.
• A stats row served stale by failover fires the same alerts as a fresh one. The rule cannot see meta.

When it fails

import { createOutbound } from "outbound-sdk";
import { alerts, bounceRateAbove, senderNotActive } from "outbound-sdk/alerts";
import type { Alert } from "outbound-sdk/alerts";
import { memory } from "outbound-sdk/memory";

import { seed } from "../plugins-index/seed.ts";

// 1. A notifier that fails cannot fail the read. The failure is dropped.
const outbound = createOutbound({
  adapter: memory({ data: seed, workspaceId: "agency" }),
  plugins: [
    alerts({
      notify: () => Promise.reject(new Error("Slack is down")),
      rules: [senderNotActive()],
    }),
  ],
});

const senders = await outbound.senders.list();

console.log("read succeeded:", senders.items.length, "senders");

// 2. A rate on a handful of sends is noise, so small rows are skipped.
//    One day of the ecommerce campaign is 100 sends and 9 bounces.
const notified: Alert[] = [];

const strict = createOutbound({
  adapter: memory({ data: seed, workspaceId: "agency" }),
  plugins: [
    alerts({
      notify: (found) => {
        notified.push(...found);
      },
      rules: [bounceRateAbove(0.05, { minSent: 150 })],
    }),
  ],
});

const day = await strict.campaign("cmp_ecom").stats({
  from: "2026-11-13",
  to: "2026-11-13",
});

console.log(
  "sent",
  day.rows[0]?.sent,
  "-> alerts:",
  strict.alerts.evaluate(day.rows).length
);

const both = await strict.campaign("cmp_ecom").stats({
  from: "2026-11-12",
  to: "2026-11-13",
});

console.log(
  "sent",
  both.rows[0]?.sent,
  "-> alerts:",
  strict.alerts.evaluate(both.rows).length
);

read succeeded: 2 senders
sent 100 -> alerts: 0
sent 200 -> alerts: 1