Overview

If your app already sends email through a mail library or an auth framework, you don't need to rewrite those calls. Point the library at coss.com instead. Each integration ships in the coss package, so there is nothing else to install:

npm install coss

Every integration reads the API key from COSS_API_KEY unless you pass apiKey. You can also pass client to reuse a Coss client you already have. The client is created on the first send, so a missing key fails that send, not your app's startup or its build.

How messages are mapped

The integrations send through the JSON API rather than the SMTP relay. That works where outgoing SMTP ports are blocked (serverless functions, edge runtimes), sets coss.com's own fields per message, and gives you the API's error codes. Each integration turns the library's message into a send request:

• Addresses become Name <address>, with the name quoted when it contains special characters.
• Attachments are sent base64-encoded. One with a Content-ID (cid) is sent inline, for <img src="cid:…">.
• Headers that coss.com sets itself (Message-ID, Date, MIME-Version, Content-Type and similar) are dropped instead of failing the send. Values with non-ASCII characters are encoded as RFC 2047 encoded-words. Other headers go through as custom headers (at most 15).
• What coss.com can't send fails the send instead of being silently dropped: raw MIME messages, a custom SMTP envelope, a separate Sender, and AMP bodies.

coss.com refusals throw a CossSendError. It carries the API's error as error and its code, status and requestId (quote the request id to support). These libraries report failures by throwing, so integrations throw too, unlike coss.email.send, which returns { data, error }.

try {
  await send();
} catch (err) {
  if (err instanceof CossSendError && err.code === "domain_not_verified") {
    // Verify the sender's domain in the dashboard, or send with a sandbox key.
  }
  throw err;
}

Authentication emails

The Better Auth and Auth.js integrations send with category: "account" and turn open and click tracking off. Click tracking would send the secret sign-in links through coss.com's redirect, and an account category keeps suppressions you scoped to other categories (such as marketing) from blocking sign-in mail.

With a live key, from must use a verified domain. Sandbox keys (coss_test_…) send from any address and never deliver, so they're the way to try an integration out.