Skip to main content
Broadcasts let you send a single message to an entire list of contacts at once. Each recipient receives the message individually and can reply privately, creating a one-on-one conversation for any follow-up. Use broadcasts for announcements, promotions, reminders, or any outreach that targets a defined segment of your contacts.

​
Steps

1

Create a contact list

Use the v2 endpoint POST /v2/lists to create a list. Provide a title, a client-side local_id, and the recipients as contact IDs, phone numbers, or email addresses.
curl
curl -X POST https://api.heymarket.com/v2/lists \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "April Promo",
    "local_id": "promo-april-2026",
    "type": "contacts",
    "contacts": [98765, 98766, 98767],
    "phones": ["15105553344", "15105553355"]
  }'
The response returns the new list’s id. Use this value in the next step.
2

Send the broadcast

Call POST /v1/message/send with the list_id from your new list. You must include a local_id when sending to a list — this prevents duplicate sends if you retry the request.
curl
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,
    "list_id": 501,
    "local_id": "broadcast-april-2026-001",
    "text": "Hi {{first_name}}, your exclusive April offer is ready. Reply DETAILS for more info."
  }'
3

Track responses

Each recipient who replies creates an individual conversation in your Heymarket inbox. You can monitor these conversations in the app, by paginating POST /v1/conversations, or by listening for inbound message events on your webhook endpoint.

​
Creating a list

The POST /v2/lists endpoint is the preferred way to create contact lists.
FieldTypeDescription
titlestringRequired. Display name for the list.
local_idstringRequired. Client-side unique identifier for the list.
typestringUse "contacts" for omnichannel lists that support SMS, email, and other channels.
contactsarray of integersContact IDs to add to the list.
phonesarray of stringsPhone numbers to add (E.164 without plus sign).
emailsarray of stringsEmail addresses to add.
{
  "title": "April Promo",
  "local_id": "promo-april-2026",
  "type": "contacts",
  "contacts": [98765, 98766, 98767],
  "phones": ["15105553344", "15105553355"],
  "emails": ["customer@example.com"]
}

​
Updating a list

Use PUT /v2/lists/{id} to add or remove recipients from an existing list without recreating it. 
curl -X PUT https://api.heymarket.com/v2/lists/501 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "add_contacts": [98770, 98771],
    "remove_contacts": [98765],
    "add_phones": ["15105553366"],
    "remove_phones": ["15105553355"]
  }'
FieldTypeDescription
add_contactsarray of integersContact IDs to add.
remove_contactsarray of integersContact IDs to remove.
add_phonesarray of stringsPhone numbers to add.
remove_phonesarray of stringsPhone numbers to remove.
add_emailsarray of stringsEmail addresses to add.
remove_emailsarray of stringsEmail addresses to remove.

​
Complete example

The following sequence creates a list and immediately sends a broadcast to it. 
curl -X POST https://api.heymarket.com/v2/lists \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "April Promo",
    "local_id": "promo-april-2026",
    "type": "contacts",
    "phones": ["15105553344", "15105553355", "15105553366"]
  }'
Toll-free numbers are not supported for group MMS broadcasts. Use a standard long-code or short-code number for your sending inbox if you need MMS.
local_id is required when sending to a list. It acts as an idempotency key — if you send the same local_id twice, Heymarket will deduplicate the request.
Use templates with merge tokens to personalize each message in a broadcast. Supported tokens include {{first_name}}, {{last_name}}, and any custom field token configured in your account. Personalized messages typically see higher engagement than generic ones.