Skip to main content
Messages are the individual units of communication in Heymarket. Every message belongs to a conversation and is associated with a contact. You can send SMS, MMS, email, group messages, broadcasts, and internal comments — all through a consistent API structure.

​
The Message object

The following attributes are returned when you fetch a message from the API.
AttributeDescription
idUnique identifier for the message
textMessage text content
mediaMedia URL, present on MMS messages
phonePhone number associated with the message
typeMessage type
statusDelivery status of the message
dateTimestamp when the message was sent or received
userID of the user who sent the message
conversationThe associated conversation object
broadcast_idBroadcast ID if this message was part of a broadcast
flaggedWhether the message has been flagged for review

​
Message types

​
Individual SMS/MMS

Send a message to a single phone number. Include a media_url to send an MMS with an image or other media attachment.

​
Group MMS

Send a single MMS to multiple recipients at once by specifying an array of phone numbers in the targets field. All recipients receive the same message in a group thread.

​
Broadcast

Send a message to a contact list by specifying a list_id. Each recipient receives the message individually and can reply privately — their replies do not go to the group. Broadcasts are well suited for announcements and campaigns.

​
Email

Send an email message through: 
POST /v1/email/send
Email messages follow the same conversation model as SMS, so replies are tracked in the same thread.

​
Private comment (memo)

Add an internal note to a conversation that is only visible to your team — the customer never sees it. Set private: true when creating the message. 
{
  "text": "Customer mentioned they called in last week.",
  "private": true
}

​
Scheduled message

Create a message to be sent at a future time: 
POST /v1/schedule
Provide a future timestamp and the message will be queued and delivered automatically when the scheduled time arrives. You can cancel a scheduled message before it is sent.

​
Templates and merge tokens

Templates let you reuse message content and personalize it for each recipient. You can include the following merge tokens in any template or message body:
TokenReplaced with
{{first_name}}Contact’s first name
{{last_name}}Contact’s last name
{{custom_field_name}}Value of the matching custom field
When Heymarket sends the message, it replaces each token with the corresponding value from the contact record. If a value is missing, the token is replaced with an empty string.

​
Media

To send an image or other media file, include a publicly accessible URL in the media_url field of your request. Heymarket fetches the file and delivers it as an MMS attachment. 
{
  "phone": "14155553434",
  "text": "Here is your receipt.",
  "media_url": "https://example.com/receipts/order-123.jpg"
}
Supported media types include JPEG, PNG, GIF, and PDF, subject to carrier limits on file size.