Overview
Send email through coss.com from the libraries you already use, by changing configuration instead of call sites.
If your app already sends email through a mail library, an auth framework or a web framework's mailer, you don't need to rewrite those calls. Point it at coss.com instead.
The JavaScript integrations ship in the coss package, so there is nothing else to
install:
npm install coss| Integration | Import | What it replaces |
|---|---|---|
| Nodemailer | coss/nodemailer | SMTP or another transport in nodemailer.createTransport |
| Better Auth | coss/better-auth | The email callbacks: verification, password reset, magic links, codes, invitations |
| Auth.js | coss/authjs | The email (magic link) provider |
Every JavaScript 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.
The framework drivers are packages of their own, each with no dependency beyond its framework:
They read the API key from their own configuration, else COSS_API_KEY, and also check it on the
first send rather than at startup.
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-Typeand 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.
In JavaScript, 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 }. The framework drivers raise their framework's kind of error with the same
fields; see each page.
try {
await ();
} catch () {
if ( instanceof && . === "domain_not_verified") {
// Verify the sender's domain in the dashboard, or send with a sandbox key.
}
throw ;
}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.
Last updated
On This Page