Overview

Install the coss TypeScript SDK, configure the client and handle results. Zero dependencies, on Node.js 22+, Bun, Deno and Cloudflare Workers.

coss is the official TypeScript SDK. It has zero dependencies, is fully typed and runs on Node.js 22+, Bun, Deno and Cloudflare Workers.

npm install coss

The client

One client covers every product. Create it once and reuse it. Each endpoint's page in the API reference shows its SDK call in the TypeScript tab; these pages cover how the client itself behaves.

import {  } from "coss";

const coss = new ({ : .. });
const coss: Coss

Hover any identifier in these examples to see its type.

Products

The same client reaches every product. A short example of each, with its guide:

Email

Sending, and broadcasts to a whole audience or segment:

await ..({
  : "Acme <hello@acme.com>",
  : "ada@example.com",
  : "Welcome",
  : "<p>It works!</p>",
});

const { :  } = await ...({
  : "October newsletter",
  : "seg_01k7c8m4q2f3e9v6t5r1n0p8yz",
  : "Acme <news@acme.com>",
  : "What's new",
  : "<p>Hi {{{contact.first_name|there}}}</p>",
});
await ...(!.);

SMS

Text messages from your organization's numbers:

const { :  } = await ..({
  : "+14155550123",
  : "+14155550199",
  : "Your order has shipped.",
});

Verify

One-time codes by SMS or email:

await ..({ : "+14155550123" });
const { :  } = await ..({ : "+14155550123", : "482913" });
.(?.);

Sign

E-signatures on your PDFs, embedded or by email:

const { :  } = await ...({
  : "Services agreement",
  : [{ : "agreement.pdf", :  }],
  : [
    {
      : "Ada Lovelace",
      : "ada@example.com",
      : [{ : "signature", : "{{signature:signer_1}}" }],
    },
  ],
});

Forms

Form endpoints for your site, with spam filtering and delivery built in:

const { :  } = await ..({
  : "Contact us",
  : { : ["support@example.com"] },
});
.(?.);

Scheduling

Bookings with your users' calendars and double-booking handled:

const { :  } = await ...(, {
  : "2027-01-04T00:00:00Z",
  : "2027-01-11T00:00:00Z",
});

const { :  } = await ...({
  : ,
  : !.[0]!.,
  : { : "Sam Lee", : "sam@example.com", : "America/Chicago" },
});

Inboxes

Email addresses for AI agents, with threads and replies:

const { :  } = await ..({ : "support-agent" });

await ...(!., , { : "On it." });

Hooks

Webhooks as a service, delivered to your customers' endpoints:

const { :  } = await ...({
  : "customer_8812",
  : "invoice.paid",
  : { : "in_1042", : 4200 },
});

Risk

Risk assessments of sign-ups, logins and other events:

const { :  } = await ..({
  : "signup",
  : { : "ada@example.com" },
  : "203.0.113.7",
});
.(?., ?.);

Options

const  = new ({
  : "coss_test_...",
  : "https://api.coss.com",
  : 30_000,
  : 2,
  : false,
});

The constructor throws only for programmer errors: a missing API key, or running in a browser without dangerouslyAllowBrowser.

Results, not exceptions

Every method returns { data, error }. API and network failures come back as error; they are never thrown. Checking error narrows data:

const  = await ..("email_01k7c8m4q2f3e9v6t5r1n0p8yz");

if (.) {
  .(..);
} else {
  .(.data.);
data: Email
}

Per-request options

Methods take an optional last argument. Every method accepts an AbortSignal; send also takes an idempotency key.

const  = new ();

await ..(, { : "welcome-user-123", : . });
await ..("email_01k7c8m4q2f3e9v6t5r1n0p8yz", { : . });

Any endpoint

coss.request() calls an endpoint by its path, for one the SDK has no method for yet. It takes the client's key, version, timeout and retries, and returns the response's JSON as { data, error }, unchecked (pass a type to describe it):

const { ,  } = await .<{ : { : string }[] }>("GET", "/v1/domains", {
  : { : 5 },
});

await .("POST", "/v1/domains/dom_01k7c8m4q2f3e9v6t5r1n0p8yz/verify");

GET and DELETE are retried like every other call; POST, PUT and PATCH only with retry: true, since not every endpoint deduplicates them (saving a template's draft counts every attempt as a revision). responseType: "text" or "bytes" reads a body that isn't JSON (a CSV export, a received email's raw message).

Diagnose a delivery

coss/diagnose explains what happened to an email: a verdict, what each recipient's status means (a bounce with the receiving server's reason, a suppression with its entry, a delay, a failure and its cause), account problems that affect it and what to do next. diagnose reads the email, its events and the account context it needs; diagnoseEmail is the pure part, for data you already have. The CLI's coss emails diagnose and the MCP server's diagnose_email use it too.

The other products have the same: fetchSmsDiagnosis, fetchVerificationDiagnosis, fetchSignRequestDiagnosis, fetchFormSubmissionDiagnosis, fetchHookDeliveryDiagnosis and fetchSchedulingSlotsDiagnosis read what they need and answer with a verdict, a summary and next steps, and diagnoseSms, diagnoseVerification, diagnoseSignRequest, diagnoseFormSubmission, diagnoseHookDelivery and diagnoseSchedulingSlots are their pure parts.

import {  } from "coss/diagnose";

const { ,  } = await (, "email_01k7c8m4q2f3e9v6t5r1n0p8yz");
if () {
  .(.verdict, .);
Diagnosis.verdict: Verdict
for (const of .) .(., .); }

Runtimes

The package is ESM-only and uses nothing but fetch, AbortSignal and crypto.randomUUID. Environment fallbacks read process.env where it exists; on Workers or Deno without env access, pass apiKey (and baseUrl) explicitly.

Last updated