Messages — Reference — Clement docs

List messages

get /v1/messages

curl TypeScript

curl -X GET "https://api.clement.so/v1/messages" \
  -H "Authorization: Bearer $CLEMENT_API_KEY"

import { Clement } from "@clement/sdk";

const c = new Clement({ apiKey: process.env.CLEMENT_API_KEY! });
const result = await c.messages.list();

Query parameters

limit integer
starting_after string
ending_before string
inbox_id string
direction string
classification string
thread_id string
expand string

Response200

OK

Property	Type	Description
`object` required	enum (1)	`"list"`
`data` required	array<Message>
`has_more` required	boolean
`next_cursor` required	string \| null
`prev_cursor` required	string \| null

Example response

{
  "object": "list",
  "data": [
    {
      "id": "msg_01HZ8X3J9K7P2QV6R5N4M3T2L5",
      "object": "message",
      "mode": "live",
      "inbox_id": "inb_01HZ8X3J9K7P2QV6R5N4M3T2L1",
      "direction": "inbound",
      "classification": "reply",
      "thread_id": "18f8a2b3c4d5e6f",
      "rfc822_message_id": "<reply-abc123@example.com>",
      "in_reply_to": "<01HZ8X3J9K7P2QV6@mail.clement.so>",
      "from_email": "alice@example.com",
      "from_name": "Alice",
      "subject": "Re: Quick question about Acme's data stack",
      "bounce_type": null,
      "bounce_status_code": null,
      "matched_send_id": "snd_01HZ8X3J9K7P2QV6R5N4M3T2L4",
      "received_at": "2026-04-29T16:42:11Z",
      "created_at": "2026-04-29T16:42:13Z"
    }
  ],
  "has_more": false,
  "next_cursor": "string",
  "prev_cursor": "string"
}

Errors

400 Invalid request
401 Authentication failed
403 Insufficient scope
404 Not found
409 Conflict
422 Validation failed
429 Rate limited

See Errors for the full envelope and per-code reference.

Retrieve a message

get /v1/messages/{id}

curl TypeScript

curl -X GET "https://api.clement.so/v1/messages/obj_01HZ8X3J9K7P2QV6R5N4M3T2L1" \
  -H "Authorization: Bearer $CLEMENT_API_KEY"

import { Clement } from "@clement/sdk";

const c = new Clement({ apiKey: process.env.CLEMENT_API_KEY! });
const result = await c.messages.retrieve("obj_01HZ8X3J9K7P2QV6R5N4M3T2L1");

Path parameters

id string required

Query parameters

expand string

Response200

OK

Property Type Description

id required string

object required

enum (1)

"message"

mode required

enum (2)

"live""test"

inbox_id required string

inbox

MessageExpandInbox | null

Show properties

Property	Type	Description
`id` required	string
`email_address` required	string (email)
`display_name` required	string \| null
`status` required	string

direction required

enum (2)

"inbound""outbound"

classification required

enum (4) | null

"reply""auto_reply""bounce""unrelated"

thread_id required string Provider thread id (Gmail's resource id)

rfc822_message_id required string | null

in_reply_to required string | null

from_email required string | null

from_name required string | null

subject required string | null

bounce_type required string | null

bounce_status_code required string | null

matched_send_id required string | null

received_at required string (date-time) | null

created_at required string (date-time)

Example response

{
  "id": "msg_01HZ8X3J9K7P2QV6R5N4M3T2L5",
  "object": "message",
  "mode": "live",
  "inbox_id": "inb_01HZ8X3J9K7P2QV6R5N4M3T2L1",
  "direction": "inbound",
  "classification": "reply",
  "thread_id": "18f8a2b3c4d5e6f",
  "rfc822_message_id": "<reply-abc123@example.com>",
  "in_reply_to": "<01HZ8X3J9K7P2QV6@mail.clement.so>",
  "from_email": "alice@example.com",
  "from_name": "Alice",
  "subject": "Re: Quick question about Acme's data stack",
  "bounce_type": null,
  "bounce_status_code": null,
  "matched_send_id": "snd_01HZ8X3J9K7P2QV6R5N4M3T2L4",
  "received_at": "2026-04-29T16:42:11Z",
  "created_at": "2026-04-29T16:42:13Z"
}

Errors

400 Invalid request
401 Authentication failed
403 Insufficient scope
404 Not found
409 Conflict
422 Validation failed
429 Rate limited

See Errors for the full envelope and per-code reference.

Retrieve a message's body

get /v1/messages/{id}/body

Fetches the body from the mailbox on demand (Gmail API or IMAP); Clement stores headers only. Slower than other reads and counts against the inbox provider's rate limits, so fetch the messages you need. 502 `body_unavailable` when the provider can't return it (inbox disconnected, message deleted, token expired). Sandbox inboxes have no stored body (`html` and `text` null).

curl TypeScript

curl -X GET "https://api.clement.so/v1/messages/obj_01HZ8X3J9K7P2QV6R5N4M3T2L1/body" \
  -H "Authorization: Bearer $CLEMENT_API_KEY"

import { Clement } from "@clement/sdk";

const c = new Clement({ apiKey: process.env.CLEMENT_API_KEY! });
const id = "obj_01HZ8X3J9K7P2QV6R5N4M3T2L1";
const result = await c.request("GET", `/v1/messages/${id}/body`);

Path parameters

id string required

Response200

OK

Property	Type	Description
`object` required	enum (1)	`"message_body"`
`message_id` required	string
`html` required	string \| null
`text` required	string \| null

Example response

{
  "object": "message_body",
  "message_id": "msg_01HZ8X3J9K7P2QV6R5N4M3T2L7",
  "html": "string",
  "text": "string"
}

Errors

400 Invalid request
401 Authentication failed
403 Insufficient scope
404 Not found
409 Conflict
422 Validation failed
429 Rate limited

See Errors for the full envelope and per-code reference.