Skip to main content
The Heymarket API lets you send SMS and MMS messages programmatically from any inbox in your account. You can send to an individual phone number, use a saved template, or attach media for MMS. All requests go to https://api.heymarket.com and require your API key in the Authorization header.

​
Prerequisites

Before you can send a message, you need two IDs from your Heymarket account:
  • inbox_id — the inbox you want to send from
  • creator_id — the user ID that appears as the sender
Call GET /v1/inboxes to retrieve these values.

​
Steps

1

Get your inbox ID

Call GET /v1/inboxes to list all inboxes in your account. Each inbox object includes its ID, name, and associated phone numbers.
curl -X GET https://api.heymarket.com/v1/inboxes \
  -H "Authorization: Bearer YOUR_API_KEY"
Example response:
{
  "inboxes": [
    {
      "id": 42,
      "name": "Support",
      "phones": ["+15105550100"]
    },
    {
      "id": 87,
      "name": "Sales",
      "phones": ["+15105550200"]
    }
  ]
}
Note the id value for the inbox you want to send from, and the id of the user who should appear as the sender (retrieve user IDs from GET /v1/users).
2

Send an individual SMS

Post to POST /v1/message/send with your inbox_id, creator_id, the recipient’s phone_number, and the message text.
curl -X POST https://api.heymarket.com/v1/message/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inbox_id": 42,
    "creator_id": 7,
    "phone_number": "15105553344",
    "text": "Hi! Your order has shipped and will arrive by Friday."
  }'
3

Send with a template

Replace text with template_id to use a saved message template. The template content is applied server-side, including any merge tokens.
curl -X POST https://api.heymarket.com/v1/message/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inbox_id": 42,
    "creator_id": 7,
    "phone_number": "15105553344",
    "template_id": 301
  }'
4

Send with media (MMS)

Add a media_url field to send an image or other media file. The recipient’s carrier must support MMS.
curl -X POST https://api.heymarket.com/v1/message/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inbox_id": 42,
    "creator_id": 7,
    "phone_number": "15105553344",
    "text": "Here is your receipt.",
    "media_url": "https://example.com/receipt.png"
  }'
Toll-free numbers do not support group MMS.
5

Check the response

A successful request returns HTTP 200 with a JSON body containing the message ID, timestamp, and a link to view the conversation.
{
  "id": 9980041,
  "date": "2026-04-16T14:22:00Z",
  "gallery_url": "https://app.heymarket.com/conversations/123456"
}
Store id if you need to reference the message later (for example, to correlate with webhook events).

​
Request body

FieldTypeDescription
inbox_idintegerRequired. The inbox to send from.
creator_idintegerRequired. The user ID that appears as the sender.
phone_numberstringRecipient phone number in E.164 format without the leading plus sign (e.g., 15105553344).
targetsarray of stringsList of phone numbers for group MMS.
chat_idintegerExisting conversation ID. Use this to send into an open conversation instead of creating a new one.
list_idintegerContact list ID for broadcasting to a list.
textstringThe message body text.
media_urlstringPublicly accessible URL of a media file to send as MMS.
template_idintegerID of a saved template to use instead of text.
local_idstringClient-side unique identifier. Required when sending to a list.
privatebooleanWhen true, creates a private internal comment visible only to your team.
authorstringName displayed above the chat bubble in the conversation view.
survey_idintegerID of a survey to send to the recipient.

​
Code examples

curl -X POST https://api.heymarket.com/v1/message/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inbox_id": 42,
    "creator_id": 7,
    "phone_number": "15105553344",
    "text": "Hi! Your order has shipped and will arrive by Friday."
  }'

​
Response fields

FieldTypeDescription
idintegerUnique ID of the sent message.
datestringISO 8601 timestamp of when the message was sent.
gallery_urlstringURL to view the conversation in the Heymarket web app.