Overview

The COSS API is a JSON API. Every endpoint page in this reference shows the request, every response, and samples for the TypeScript SDK, cURL, Python and Go.

The machine-readable OpenAPI 3.1 document describes the same endpoints.

Base URLCopy Anchor Link

https://api.coss.com

Paths start with /v1/…. Breaking changes ship as dated API versions, selected with the Coss-Version header: see Versioning.

AuthenticationCopy Anchor Link

Send your API key as a bearer token:

curl https://api.coss.com/v1/emails/email_01k7c8m4q2f3e9v6t5r1n0p8yz \
  -H "Authorization: Bearer $COSS_API_KEY"

The key decides the environment: requests only see data from the key's own environment. See Environments and API keys.

ConventionsCopy Anchor Link

• Request and response bodies are JSON (Content-Type: application/json). Requests are limited to 5 MB, except POST /v1/emails, which accepts up to 40 MB (at most 25 MB of decoded attachments).
• Field names are snake_case; timestamps are ISO 8601 strings in UTC.
• IDs are prefixed with their type: email_…, evt_….
• Every object has an object field naming its type ("email", "email_event", "list").
• Lists are { "object": "list", "data": [...], "has_more": false }.
• Every response carries an X-Request-Id header (req_…). Include it when contacting support.