Receive email at a domain
Starts receiving email at the domain itself or a subdomain (e.g. inbound.acme.com): email sent to any address at that hostname becomes a received email of the API key's environment (an email.received webhook, GET /v1/received_emails). Publish the MX record in receiving.record; COSS checks it in the background. Using the domain itself moves all of its mail to COSS. A domain has at most one receiving hostname: remove it to use another one.
bearerAuthAuthorizationBearer <token>A secret API key from the dashboard: coss_live_… for production environments, coss_test_… for sandbox environments.
id*stringThe domain's id.
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
- body
- …
hostname*stringThe domain itself or a subdomain of it, without a scheme or path. Point its MX at COSS with the record the response lists. Using the domain itself moves all of its mail to COSS, so a subdomain is usually the better choice.
1 <= length <= 200The domain, with its receiving domain and the MX record to publish.
application/json- response
- response
- …
object*"domain""domain"id*stringname*stringThe domain, lower-cased.
status*stringpending 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.
"pending""verified""temporary_failure""failed""deleting"can_send*booleanWhether live keys may send from this domain right now.
region*string|nullmail_from_domain*stringThe envelope sender subdomain bounces come back to.
mail_from_status*string"pending""success""temporary_failure""failed"records*array<>The DNS records to publish, with the result of the last check.
created_at*stringdate-timelast_checked_at*|date-timeverified_at*|date-timefailed_at*|date-timetracking*|nullreceiving*|nullimport { Coss } from "coss";const coss = new Coss({ apiKey: process.env.COSS_API_KEY, baseUrl: "https://api.coss.com",});const { data, error } = await coss.domains.receiving.create("dom_01k7c8m4q2f3e9v6t5r1n0p8yz", { hostname: "inbound.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.cosslinks.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 }, "receiving": null}