Skip to main content
Broadcasts send the same message to a list of recipients. Each recipient receives an individual message and replies privately in their own conversation.

​
Prerequisites

Before you send a broadcast, collect:
  • A signed JWT generated from an API Secret.
  • An inbox_id for the sending inbox.
  • A creator_id for a sender member in that inbox.
  • A contact list, or the contact IDs, phone numbers, or email addresses for a new list.
Confirm that recipients are eligible to receive the message before you send. Review opt-in status, list membership, and phone-number formatting in your source system or Heymarket.

​
Steps

1

Create the list

Create a list with POST /v2/lists. Provide a title, a unique local_id, and at least one recipient source.
curl -X POST https://api.heymarket.com/v2/lists \
  -H "Authorization: Bearer YOUR_SIGNED_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "April Reminders",
    "local_id": "april-reminders-2026",
    "contacts": [98765, 98766],
    "phones": ["15105553344", "15105553355"]
  }'
Store the returned list id.contacts are existing Heymarket contact IDs. phones and emails add lightweight targets when you do not already have contact IDs.
2

Send to the list

Send the broadcast with POST /v1/message/send. When you provide list_id, you must also provide a unique message local_id.
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,
    "list_id": 501,
    "local_id": "broadcast-april-reminders-001",
    "text": "Hi {{first_name}}, your appointment reminder is ready."
  }'
3

Track replies

Replies arrive as individual conversations in the sending inbox. Track them in the app, poll conversation or message endpoints, or receive webhook events. Inbound message webhooks use the message_recieved event type.

​
Update a list

Use PUT /v2/lists/{id} to change list membership. 
curl -X PUT https://api.heymarket.com/v2/lists/501 \
  -H "Authorization: Bearer YOUR_SIGNED_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "add_contacts": [98770, 98771],
    "remove_contacts": [98765],
    "add_phones": ["15105553366"],
    "remove_phones": ["15105553355"]
  }'
You can add or remove contacts, phone numbers, and email addresses. You can also replace membership by passing contacts, phones, or emails.

​
Broadcast rules

  • Use a unique local_id for each list and each broadcast send.
  • Use E.164 digits without the leading plus sign for phone numbers.
  • Use templates when broadcast copy should be managed in Heymarket.
  • Group MMS with targets is separate from list broadcasts, and toll-free sending numbers are not supported for group MMS.
A list broadcast sends separate one-to-one messages. It does not create a shared group thread for every list member.

Lists and templates

Understand lists, templates, tags, surveys, and scheduled sends.

Lists reference

Review list create, update, and delete endpoints.

Webhook guide

Receive replies to broadcast messages.