# outbound-sdk > One small, typed, read-only TypeScript API over outbound sending tools: Instantly, Smartlead and HeyReach. Reach for outbound-sdk when a TypeScript or JavaScript project needs to read campaigns, sequences, leads, replies, senders and results from Instantly, Smartlead or HeyReach through one API. It is read-only: no method sends, pauses, edits or deletes anything in a vendor tool (the raw client can send other requests only when the caller sets allowWrites), it stores nothing and it runs no AI model. It is a preview: the package is not published to npm yet and its repository is private, so `npm install outbound-sdk` does not work today. Instantly and HeyReach are beta (read-only runs against one live workspace each); Smartlead is unverified (tested offline against its public documentation). Construct `createOutbound({ adapter: instantly() })` and call `outbound.campaigns.listAll()`, `outbound.campaign(id).stats()` and the rest; `outbound-sdk/insights` adds 26 computed answers, and `outbound mcp` serves the same reads to an agent. The code samples on this site are files the test suite runs on an in-memory adapter; none was run against a vendor. ## Docs - [outbound-sdk](https://outbound-sdk.dev/): One small, typed, read-only TypeScript API over outbound sending tools. Read campaigns, sequences, leads, replies, senders and results from Instantly, Smartlead and HeyReach with the same code. ## Docs - [Introduction](https://outbound-sdk.dev/docs): outbound-sdk is one read-only TypeScript API over Instantly, Smartlead and HeyReach, with a typed catalog of each vendor's own reads, 26 computed insights, plugins, AI tools, a CLI and an MCP server. - [Installation](https://outbound-sdk.dev/docs/installation): outbound-sdk is not published to npm yet. How to build and install it from the repository today, what it needs at run time, and what will change at the first release. - [Usage](https://outbound-sdk.dev/docs/usage): Construct an Outbound instance with an adapter, list and read records, follow a campaign down to its sequence, stats and leads, and handle the one error class. - [What is verified](https://outbound-sdk.dev/docs/status): What has been run against a live vendor account and what has not, per adapter, with the dates. Read this before relying on a number from outbound-sdk. - [How the samples are run](https://outbound-sdk.dev/docs/samples): Every code sample on this site is a file in the repository that the test suite runs on the in-memory adapter. What that proves, and what it does not. - [Capabilities](https://outbound-sdk.dev/docs/capabilities): Every adapter declares what it can read as a flat map. What each key gates, what the grades mean, how to branch on the map, and how an adapter option or a plugin changes it. - [Native catalog](https://outbound-sdk.dev/docs/native): Call any read a vendor offers that has no normalized form, by name and with typed parameters, and know what comes back, what it costs and when it is refused. - [Rate limits](https://outbound-sdk.dev/docs/rate-limits): How outbound-sdk keeps every request inside each vendor's published limits, what it does on a 429, what was measured on live accounts, and how several processes share one budget. - [Retries, timeouts and budgets](https://outbound-sdk.dev/docs/retries): What the SDK retries on its own and what it never retries, how long it waits between attempts, and the five options that bound a call - retries, timeout, deadline, maxRequests and signal. - [Troubleshooting](https://outbound-sdk.dev/docs/troubleshooting): The errors a new user hits first, each with the exact message the SDK prints, what caused it and what to change. ### Adapters - [Adapters](https://outbound-sdk.dev/docs/adapters): What an adapter is, the four that ship, what each can and cannot do in one table checked against the code, and how much of each vendor's API is covered. - [Instantly adapter](https://outbound-sdk.dev/docs/adapters/instantly): Construct the Instantly adapter, know which key it needs, what it can and cannot read, what its reads cost in requests, the rate limits it keeps to and the assumptions it has not confirmed. - [Smartlead adapter](https://outbound-sdk.dev/docs/adapters/smartlead): Construct the Smartlead adapter, know which key it needs, what it can and cannot read, what its reads cost in requests, the rate limits it keeps to and the assumptions it has not confirmed. - [HeyReach adapter](https://outbound-sdk.dev/docs/adapters/heyreach): Construct the HeyReach adapter, know which key it needs, what it can and cannot read, what its reads cost in requests, the rate limits it keeps to and the assumptions it has not confirmed. - [In-memory adapter](https://outbound-sdk.dev/docs/adapters/memory): Run the whole SDK on plain data with no key and no network, seed every record type, limit it to what a real vendor declares, and know where it differs from a vendor. - [Combine adapters](https://outbound-sdk.dev/docs/adapters/combine): Put several adapters or several keys behind one instance, and know what the combined instance promises, how lookups are routed, and what it cannot do. ### Coverage - [Coverage](https://outbound-sdk.dev/docs/coverage): How every endpoint in each vendor's public API reference is reached by outbound-sdk, with the counts per vendor and the rules the per-vendor tables follow. - [Instantly coverage](https://outbound-sdk.dev/docs/coverage/instantly): Every endpoint in Instantly's API V2 reference and how outbound-sdk reaches it: a normalized read, a native read, excluded with a reason, or a write. - [Smartlead coverage](https://outbound-sdk.dev/docs/coverage/smartlead): Every endpoint in Smartlead's API reference and how outbound-sdk reaches it: a normalized read, a native read, excluded with a reason, or a write. - [HeyReach coverage](https://outbound-sdk.dev/docs/coverage/heyreach): Every endpoint in HeyReach's public API reference and how outbound-sdk reaches it: a normalized read, a native read, excluded with a reason, or a write. ### API reference - [API reference](https://outbound-sdk.dev/docs/api): Every option, collection, handle, method and property of an Outbound instance on one page, each linked to the page that documents it. - [Collections](https://outbound-sdk.dev/docs/api/collections): The five read methods every collection shares, the filters each collection takes and the capability each filter needs, lookups by email or profile, message bodies, and bulk reads where a missing record is data. - [Handles](https://outbound-sdk.dev/docs/api/handles): What campaign(id), sender(id), lead(id), list(id) and thread(id) give you, what each method returns, and the capability each one needs. - [Records](https://outbound-sdk.dev/docs/api/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. - [Stats](https://outbound-sdk.dev/docs/api/stats): How to read counts for a workspace, a campaign, a campaign's steps or a sender, as one total or one row per day, and how the six rates are computed from those counts. - [Results and meta](https://outbound-sdk.dev/docs/api/results): The meta object on every result says how the answer was obtained, when, at what cost and whether it is whole. What each field means and how to use it to decide whether to trust an answer. - [Pagination](https://outbound-sdk.dev/docs/api/pagination): Read one page with a cursor or walk every page with listAll, cap a walk with max, and resume a walk after a crash from a saved cursor without skipping a record. - [Errors](https://outbound-sdk.dev/docs/api/errors): The one error class the SDK throws, its six codes with when each is thrown and whether it is retried, the fields that say what to do next, and what is removed from every message. - [Hooks](https://outbound-sdk.dev/docs/api/hooks): Five functions that observe every call, HTTP request, retry, throttle wait and failure, with the fields each one receives. A hook can watch a call but cannot fail it. - [Raw requests](https://outbound-sdk.dev/docs/api/raw): outbound.raw sends a request to the vendor's own API by path, through the same rate budget and retries. It is refused for anything that is not a known read unless you turn writes on. ### Insights - [Insights](https://outbound-sdk.dev/docs/insights): The 26 computed answers in outbound-sdk/insights, what every answer carries, how inputs and capabilities are checked, and how to run one by name, as an agent tool, from the command line, or define your own. - [People and account insights](https://outbound-sdk.dev/docs/insights/people): Reference for the seven insights about people (personSummary, accountSummary, leadCollisions, suppressionCheck, droppedReplies, hotLeads, personalizationGaps), with every input, what the answer holds and a sample that runs. - [Copy and sequence insights](https://outbound-sdk.dev/docs/insights/copy): Reference for the five insights about copy (stepFunnel, variantTest, copyAudit, copyReuse, replyTiming), with every input, what the answer holds and a sample that runs. - [Sender and deliverability insights](https://outbound-sdk.dev/docs/insights/senders): Reference for the six insights about senders (domainHealth, senderCapacity, bounceWatch, warmupReadiness, senderLoad, settingsAudit), with every input, what the answer holds and a sample that runs. - [Campaign operations and reporting insights](https://outbound-sdk.dev/docs/insights/operations): Reference for the eight insights about campaign results (campaignDiagnosis, pipelineForecast, anomalies, periodComparison, campaignRanking, channelMix, tagRollup, clientReport), with every input, what the answer holds and a sample that runs. ### Plugins - [Plugins](https://outbound-sdk.dev/docs/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. - [clients](https://outbound-sdk.dev/docs/plugins/clients): Tag every record with the client it belongs to, by workspace or by rules on provider, workspace, campaign tag, name or ref, and add up results per client. - [identity](https://outbound-sdk.dev/docs/plugins/identity): Tag every lead with person keys built from exact identifiers, and look one person up across tools with every record and one timeline. - [redact](https://outbound-sdk.dev/docs/plugins/redact): Mask emails, names, companies, LinkedIn URLs, custom fields, subjects and bodies in everything an instance returns, and know exactly which fields it does not touch. - [cache](https://outbound-sdk.dev/docs/plugins/cache): Serve a repeat read from a store for a set number of seconds, with the store interface, a custom store, and what a cached answer says about itself. - [budget](https://outbound-sdk.dev/docs/plugins/budget): Cap the vendor requests one call or one whole run may spend, read what is left, and see what a call looks like when it hits the cap. - [audit](https://outbound-sdk.dev/docs/plugins/audit): Hand every operation's duration, request count and throttle time, and optionally every HTTP request, to a sink of your own, with no record data in the entries. - [tracing](https://outbound-sdk.dev/docs/plugins/tracing): Emit one OpenTelemetry span per SDK operation and one per HTTP request, with the span names and attributes the plugin sets. - [sync](https://outbound-sdk.dev/docs/plugins/sync): Walk a collection page by page into your own database, resume where a run stopped, and ask only for records newer than the last finished run, with checkpoints in a store you supply. - [reconcile](https://outbound-sdk.dev/docs/plugins/reconcile): Compare the webhook events you received and the refs you hold with what the vendor lists, and get a report of what is missing, unmatched, late, deleted or new. - [alerts](https://outbound-sdk.dev/docs/plugins/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. - [benchmarks](https://outbound-sdk.dev/docs/plugins/benchmarks): Put a campaign's reply, bounce, open and other rates beside its own workspace's over the same dates, as a value, a baseline and a ratio. - [fixtures](https://outbound-sdk.dev/docs/plugins/fixtures): Record an instance's answers to files in a folder you choose, with personal data replaced by numbered placeholders, and replay them without calling the vendor. - [exporter](https://outbound-sdk.dev/docs/plugins/exporter): Stream every record of a listing to a CSV or JSON Lines file as pages arrive, or to a writer of your own for Parquet, DuckDB or anything else. - [failover](https://outbound-sdk.dev/docs/plugins/failover): Serve the last good answer to a read, marked stale with its original fetch time, when the vendor is down or rate limiting, from a store you supply. - [Writing a plugin](https://outbound-sdk.dev/docs/plugins/writing-a-plugin): The plugin contract (wrap, capabilities, extend, hooks and event), a small working plugin with typed methods, and the rules a plugin has to follow. ### AI tools - [AI tools](https://outbound-sdk.dev/docs/tools): Twelve read-only tools an agent can call to ask about campaigns, senders, replies and leads, what each one needs, and what a tool returns when it cannot answer. - [OpenAI SDK tools](https://outbound-sdk.dev/docs/tools/openai): The outbound tools as OpenAI function definitions for the Responses and Chat Completions APIs, with one function that runs a call from the model and returns the string to send back. - [AI SDK tools](https://outbound-sdk.dev/docs/tools/ai-sdk): The outbound tools as a tool set for the AI SDK, keyed by tool name and ready to pass to generateText or streamText. - [Claude Agent SDK tools](https://outbound-sdk.dev/docs/tools/claude-agent): The outbound tools as an in-process MCP server for the Claude Agent SDK, with the list of tool names to pre-approve. - [Untrusted content in tool results](https://outbound-sdk.dev/docs/tools/untrusted-content): How the tools handle text a prospect wrote, so that a model reading replies sees it as data. What the SDK does, and what it cannot do for you. ### CLI - [The outbound CLI](https://outbound-sdk.dev/docs/cli): The outbound command reads campaigns, senders, leads, replies and stats from the terminal and prints JSON. How it picks an adapter, what it prints, and how it reports failure. - [CLI commands](https://outbound-sdk.dev/docs/cli/commands): Every outbound command and flag, each with a real invocation on the demo data and the output it printed. - [outbound mcp](https://outbound-sdk.dev/docs/cli/mcp): A local Model Context Protocol server on stdio that serves the read-only tools and insights to an agent client. What it implements, how to configure a client, and where the keys live. ### Webhooks - [Webhooks](https://outbound-sdk.dev/docs/webhooks): Turn a webhook from Instantly, Smartlead or HeyReach into one normalized event shape with a single function, and know what an event can and cannot tell you. - [Verifying a webhook](https://outbound-sdk.dev/docs/webhooks/verification): How parse checks that a webhook came from your vendor, per vendor, where the secret goes, what a failed check throws, and what happens when you pass no secret. - [Webhook events](https://outbound-sdk.dev/docs/webhooks/events): Which vendor event becomes which normalized type, how event ids stay stable when a vendor delivers twice, and how to drop events you already handled. ## Guides - [Guides](https://outbound-sdk.dev/guides): Complete tasks with outbound-sdk, end to end. Each guide has one outcome, code that the test suite runs, the output it printed and the failure cases. - [Build a weekly client report an agency can send, from one call](https://outbound-sdk.dev/guides/weekly-client-report): One function that turns a client's campaigns into a plain-text weekly report with the change from last week, the best campaigns and a to-do list, plus what it does when a vendor cannot answer. - [Find why one campaign is underperforming](https://outbound-sdk.dev/guides/diagnose-campaign): One function that runs a fixed list of checks on a campaign and returns the findings most serious first, with the days that broke from its own trend and its rates beside the rest of the workspace. - [Find the campaigns about to run out of leads](https://outbound-sdk.dev/guides/lead-runway): One function that forecasts every active campaign, sorts them by days of leads left and flags the ones under your threshold, with what the loop costs in vendor requests and what the estimate assumes. - [Tell whether an A/B variant is ahead by more than chance](https://outbound-sdk.dev/guides/ab-test-winner): One function that reads a campaign's step stats and says, for each step with two or more variants, whether the leader's gap is larger than chance would give, plus which step the replies come from. - [See every campaign one person is in, across an email tool and a LinkedIn tool](https://outbound-sdk.dev/guides/person-across-email-and-linkedin): One function that takes an email address or a LinkedIn profile URL and returns each campaign the person is in on every tool, with messages sent and replies per channel. Records are linked by exact identifier only. - [See everyone you have contacted at one company before a call, from its domain](https://outbound-sdk.dev/guides/account-brief): One function that takes a company domain and returns each person at it across campaigns and tools, with who replied, who the vendor marked interested and who replied last. People are matched by exact email domain only. - [List the replies nobody answered, longest waiting first, from a scheduled job](https://outbound-sdk.dev/guides/unanswered-replies): One function that reads recent replies, checks each conversation for a message sent afterwards, and returns the ones still waiting as text, plus what it could not check. It lists replies and sends nothing. - [Build a morning list of who to call first, with the reason for each rank](https://outbound-sdk.dev/guides/hot-leads-call-list): One function that ranks leads by a score built from the vendor's interest label, replies, clicks, opens and how recent the last reply is, and prints each score with its parts. It is a ranking you can check, not a prediction. - [Find people in two campaigns at once, and leads that are on a block list](https://outbound-sdk.dev/guides/double-contacted-leads): Two functions, one that lists each person who is in two or more campaigns inside a tool or across tools, and one that lists leads sitting in campaigns although a block list holds their address, domain or profile. Both report; neither removes anyone. - [Audit a campaign's copy, merge variables and settings before it launches](https://outbound-sdk.dev/guides/pre-launch-audit): One function that lists what is wrong with a campaign's copy, which leads would get a blank merge variable, and which settings are risky, as a report you read before you press launch. - [Check domain health and bounces on a schedule, and call your notifier](https://outbound-sdk.dev/guides/deliverability-check): One function that reads sender health and bounce rates and returns a summary, wired to the alerts plugin so your own notifier is called when a read crosses a rule. You schedule it; nothing runs in between. - [Decide whether your senders can carry another campaign](https://outbound-sdk.dev/guides/sender-capacity): One function that adds up what your active senders can send a day, subtracts what the running campaigns already ask for, and lists the senders and campaigns that make the headline number too generous. - [Let an MCP client such as Claude Code or Cursor read your campaigns over a local MCP server](https://outbound-sdk.dev/guides/mcp-server): A local, read-only MCP server that an agent client starts as a command, the exact messages it exchanges, and what to decide about keys and reply text before you connect it. - [Give your agent tools that answer questions about campaigns](https://outbound-sdk.dev/guides/agent-tools): A set of read-only tools your own agent can call, in the shapes the OpenAI SDK, the AI SDK and the Claude Agent SDK take, with recorded tool calls and the failures a model will see. - [Hand reply text to a model with people's details masked and the text marked untrusted](https://outbound-sdk.dev/guides/reply-text-for-llm): Replies read with the sender's name, address and company masked or hashed, and the reply text cut short and wrapped as untrusted content. Plus exactly what that does and does not protect against. - [Keep a copy of campaigns, leads and replies in your database](https://outbound-sdk.dev/guides/sync-to-database): A scheduled job that upserts campaigns, leads and replies into your own tables, asks only for what is new where the vendor can filter by date, and restarts on the page it was writing after a crash. - [Export every lead or reply to CSV, JSON Lines or your own format](https://outbound-sdk.dev/guides/export-leads): A function that streams every lead to a CSV file, replies to JSON Lines, and any listing to a writer of your own, plus a walk you can resume when a long export dies part-way. - [Receive vendor webhooks once each, and list the ones that never arrived](https://outbound-sdk.dev/guides/webhooks-and-reconcile): A webhook endpoint that rejects forged requests and drops redeliveries, with a dedupe store in your own database, and a scheduled check that reports messages the vendor lists but no webhook announced. - [Read every client's outbound data through one instance](https://outbound-sdk.dev/guides/run-many-clients): One instance over every client key, scoped to a single client when you need it, with per-client totals, separate rate budgets and rules for a workspace that holds several clients. - [Write one function that runs on Instantly, Smartlead and HeyReach](https://outbound-sdk.dev/guides/portable-code): A function that reads outbound.capabilities before each call, says what a vendor cannot serve, and reports how each answer was produced, run as each vendor with the output recorded. - [Read data only one vendor has, through the native catalog](https://outbound-sdk.dev/guides/native-reads): List a vendor's own reads, call one with typed parameters or by a name learned at run time, reach it on a combined instance, and see what is refused, with requests and responses recorded offline. - [Share one rate budget between workers with Redis](https://outbound-sdk.dev/guides/shared-rate-budget): Several processes on one vendor key spend one rate budget instead of one each, using the Redis store that ships with outbound-sdk and the Redis client you already have. - [Answer reads from the last good answer when a vendor is down or rate limiting](https://outbound-sdk.dev/guides/vendor-outage): An instance that serves repeat reads from a cache, caps what it spends, and returns the last successful answer marked stale when the vendor fails, with the cases where it refuses to. - [Test code that reads outbound data without a vendor key](https://outbound-sdk.dev/guides/test-without-a-key): Tests for your own code that run on the in-memory adapter with a seed you write, covering unsupported calls, vendor failures, paging and recorded answers, plus what the in-memory adapter does not tell you. ## Agent skills - [outbound-sdk](https://outbound-sdk.dev/.well-known/agent-skills/outbound-sdk/SKILL.md): Read the outbound-sdk docs instead of answering from memory. One small, typed, read-only TypeScript API over outbound sending tools: Instantly, Smartlead and HeyReach. Use when a task involves outbound-sdk: how it works, how to set it up or configure it, or its API. ## Agent resources - [llms-full.txt](https://outbound-sdk.dev/llms-full.txt): The full Markdown of every page in one file. - [Page Markdown](https://outbound-sdk.dev/index.md): Append `.md` to any page URL to fetch that page as raw Markdown. - [JSON API](https://outbound-sdk.dev/api/docs/pages.json): Page index of the JSON docs API; each entry links the page's JSON and Markdown forms. Described by the OpenAPI document at https://outbound-sdk.dev/openapi.json. - [MCP server](https://outbound-sdk.dev/mcp): Streamable HTTP Model Context Protocol server with search_docs, get_page, list_pages, and get_navigation tools, plus every page as a resource. Discovery document: https://outbound-sdk.dev/.well-known/mcp.json - [Agent skills](https://outbound-sdk.dev/.well-known/agent-skills/index.json): Agent Skills discovery index of the skills this site publishes. - [API catalog](https://outbound-sdk.dev/.well-known/api-catalog): RFC 9727 linkset of the APIs documented here. - [AI catalog](https://outbound-sdk.dev/.well-known/ai-catalog.json): ARD manifest of the agent-facing resources on this site (MCP server, skills, APIs). - [agent-readability.json](https://outbound-sdk.dev/agent-readability.json): Manifest of every agent-facing artifact on this site. - [Sitemap](https://outbound-sdk.dev/sitemap.xml): Every indexable page URL with its last-modified date.