COSS
Emails

Retrieve an email

GET
/v1/emails/{id}

Only emails sent from the API key's own environment can be retrieved.

Authorization

bearerAuth
headerAuthorizationBearer <token>

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

Path Parameters

id*string

The email's id.

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"

Response Body

The email.

application/json
  1. response
object*"email"
Value in"email"
id*string
from*string
to*array<string>
cc*array<string>
bcc*array<string>
reply_to*array<string>
subject*string
html*string|null
text*string|null
headers*
tags*array<>
category*string|null
status*string

Whether the email was handed to the delivery provider. scheduled emails wait for scheduled_at; canceled ones were canceled before that. Per-recipient delivery is in recipients.

Value in"queued""sent""failed""scheduled""canceled"
recipients*array<>
attachments*array<>

Attachment metadata. Content is never returned, and is discarded once sent.

sandbox*boolean

True when sent from a sandbox environment (never delivered).

tracking*

Open and click tracking, as resolved when the email was sent, with engagement so far. Opens can be inflated by mail clients that prefetch images, clicks by link scanners.

created_at*string
Formatdate-time
sent_at*|
Formatdate-time
scheduled_at*|

When the email was scheduled to be sent; null if it was not.

Formatdate-time
batch_id*|

The batch that sent the email; null if it was sent on its own.

import { Coss } from "coss";const coss = new Coss({  apiKey: process.env.COSS_API_KEY,  baseUrl: "https://api.coss.com",});const { data, error } = await coss.email.get("email_01k7c8m4q2f3e9v6t5r1n0p8yz");
{  "object": "email",  "id": "email_01k7c8m4q2f3e9v6t5r1n0p8yz",  "from": "Acme <onboarding@acme.com>",  "to": [    "user@example.com"  ],  "cc": [],  "bcc": [],  "reply_to": [],  "subject": "Welcome to Acme",  "html": "<p>Thanks for signing up!</p>",  "text": null,  "headers": {},  "tags": [    {      "name": "template",      "value": "welcome"    }  ],  "category": "onboarding",  "status": "sent",  "recipients": [    {      "address": "user@example.com",      "type": "to",      "status": "delivered",      "last_event_at": "2026-10-10T12:00:02.000Z"    }  ],  "sandbox": false,  "tracking": {    "opens": false,    "clicks": false,    "open_count": 0,    "first_opened_at": null,    "last_opened_at": null,    "click_count": 0,    "first_clicked_at": null,    "last_clicked_at": null  },  "attachments": [],  "created_at": "2026-10-10T12:00:00.000Z",  "sent_at": "2026-10-10T12:00:01.000Z",  "scheduled_at": null,  "batch_id": null}

Cancel a scheduled email POST

Cancels an email sent with a future `scheduled_at` before it is sent. Canceling an already canceled email returns it unchanged. To send it at another time, reschedule it instead.

List an email's delivery events GET

Every delivery event of the email, oldest first: `email.scheduled`, `email.rescheduled`, `email.canceled`, `email.sent` and `email.failed` for the whole email, and `email.delivered`, `email.delivery_delayed`, `email.bounced`, `email.complained` and `email.suppressed` (skipped because of the suppression list) per recipient, plus `email.opened` and `email.clicked` when tracking is on (attributed to a recipient only when the email had a single one).