Skip to main content
GET
/
conversations
/
{id}
/
messages
List messages in a conversation
curl --request GET \
  --url https://api.getfernand.com/conversations/{id}/messages \
  --header 'X-API-Key: <api-key>'
[
  {
    "id": "m-123456",
    "conversation_id": 12345,
    "type": "MESSAGE",
    "timestamp": "2026-01-21T14:30:00Z",
    "way": "IN",
    "status": "SENT",
    "source": "EMAIL",
    "download_url": "https://api.getfernand.com/conversations/a1b2c3d4-e5f6-7890-abcd-ef1234567890/original.eml?token=abc123",
    "agent_id": 42,
    "contact_id": 789,
    "message": "<p>Hello, I need help with my account.</p>",
    "attachments": [
      {
        "id": 123,
        "name": "<string>",
        "url": "<string>",
        "type": "<string>",
        "size": 123,
        "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      }
    ],
    "delay": 0,
    "unsubscribe_url": "https://newsletter.hooli.com/unsubscribe?token=xyz789",
    "last_event": {
      "event": "DELIVERED",
      "received_at": "2026-01-21T14:31:00Z",
      "error_code": "550",
      "reason": "Message delivered successfully"
    },
    "actions": [
      {}
    ],
    "language": "en",
    "is_read": false,
    "is_automated": false
  }
]
Upcoming changes!

This endpoint returns id in the form [x]-[id], such as m-1234 for messages, n-4321 for notes, and e-6789 for events, but the messages and notes endpoints expects the id as integer, without the first part.

We will soon update this endpoint API without notification to remove the first parts (m-, n- and e-) so you should conditionnaly strip these, and rely on the type property to know if it’s a message, note or event.

Thank you for your understanding.

Authorizations

​
X-API-Key
string
header
required

Authenticate your account by including your secret key in API requests. You can manage your API keys in the Dashboard.

Authentication to the API is performed by using the HTTP Header X-API-Key.

Path Parameters

​
id
integer<int64>
required

ID of the conversation to retrieve messages from.

Query Parameters

​
before
string

Timestamp or Unix epoch (in seconds or milliseconds) to fetch messages before. Accepts ISO 8601 format or Unix timestamp. Used for pagination to load older messages.

​
limit
integer
default:20

Maximum number of entries to return.

Required range: 5 <= x <= 100

Response

Messages retrieved successfully.

​
id
string
required

Unique identifier for the message

Example:

"m-123456"

​
conversation_id
integer<int64>
required

ID of the conversation this message belongs to

Example:

12345

​
type
enum<string>
required

Type of entry (always MESSAGE for messages)

Available options:
MESSAGE
Example:

"MESSAGE"

​
timestamp
string<date-time>
required

ISO 8601 timestamp when the message was created

Example:

"2026-01-21T14:30:00Z"

​
way
enum<string>
required

Direction of the message (IN for incoming, OUT for outgoing)

Available options:
IN,
OUT
Example:

"IN"

​
status
enum<string>
required

Current status of the message

Available options:
DRAFT,
PENDING,
SENT,
RECEIVED,
BOUNCED,
SPAM,
ERROR
Example:

"SENT"

​
source
enum<string>
required

Source channel of the message

Available options:
EMAIL,
CHAT
Example:

"EMAIL"

​
download_url
string | null

URL to download the original email file (.eml), if available

Example:

"https://api.getfernand.com/conversations/a1b2c3d4-e5f6-7890-abcd-ef1234567890/original.eml?token=abc123"

​
agent_id
integer<int64> | null

ID of the agent who sent the message (null for incoming messages)

Example:

42

​
contact_id
integer<int64> | null

ID of the contact who sent the message (null for outgoing messages)

Example:

789

​
message
string

HTML content of the message body

Example:

"<p>Hello, I need help with my account.</p>"

​
attachments
object[]

Array of file attachments in the message

​
delay
integer<int32>

Delay in seconds before the message is sent (for scheduled messages)

Example:

0

​
unsubscribe_url
string | null

URL for the recipient to unsubscribe, if available

Example:

"https://newsletter.hooli.com/unsubscribe?token=xyz789"

​
last_event
object

Most recent delivery event for this message

​
actions
object[]

Array of automated actions triggered by this message

​
language
string | null

Detected language code of the message content (e.g., en, fr, es)

Example:

"en"

​
is_read
boolean

Whether the message has been read by the recipient (chat messages only)

Example:

false

​
is_automated
boolean

Whether this message was sent automatically by the system

Example:

false