COSS
Domains

Add a sending domain

POST
/v1/domains

Claims the domain for the organization and returns the DNS records to publish. Domains belong to the organization, not to one environment, so every API key of the organization sees the same domains. The records are checked repeatedly in the background and verification gives up after 72 hours; until the domain is verified, live keys cannot send from it.

Authorization

bearerAuth
headerAuthorizationBearer <token>

A secret API key from the dashboard: coss_live_… for production environments, coss_test_… for sandbox environments.

Header Parameters

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.

Value in"2026-10-10"

Request Body

application/json
  1. body
name*string

The domain to send from, without a scheme or path. Subdomains are allowed; internationalized domains must be punycode-encoded.

Length1 <= length <= 200

Response Body

The domain, with the DNS records to publish.

application/json
  1. response
object*"domain"
Value in"domain"
id*string
name*string

The domain, lower-cased.

status*string

pending while the records are being checked, verified once they are, temporary_failure after a transient DNS problem, and failed when verification gave up (72 hours) — restart it with the verify endpoint. deleting is a removal in progress.

Value in"pending""verified""temporary_failure""failed""deleting"
can_send*boolean

Whether live keys may send from this domain right now.

region*string|null
mail_from_domain*string

The envelope sender subdomain bounces come back to.

mail_from_status*string
Value in"pending""success""temporary_failure""failed"
records*array<>

The DNS records to publish, with the result of the last check.

created_at*string
Formatdate-time
last_checked_at*|
Formatdate-time
verified_at*|
Formatdate-time
failed_at*|
Formatdate-time
tracking*|null
import { Coss } from "coss";const coss = new Coss({  apiKey: process.env.COSS_API_KEY,  baseUrl: "https://api.coss.com",});const { data, error } = await coss.domains.create({  name: "acme.com",});
{  "object": "domain",  "id": "dom_01k7c8m4q2f3e9v6t5r1n0p8yz",  "name": "acme.com",  "status": "verified",  "can_send": true,  "region": "us-east-1",  "mail_from_domain": "send.acme.com",  "mail_from_status": "success",  "records": [    {      "priority": null,      "required": true,      "status": "verified",      "found": [],      "purpose": "dkim",      "type": "CNAME",      "name": "x7f3k2m9qp4ld8sv6hwz1nyc5rbtgj0e._domainkey.acme.com",      "value": "x7f3k2m9qp4ld8sv6hwz1nyc5rbtgj0e.dkim.amazonses.com"    },    {      "priority": 10,      "required": true,      "status": "verified",      "found": [],      "purpose": "mail_from_mx",      "type": "MX",      "name": "send.acme.com",      "value": "feedback-smtp.us-east-1.amazonses.com"    },    {      "priority": null,      "required": true,      "status": "verified",      "found": [],      "purpose": "mail_from_spf",      "type": "TXT",      "name": "send.acme.com",      "value": "v=spf1 include:amazonses.com ~all"    },    {      "priority": null,      "required": false,      "status": "verified",      "found": [],      "purpose": "dmarc",      "type": "TXT",      "name": "_dmarc.acme.com",      "value": "v=DMARC1; p=none;"    }  ],  "created_at": "2026-01-15T09:30:00.000Z",  "last_checked_at": "2026-01-15T09:42:10.000Z",  "verified_at": "2026-01-15T09:42:10.000Z",  "failed_at": null,  "tracking": {    "hostname": "links.acme.com",    "status": "active",    "record": {      "type": "CNAME",      "name": "links.acme.com",      "value": "track.coss.com",      "status": "verified",      "found": []    },    "message": null,    "created_at": "2026-01-15T09:45:00.000Z",    "last_checked_at": "2026-01-15T09:52:00.000Z",    "activated_at": "2026-01-15T09:52:00.000Z",    "failed_at": null  }}

List invoices GET

The organization's invoices, newest first, without their lines. Pass the last `id` as `after` to get the next page while `has_more` is true.

Add a custom tracking domain POST

Sets up a subdomain of the domain (e.g. `links.acme.com`) to serve open and click tracking. Publish the CNAME record in `tracking.record`; COSS then issues its certificate and checks it in the background, giving up after 72 hours. Open pixels and click redirects of emails sent from the domain (or its subdomains without a domain of their own) use the tracking domain while it is `active`, and the default tracking host otherwise. A domain has at most one tracking domain: remove it to use another hostname.