coss.comdocs

Retrieve a received email

GET
/v1/received_emails/{id}

The received email with its headers, text and HTML bodies (each cut at 2 MB, see truncated) and attachment metadata. HTML is the sender's: sanitize it before showing it to anyone.

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 received 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 received email.

application/json
  1. response
object*"received_email"
Value in"received_email"
id*string
status*string

received, or blocked when the message carried a virus: then only its envelope and verdicts are kept, never its content.

Value in"received""blocked"
blocked_reason*|null
mail_from*string

The envelope sender (MAIL FROM); empty for bounces.

recipients*array<string>

The envelope recipients this environment received the message for (Bcc'd addresses included, other organizations' never).

from*|

The From header.

to*array<string>

The To header's addresses.

cc*array<string>

The Cc header's addresses.

subject*string|null
message_id*|

The Message-ID header.

attachments*array<>
size*integer

Size of the raw message in bytes.

spam*boolean

Whether the spam verdict is fail.

verdicts*

What the receiving server concluded: pass, fail, gray (could not decide) or processing_failed; null when the check did not run.

sandbox*boolean

Whether it was received by a sandbox environment.

received_at*string
Formatdate-time
reply_to*array<string>
in_reply_to*string|null
references*array<string>

Message ids of the References header.

sent_at*|

The Date header, when valid.

Formatdate-time
headers*array<>

Every header in message order (duplicates included).

text*string|null
html*string|null
truncated*boolean

Whether text, html or headers were shortened (2 MB per body, 64 KB of headers). The raw message always has all of it.

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.received.get("rcvd_01k7c8m4q2f3e9v6t5r1n0p8yz");
{  "object": "received_email",  "id": "rcvd_01k7c8m4q2f3e9v6t5r1n0p8yz",  "status": "received",  "blocked_reason": null,  "mail_from": "jane@example.com",  "recipients": [    "support@inbound.acme.com"  ],  "from": "Jane Doe <jane@example.com>",  "to": [    "support@inbound.acme.com"  ],  "cc": [],  "subject": "Re: Your order",  "message_id": "<CAF3k2m9qp4ld8sv@mail.example.com>",  "attachments": [    {      "id": "rcvdatt_01k7c8m4r0c2b8w9y3d5f6g7h8",      "filename": "invoice.pdf",      "content_type": "application/pdf",      "content_id": null,      "disposition": "attachment",      "size": 48213    }  ],  "size": 61432,  "spam": false,  "verdicts": {    "spam": "pass",    "virus": "pass",    "spf": "pass",    "dkim": "pass",    "dmarc": "pass",    "dmarc_policy": null  },  "sandbox": false,  "received_at": "2026-10-10T12:00:00.000Z",  "reply_to": [],  "in_reply_to": "<x7f3k2m9qp4ld8sv@acme.com>",  "references": [    "<x7f3k2m9qp4ld8sv@acme.com>"  ],  "sent_at": "2026-10-10T11:59:58.000Z",  "headers": [    {      "name": "From",      "value": "Jane Doe <jane@example.com>"    },    {      "name": "To",      "value": "support@inbound.acme.com"    },    {      "name": "Subject",      "value": "Re: Your order"    }  ],  "text": "Hi, the order arrived damaged.",  "html": "<p>Hi, the order arrived damaged.</p>",  "truncated": false}