Create a log drain
Streams the environment's logs to a URL: every line GET /v1/logs returns (API requests, email events, webhook attempts) and the environment's audit events, posted as signed NDJSON batches of up to 500 lines or 1 MB, usually within seconds. Log drains belong to the API key's own environment: a coss_test_… key only ever sees sandbox drains, and a coss_live_… key only production ones. The response carries the signing secret, which is returned only here: store it, and verify every batch with it (verifyLogDrainBatch in the SDK).
bearerAuthAuthorizationBearer <token>A secret API key from the dashboard: coss_live_… for production environments, coss_test_… for sandbox environments.
Coss-Version?"2026-10-10"The API version (a date) to use for this request. Defaults to your organization's version, pinned to the latest one when it first used the API and upgraded from the dashboard. The SDK always sends the version it was built for.
"2026-10-10"application/json- body
url*stringAn https:// URL COSS posts batches of log lines to.
1 <= length <= 2048description?|A note for your own reference. null clears it.
length <= 256sources?array<>What the drain forwards: api (requests made with the environment's API keys), email (email events), webhook (webhook delivery attempts) and audit (changes to the environment, from the organization's audit log). An empty array means every source, including ones added later. Defaults to every source.
items <= 4The drain and its signing secret.
application/json- response
object*"log_drain""log_drain"id*stringurl*stringdescription*string|nullsources*array<>What the drain forwards: api (requests made with the environment's API keys), email (email events), webhook (webhook delivery attempts) and audit (changes to the environment, from the organization's audit log). An empty array means every source, including ones added later.
enabled*booleanA disabled drain receives nothing, and lines logged while it is disabled are not kept for it.
disabled_reason*|manual: someone disabled it. failing: a batch failed every attempt, so COSS disabled it. null while enabled.
"manual""failing"nulldisabled_at*|date-timecreated_at*stringdate-timeupdated_at*stringdate-timesecret*stringThe drain's whsec_… signing secret, used to verify the batches COSS sends. Returned only when the drain is created — store it now; it cannot be read back through the API.
import { Coss } from "coss";const coss = new Coss({ apiKey: process.env.COSS_API_KEY, baseUrl: "https://api.coss.com",});const { data, error } = await coss.logDrains.create({ url: "https://logs.example.com/coss", description: "Production logs", sources: [ "api", "email", ],});{ "object": "log_drain", "id": "drain_01k7c8m4q2f3e9v6t5r1n0p8yz", "url": "https://logs.example.com/coss", "description": "Production logs", "sources": [ "api", "email" ], "enabled": true, "disabled_reason": null, "disabled_at": null, "created_at": "2026-01-15T09:30:00.000Z", "updated_at": "2026-01-15T09:30:00.000Z", "secret": "whsec_6Jk…"}Send an email POST
Queues an email from the API key's environment and returns it with `status: "queued"`; it is handed to the delivery provider moments later. Follow it with `GET /v1/emails/{id}` or the `email.sent` / `email.failed` webhooks. Live (`coss_live_…`) keys must send from a verified domain of the organization. Sandbox (`coss_test_…`) keys accept any `from` and never deliver anything; the response has `sandbox: true`. Recipients on the environment's suppression list (for every email, or for the email's `category`) are skipped and get the status `suppressed`. With a future `scheduled_at` the email is stored with the status `scheduled` and sent at that time; the domain and the suppression list are checked again then. Attachments are base64-encoded; only metadata is kept after sending. Recipients count against the organization's send quota (per second and per day; sandbox environments have their own daily quota). With open or click tracking on (the environment's settings, or `tracking`), the HTML body is delivered with a tracking pixel and/or links rewritten to COSS redirects; the stored `html` stays as sent.
Delete a log drain DELETE
Removes the drain and its batch log. Lines still waiting for it are dropped. To stop it temporarily, set `enabled` to `false` instead.