Plugins

What a plugin is, how plugins stack around a read, the order to list them in and why, and a table of every plugin the package ships.

A plugin is an object you pass to createOutbound in plugins. It can do five things: wrap every read, turn capabilities off, add methods to the instance, observe calls and HTTP requests, and rewrite webhook events. Each plugin is its own subpath (outbound-sdk/<name>), so you import only the ones you use.

Plugins follow the same boundary as the rest of the SDK. None writes to a vendor, none calls an AI model, and none stores anything on our side. A plugin that keeps state (cache, sync, failover) takes a store you supply.

Two things that look like plugins are documented elsewhere:

• combine([...]) is an adapter, not a plugin. It goes in adapter, not in plugins. See combine adapters.
• insights() is a plugin, and has its own section.

How plugins compose

Every read the SDK makes is an operation, such as campaigns.list or stats. Each plugin with a wrap function is a layer around the adapter. plugins[0] is the outermost layer: it sees the operation first and the answer last.

import { createOutbound } from "outbound-sdk";
import type { OutboundPlugin } from "outbound-sdk";
import { memory } from "outbound-sdk/memory";

import { seed } from "./seed.ts";

// A plugin that does nothing but say when an operation passes through it.
const layer = (name: string): OutboundPlugin => ({
  name,
  wrap: async (operation, next) => {
    console.log(`${name}: in  (${operation.kind})`);
    const output = await next(operation);
    console.log(`${name}: out (${output.items.length} records)`);

    return output;
  },
});

const outbound = createOutbound({
  adapter: memory({ data: seed, workspaceId: "agency" }),
  plugins: [layer("first"), layer("second"), layer("third")],
});

await outbound.campaigns.list();

console.log(outbound.plugins.map((plugin) => plugin.name));

first: in  (campaigns.list)
second: in  (campaigns.list)
third: in  (campaigns.list)
third: out (3 records)
second: out (3 records)
first: out (3 records)
[ 'first', 'second', 'third' ]

Four more rules:

• A plugin name may appear once. Listing the same plugin twice throws Invalid when the instance is built.
• Capabilities only narrow. A plugin can turn a capability off or lower its grade. Anything it tries to widen is ignored. A call that needs a capability a plugin turned off throws Unsupported before any request, and the message names the plugin.
• Methods a plugin adds are typed. createOutbound returns the instance with every plugin’s additions, so outbound.clients exists in the type only when clients() is in the list. A plugin that adds a name the instance already has throws Invalid.
• outbound.workspace(id) keeps the plugins. The scoped instance has the same plugin objects and the methods they add.

outbound.plugins lists the plugins on an instance, outermost first.

The order that matters

List plugins in this order. Each line says why.

1. redact first. It masks what every layer inside it returns, so nothing inside can hand back an unmasked record.
2. clients and identity next. They add fields to records as they pass. Outside the cache they run on every read, so a cached record is tagged by the rules you have now.
3. cache after them, so a repeat read stops there and skips everything inside it.
4. audit and tracing inside the cache. They then record only reads that did real work.
5. budget last, next to the request engine, so only requests that reach the vendor count.

import { setImmediate } from "node:timers/promises";

import { createOutbound } from "outbound-sdk";
import { audit } from "outbound-sdk/audit";
import { budget } from "outbound-sdk/budget";
import { cache } from "outbound-sdk/cache";
import { clients } from "outbound-sdk/clients";
import { memory } from "outbound-sdk/memory";
import { redact } from "outbound-sdk/redact";

import { seed } from "./seed.ts";

const audited: string[] = [];

const outbound = createOutbound({
  adapter: memory({ data: seed, workspaceId: "agency" }),
  plugins: [
    // Outermost: masks whatever the layers inside it return.
    redact(),
    // Tags records.
    clients({ rules: [{ campaignTag: "acme", client: "Acme" }] }),
    // A repeat read stops here and skips everything below.
    cache({ ttl: 60 }),
    // So this records only the reads that did real work.
    audit({
      sink: (entry) => {
        audited.push(entry.type === "call" ? entry.operation : entry.type);
      },
    }),
    // Innermost: next to the request engine.
    budget({ maxRequests: 50 }),
  ],
});

const first = await outbound.lead("lead_jane").get();
const second = await outbound.lead("lead_jane").get();

for (const lead of [first, second]) {
  console.log(
    `email ${lead.email}, client ${"client" in lead ? lead.client : "?"}`
  );
}

// The audit sink is not awaited by the read. Give its entries a turn to arrive.
await setImmediate();

console.log("audited:", audited);

email [redacted], client Acme
email [redacted], client Acme
audited: [ 'leads.get', 'campaigns.get' ]

The first read was audited as two operations: the lead, and the lead’s campaign, which clients fetched to check its tag. The second read was served by the cache and never reached the audit layer.

Other positions that matter:

Plugins that only add methods (sync, reconcile, benchmarks, exporter) have no layer, so their position does not matter. Their methods call the instance’s public API, so every layer applies to what they read.

Every plugin

The samples on these pages read one seed on the in-memory adapter: an agency workspace with three campaigns, four leads, three messages, two senders and two days of results. The in-memory adapter makes no HTTP request, so the pages for budget, audit and tracing also run Instantly’s adapter on a fetch that serves the vendor’s documented payloads from the repository.

// Made-up data for one agency workspace, "agency", that runs campaigns for
// two clients. Every sample in the Plugins section reads this.
import type { MemoryData } from "outbound-sdk/memory";

export const seed: MemoryData = {
  campaigns: [
    { id: "cmp_founders", name: "Acme: SaaS founders", tags: ["acme"] },
    { id: "cmp_agencies", name: "Globex: agency owners", tags: ["globex"] },
    { id: "cmp_ecom", name: "Ecommerce ops" },
  ],
  leads: [
    {
      campaignId: "cmp_founders",
      company: "Northwind",
      createdAt: "2026-11-09T09:00:00.000Z",
      custom: { phone: "555-0100" },
      email: "jane.doe@example.com",
      firstName: "Jane",
      id: "lead_jane",
      lastName: "Doe",
      linkedinUrl: "https://www.linkedin.com/in/jane-doe-example",
    },
    {
      campaignId: "cmp_founders",
      company: "Contoso",
      createdAt: "2026-11-10T09:00:00.000Z",
      email: "sam.lee@example.com",
      firstName: "Sam",
      id: "lead_sam",
      lastName: "Lee",
    },
    {
      campaignId: "cmp_agencies",
      company: "Fabrikam",
      createdAt: "2026-11-12T09:00:00.000Z",
      email: "priya.patel@example.com",
      firstName: "Priya",
      id: "lead_priya",
      lastName: "Patel",
    },
    {
      campaignId: "cmp_ecom",
      company: "Tailspin",
      createdAt: "2026-11-13T09:00:00.000Z",
      email: "omar.haddad@example.com",
      firstName: "Omar",
      id: "lead_omar",
      lastName: "Haddad",
    },
  ],
  messages: [
    {
      body: "Hi Jane, are you still hiring SDRs?",
      campaignId: "cmp_founders",
      direction: "out",
      id: "msg_1",
      leadId: "lead_jane",
      senderId: "snd_ana",
      sentAt: "2026-11-10T10:00:00.000Z",
      subject: "Quick question",
    },
    {
      body: "Yes. Send me some times for next week.",
      campaignId: "cmp_founders",
      category: "positive",
      direction: "in",
      id: "msg_2",
      leadId: "lead_jane",
      sentAt: "2026-11-11T08:30:00.000Z",
      subject: "Re: Quick question",
    },
    {
      body: "Hi Priya, how do you report to clients today?",
      campaignId: "cmp_agencies",
      direction: "out",
      id: "msg_3",
      leadId: "lead_priya",
      senderId: "snd_ana",
      sentAt: "2026-11-12T10:00:00.000Z",
      subject: "Client reporting",
    },
  ],
  senders: [
    { address: "ana@agency.example.com", id: "snd_ana", name: "Ana Ruiz" },
    {
      address: "ben@agency.example.com",
      id: "snd_ben",
      name: "Ben Cole",
      status: "disconnected",
    },
  ],
  stats: [
    // Acme: 200 sent, 12 replies, 2 bounces over two days.
    {
      campaignId: "cmp_founders",
      counts: { bounced: 1, replied: 6, sent: 100 },
      date: "2026-11-12",
    },
    {
      campaignId: "cmp_founders",
      counts: { bounced: 1, replied: 6, sent: 100 },
      date: "2026-11-13",
    },
    // Globex: 400 sent, 8 replies, 4 bounces.
    {
      campaignId: "cmp_agencies",
      counts: { bounced: 2, replied: 4, sent: 200 },
      date: "2026-11-12",
    },
    {
      campaignId: "cmp_agencies",
      counts: { bounced: 2, replied: 4, sent: 200 },
      date: "2026-11-13",
    },
    // No client: nothing on the 11th, then 200 sent, 2 replies, 18 bounces.
    { campaignId: "cmp_ecom", counts: { sent: 0 }, date: "2026-11-11" },
    {
      campaignId: "cmp_ecom",
      counts: { bounced: 9, replied: 1, sent: 100 },
      date: "2026-11-12",
    },
    {
      campaignId: "cmp_ecom",
      counts: { bounced: 9, replied: 1, sent: 100 },
      date: "2026-11-13",
    },
  ],
};

Several tools, several clients

Cost and visibility

Keeping a copy in step

Context, files and bad days

To write your own, see writing a plugin.