Send SMS and MMS messages

Use POST /v1/message/send when your integration needs to send a message from a Heymarket inbox. You can send to a phone number, reply in an existing conversation, send to a list, attach media, use a template, or add a private internal comment.

Prerequisites

Before you send a message, collect:

A signed JWT generated from an API Secret.
The inbox_id for the sending inbox.
The creator_id for the sender member.
The target, such as phone_number, chat_id, list_id, or targets.

creator_id is the member ID returned by GET /v1/inboxes or GET /v1/team. Do not assume it is the same as your general user ID.

Steps

Get the inbox and sender IDs

Call GET /v1/inboxes and choose the inbox that should send the message. Use the inbox id as inbox_id.

curl https://api.heymarket.com/v1/inboxes \
  -H "Authorization: Bearer YOUR_SIGNED_JWT"

Use a member ID from that inbox, or from GET /v1/team, as creator_id.

Choose the target

Pick one target family for the send. Do not combine target families in one request.

Target family	Fields	Use when
Individual SMS/MMS	`phone_number` or `chat_id`	Sending to one phone number or replying inside one conversation.
List broadcast	`list_id` and `local_id`	Sending separate one-to-one messages to a contact list.
Group MMS	`targets`	Sending one group MMS conversation to multiple phone numbers.

Send the message

Send the request with inbox_id, creator_id, a target, and message content from text, template_id, or media_url. Add private: true only when creating an internal comment inside an existing conversation.

curl -X POST https://api.heymarket.com/v1/message/send \
  -H "Authorization: Bearer YOUR_SIGNED_JWT" \
  -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."
  }'

Store the response ID

A successful request returns the created message id, the send date, and gallery_url when applicable.

{
  "id": 9980041,
  "date": "2026-04-16T14:22:00Z",
  "gallery_url": "https://example.com/media/receipt.png"
}

Store the message id or your own local_id if you need to reconcile webhook events, poll message history, or retry-sensitive work.

Examples

curl -X POST https://api.heymarket.com/v1/message/send \
  -H "Authorization: Bearer YOUR_SIGNED_JWT" \
  -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."
  }'

curl -X POST https://api.heymarket.com/v1/message/send \
  -H "Authorization: Bearer YOUR_SIGNED_JWT" \
  -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"
  }'

curl -X POST https://api.heymarket.com/v1/message/send \
  -H "Authorization: Bearer YOUR_SIGNED_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "inbox_id": 42,
    "creator_id": 7,
    "phone_number": "15105553344",
    "template_id": 301
  }'

curl -X POST https://api.heymarket.com/v1/message/send \
  -H "Authorization: Bearer YOUR_SIGNED_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "inbox_id": 42,
    "creator_id": 7,
    "chat_id": 123456,
    "text": "Customer asked about their renewal date.",
    "private": true,
    "author": "Support Bot"
  }'

Request rules

Use E.164 digits without the leading plus sign for phone numbers, such as 15105553344.
For an individual SMS or MMS, provide phone_number or chat_id.
For broadcasts, provide list_id and a unique local_id.
For MMS, media_url must be publicly accessible.
For group MMS with targets, toll-free sending numbers are not supported.
Use POST /v1/email/send for email. Email uses targets or convo_id, not the SMS/MMS target fields on this page.

Messages

Understand message targets, content, and delivery models.

Send message reference

Review all request fields and response fields.

Message history reference

Retrieve messages for a conversation when you need to verify delivery or replies.

Webhook guide

Receive inbound replies and message events in real time.

Get Started

Core Concepts

Guides

Prerequisites

Steps

Examples

Request rules

Messages

Send message reference

Message history reference

Webhook guide

​Prerequisites

​Steps

​Examples

​Request rules

​Related pages

Messages

Send message reference

Message history reference

Webhook guide

Prerequisites

Steps

Examples

Request rules

Related pages