Skip to main content
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

1

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.
2

Choose the target

Pick one target family for the send. Do not combine target families in one request.
Target familyFieldsUse when
Individual SMS/MMSphone_number or chat_idSending to one phone number or replying inside one conversation.
List broadcastlist_id and local_idSending separate one-to-one messages to a contact list.
Group MMStargetsSending one group MMS conversation to multiple phone numbers.
3

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."
  }'
4

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."
  }'

​
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.