coss.comdocs

Create an inbox

POST
/v1/inboxes

Gives an agent (or anyone) its own email address in the API key's environment: username@<the environment's inbound domain>, which needs no DNS setup, or an address at one of the environment's receiving domains (domain). Mail to it is kept as threads, and each message that arrives sends an inbox.message.received webhook. With a client_id that already has an inbox, that inbox is returned (200) instead of a new one.

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
username?string

The part before the @. Omit it for a random one. Mail to username+anything@domain reaches the inbox too.

Match^(?!.*\.\.)[a-z0-9](?:[a-z0-9._-]{0,62}[a-z0-9])?$
Lengthlength <= 64
domain?string

One of the environment's receiving domains (its hostname). Omit it for the environment's own domain under coss.com's inbound domain, which needs no DNS setup.

Length1 <= length <= 253
display_name?string

The name messages from the inbox are sent with.

Length1 <= length <= 64
client_id?string

Your own id for the inbox (unique per environment). Creating an inbox with a client_id that already has one returns that inbox instead (200), so retries and "one inbox per user" need no bookkeeping.

Match^[\x21-\x7e]{1,128}$

Response Body

The environment's inbox with this client_id.

application/json
  1. response
object*"inbox"
Value in"inbox"
id*string
address*string

The inbox's email address (username@domain).

username*string
domain*string
kind*string

managed: at the environment's own domain under coss.com's inbound domain (no DNS setup). domain: at one of the environment's receiving domains.

Value in"managed""domain"
display_name*|

The name messages from the inbox are sent with.

client_id*|

Your own id for the inbox, e.g. your agent's or user's (unique per environment).

can_send*boolean

Whether messages can be sent from the inbox. Inboxes at coss.com's inbound domain only receive in live environments: create the inbox at a receiving domain under one of your verified domains to send from it.

sandbox*boolean

Whether it belongs to a sandbox environment.

created_at*string
Formatdate-time
updated_at*string
Formatdate-time
import { Coss } from "coss";const coss = new Coss({  apiKey: process.env.COSS_API_KEY,  baseUrl: "https://api.coss.com",});const { data, error } = await coss.inboxes.create({  username: "support-agent",  display_name: "Acme Support",  client_id: "agent-42",});
{  "object": "inbox",  "id": "inbox_01k7c8m4q2f3e9v6t5r1n0p8yz",  "address": "support-agent@k3j9x2m7qp4l.inbound.coss.com",  "username": "support-agent",  "domain": "k3j9x2m7qp4l.inbound.coss.com",  "kind": "managed",  "display_name": "Acme Support",  "client_id": "agent-42",  "can_send": true,  "sandbox": true,  "created_at": "2026-10-10T12:00:00.000Z",  "updated_at": "2026-10-10T12:00:00.000Z"}