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 cossThe 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: CossHover any identifier in these examples to see its type.
Products
The same client reaches every product. A short example of each, with its guide:
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,
});| Option | Default | Description |
|---|---|---|
apiKey | COSS_API_KEY | A coss_live_… or coss_test_… key |
baseUrl | COSS_BASE_URL, then https://api.coss.com | The API origin |
timeout | 30000 | Per-attempt timeout in milliseconds |
maxRetries | 2 | Retries for network errors, timeouts, 409, 429 and 5xx |
fetch | global fetch | A custom fetch implementation |
dangerouslyAllowBrowser | false | Allow running where document exists (exposes your key) |
tracing | true | An OpenTelemetry span per call, when @opentelemetry/api is installed (Tracing) |
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