Records

Every record the SDK returns and each of its fields, the six fields all records share, how refs are built and parsed, the exported Zod schemas, and why a missing value is null and never 0.

Every adapter maps its vendor’s data onto the same records. A Campaign from Instantly and a Campaign from HeyReach have the same fields with the same meaning. Each record type is exported from outbound-sdk as a TypeScript type, and most have an exported Zod schema.

Which fields a vendor can fill is an adapter fact: see the adapter pages. A field a vendor cannot fill is null.

Fields every record has

MetricRow is the exception: it has provider, workspaceId and schemaVersion, and a scopeRef in place of its own ref.

raw is the vendor’s data unmapped, so it holds whatever personal data the vendor sent. The redact plugin removes it.

Refs

import {
  campaignSchema,
  createOutbound,
  makeRef,
  parseRef,
  SCHEMA_VERSION,
} from "outbound-sdk";
import { demoData, memory } from "outbound-sdk/memory";

const outbound = createOutbound({
  adapter: memory({ data: demoData(), workspaceId: "acme" }),
});

const campaign = await outbound.campaigns.get("cmp_founders");

// The six fields every record carries.
console.log(campaign.provider, campaign.workspaceId, campaign.sourceId);

console.log(campaign.ref);

console.log(campaign.schemaVersion === SCHEMA_VERSION, campaign.raw);

// A ref is three parts joined with colons.
console.log(makeRef("instantly", "acme", "0193-ab"));

console.log(parseRef(campaign.ref));

console.log(parseRef("not-a-ref"));

// The ref and the vendor's own id name the same record.
const again = await outbound.campaigns.get(campaign.ref);

console.log(again.sourceId);

// The exported schemas check a record that came from somewhere else,
// for example your own database.
console.log(campaignSchema.safeParse(campaign).success);

console.log(campaignSchema.safeParse({ name: "No ref" }).success);

memory acme cmp_founders
memory:acme:cmp_founders
true null
instantly:acme:0193-ab
{ provider: 'memory', sourceId: 'cmp_founders', workspaceId: 'acme' }
null
cmp_founders
true
false

• A ref names one record on one credential. Two clients on the same vendor, or one client on two vendors, can never be confused, because the workspace label and the provider are in the ref.
• Wherever the SDK takes an id, it takes a ref. On an instance with one adapter both work. A ref from another workspace is refused with Invalid.
• On a combined instance, use the ref. A bare id cannot say which adapter it belongs to. See troubleshooting.
• Fields that point at another record hold its ref, not its id: campaignRef, leadRef, senderRef, campaignRefs, scopeRef.
• Store the ref. It is the key to use in your own database.

makeRef(provider, workspaceId, sourceId) builds one. parseRef(ref) returns { provider, workspaceId, sourceId }, or null for a string that is not a ref. A vendor id may itself contain colons: everything after the second colon is the sourceId. A workspaceId cannot be empty or contain a colon, and an adapter constructed with one throws Invalid.

Null is not zero

A value the vendor does not report is null. It is never 0, "" or false.

import { computeRates, createOutbound } from "outbound-sdk";
import { memory } from "outbound-sdk/memory";

// One day of results. The vendor reported sends, replies and bounces, and
// said nothing about opens.
const outbound = createOutbound({
  adapter: memory({
    data: {
      campaigns: [{ id: "cmp_1" }],
      senders: [{ id: "mbx_1" }],
      stats: [
        {
          campaignId: "cmp_1",
          counts: { bounced: 0, replied: 6, sent: 200 },
          date: "2026-11-10",
        },
      ],
    },
  }),
});

const { rows } = await outbound.campaign("cmp_1").stats();
const [row] = rows;

if (row !== undefined) {
  // 0 was reported. null was not reported.
  console.log("bounced:", row.bounced, "| opened:", row.opened);

  const rates = computeRates(row);

  console.log("bounce rate:", rates.bounceRate);
  console.log("open rate:", rates.openRate);
  console.log("reply rate:", rates.replyRate);
}

// Fields work the same way.
const sender = await outbound.sender("mbx_1").get();

console.log(sender.address, sender.dailyLimit, sender.warmup);

bounced: 0 | opened: null
bounce rate: { basis: 'sent', value: 0 }
open rate: { basis: null, value: null }
reply rate: { basis: 'sent', value: 0.03 }
null null null

bounced: 0 means the vendor counted bounces and found none. opened: null means the vendor gave no open count: tracking was off, or its API does not report it. A rate built on a missing count is null too. Print “not reported”, not a zero, and do not add null counts up as zeros. sumCounts from outbound-sdk adds rows and keeps a count null unless at least one row reports it.

Arrays are the exception. tags, issues, events and campaignRefs are empty arrays when there is nothing to report, and custom is an empty object.

Campaign

Sequence

A campaign’s steps. Returned by campaign(id).sequence() and campaign(id).subsequences.

SequenceStep:

SequenceVariant:

Sender

A mailbox or a LinkedIn seat.

SenderHealth

What the vendor knows about a sender’s deliverability. Its sourceId is the sender’s id.

Lead

LeadEngagement, what a lead did with the campaign’s messages as the vendor counts it:

A lead is a person in one campaign. The same person in two campaigns is two Lead records. The identity plugin links them without merging them.

Message

One message sent or received.

Reply

A received message with a category. It has every Message field, direction is always "in", and it adds:

MetricRow

One row of counts. Every count is a number or null. Its fields are listed on the stats page.

CampaignSettings

How a campaign is set up to send. Its sourceId is the campaign’s id.

SendingWindow:

LeadList

A saved list that campaigns draw from.

Tag

BlockEntry

One address, domain or profile the account never contacts.

WebhookSubscription

A webhook registered with the vendor. The SDK lists them. It does not create or change them.

Workspace

Schemas

Each record is defined once as a Zod schema and its TypeScript type is inferred from it. The SDK checks every record against its schema before returning it. A record that does not match fails the call with a Provider error naming the field, so a malformed record never reaches your code.

The schemas are exported for checking records that come from somewhere else, such as your own database or a queue:

SequenceStep, SequenceVariant, LeadEngagement and SendingWindow are exported as types only. Entity is the union of every record a list or get call returns.

SCHEMA_VERSION is 1. Every record carries it as schemaVersion, so data you stored can say which shape it was written in.