Skip to main content
Heymarket provides three endpoints for accessing message history: a simple lookup that returns the 50 most recent messages in a conversation, a paginated endpoint for retrieving all messages across your team, and a count endpoint. Use these together to build message logs, exports, and analytics integrations.

​
GET /v1/messages — get recent messages

Returns up to 50 recent messages for a specific conversation, identified by phone number and inbox.

​
Query parameters

​
phoneNumber
string
required
The recipient’s phone number in E.164 format without the leading plus sign (e.g., 14155551234).
​
inboxID
integer
required
The ID of the inbox containing the conversation.
​
timestamp
integer
A Unix timestamp. When provided, only messages sent before this time are returned. Use this to retrieve older messages in the conversation.

​
Example

curl --request GET \
  --url 'https://api.heymarket.com/v1/messages?phoneNumber=14155551234&inboxID=101' \
  --header 'Authorization: Bearer YOUR_API_KEY'

​
Response

Returns an array of up to 50 Message objects.

​
POST /v1/messages/all — paginate all messages

Returns a paginated list of messages across your entire team. Use the date field from the last returned message as the created_at cursor in the next request to fetch the following page.

​
Request body

​
created_at
string
required
An RFC 3339 timestamp used as the pagination cursor. Only messages created before this time are returned. On the first request, pass the current time or a historical start date.
​
order
string
The field to sort results by. Accepts created_at or updated_at. Defaults to created_at.
​
ascending
boolean
When true, results are returned in ascending chronological order. Defaults to false (descending).
​
limit
integer
default:"30"
The maximum number of messages to return per page. Defaults to 30.

​
Example

curl --request POST \
  --url https://api.heymarket.com/v1/messages/all \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "created_at": "2026-04-16T00:00:00+00:00",
    "order": "created_at",
    "ascending": false,
    "limit": 30
  }'
To paginate through all messages, take the date value of the last message in each response and pass it as created_at in your next request. Repeat until the response returns an empty array.

​
POST /v1/messages/all/count — get message count

Returns the total number of messages for your team, optionally filtered by a date range.

​
Request body

​
created_at
string
An RFC 3339 timestamp. When provided, only messages created before this date are counted.

​
Example

curl --request POST \
  --url https://api.heymarket.com/v1/messages/all/count \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "created_at": "2026-04-16T00:00:00+00:00"
  }'

​
Response

Returns the total count as a string, for example: "1042".

​
The Message object

All message endpoints return Message objects with the following fields.
​
id
integer
The unique ID of the message.
​
text
string
The text content of the message.
​
media
string
The URL of any attached media (MMS).
​
phone
string
The phone number associated with the message.
​
type
string
The direction of the message: inbound or outbound.
​
status
string
The delivery status of the message (e.g., delivered, failed, pending).
​
date
string
The ISO 8601 timestamp of when the message was sent or received.
​
user
object
The team member who sent the message, if applicable.
​
conversation
object
The conversation this message belongs to.
​
broadcast_id
integer
The ID of the broadcast campaign this message was part of, if applicable.
​
flagged
boolean
Whether the message has been flagged for review.
​
local_id
string
The client-side unique ID provided at send time, if any.
​
author
string
The label displayed above the message bubble.