coss.comdocs

Send a message from an inbox

POST
/v1/inboxes/{inbox_id}/messages

Starts a thread with a message from the inbox's address, sent like any email (its email_id has its delivery events and webhooks; never tracked). Replies to it arrive in the same thread. Live inboxes send only from receiving domains under one of the organization's verified domains (can_send); sandbox ones always can, and deliver nothing. Recipients count against the send quota.

Authorization

bearerAuth
headerAuthorizationBearer <token>

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

Path Parameters

inbox_id*string

The inbox's id.

Header Parameters

Idempotency-Key?string

Makes the send safe to retry: a repeat with the same key and body returns the first message instead of sending again (keys are per inbox). 1-256 characters.

Length1 <= length <= 256
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

Starts a thread: the message is sent from the inbox's address.

to*|array<>
cc?|array<>
bcc?|array<>
subject*string

The new thread's subject.

Length1 <= length <= 998
text?string

Plain-text body. Without it, an html email goes out with a text part generated from the HTML.

html?string

HTML body. Provide html, text, or both.

attachments?array<>

Up to 20 files, at most 25 MB combined.

Itemsitems <= 20
tags?array<>
Itemsitems <= 50

Response Body

The message, queued for delivery. A replay returns the first one.

application/json
  1. response
object*"inbox_message"
Value in"inbox_message"
id*string
inbox_id*string
thread_id*string
direction*string

inbound: received by the inbox. outbound: sent from it.

Value in"inbound""outbound"
status*string

received for inbound messages; an outbound message's email status (queued, sent, failed, …): its email has each recipient's delivery.

Value in"received""queued""sent""failed""scheduled""canceled"
from*|

The From header.

to*array<string>
cc*array<string>
subject*string|null
preview*|

The start of the message's own text (without the quoted conversation).

attachments*array<>

An inbound message's attachments (download them from the message).

spam*boolean

Whether the receiving server judged it spam.

received_email_id*|

The received email of an inbound message.

email_id*|

The email of an outbound message: its delivery events and webhooks name it.

created_at*string

When it was received or sent.

Formatdate-time
reply_to*array<string>
message_id*|

An inbound message's Message-ID header (outbound ones get theirs at sending).

in_reply_to*string|null
references*array<string>
text*string|null
extracted_text*|

The message's own text: text without the quoted conversation and signature below it (a heuristic; when nothing is left, all of text). Made from html when there is no text.

html*|

The sender's HTML: sanitize it before showing it to anyone.

truncated*boolean

Whether text or html were shortened (2 MB each).

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.messages.send("inbox_01k7c8m4q2f3e9v6t5r1n0p8yz", {  to: "jane@example.com",  subject: "Your order",  text: "Hi Jane, your order has shipped.",});
{  "object": "inbox_message",  "id": "imsg_01k7c8m4s1d3c9x0z4e6g7h8j9",  "inbox_id": "inbox_01k7c8m4q2f3e9v6t5r1n0p8yz",  "thread_id": "thread_01k7c8m4r0c2b8w9y3d5f6g7h8",  "direction": "inbound",  "status": "received",  "from": "Jane Doe <jane@example.com>",  "to": [    "support-agent@k3j9x2m7qp4l.inbound.coss.com"  ],  "cc": [],  "subject": "My order arrived damaged",  "preview": "Hi, the order arrived damaged. Can you send a new one?",  "attachments": [    {      "id": "rcvdatt_01k7c8m4r0c2b8w9y3d5f6g7h8",      "filename": "photo.jpg",      "content_type": "image/jpeg",      "content_id": null,      "disposition": "attachment",      "size": 48213    }  ],  "spam": false,  "received_email_id": "rcvd_01k7c8m4q2f3e9v6t5r1n0p8yz",  "email_id": null,  "created_at": "2026-10-10T12:00:00.000Z",  "reply_to": [],  "message_id": "<CAF3k2m9qp4ld8sv@mail.example.com>",  "in_reply_to": null,  "references": [],  "text": "Hi, the order arrived damaged. Can you send a new one?\n\nJane",  "extracted_text": "Hi, the order arrived damaged. Can you send a new one?\n\nJane",  "html": null,  "truncated": false}