> ## Documentation Index
> Fetch the complete documentation index at: https://developers.heymarket.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Send broadcast messages

> Create contact lists and send broadcast messages where each recipient gets an individual thread in Heymarket.

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

<Steps>
  <Step title="Create the list">
    Create a list with `POST /v2/lists`. Provide a `title`, a unique `local_id`, and at least one recipient source.

    ```bash theme={null}
    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.
  </Step>

  <Step title="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`.

    ```bash theme={null}
    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."
      }'
    ```
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Update a list

Use `PUT /v2/lists/{id}` to change list membership.

```bash theme={null}
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.

<Note>
  A list broadcast sends separate one-to-one messages. It does not create a shared group thread for every list member.
</Note>

## Related pages

<CardGroup cols={2}>
  <Card title="Lists and templates" icon="list" href="/concepts/lists-templates-scheduling">
    Understand lists, templates, tags, surveys, and scheduled sends.
  </Card>

  <Card title="Lists reference" icon="code" href="/api-reference/lists/overview">
    Review list create, update, and delete endpoints.
  </Card>

  <Card title="Webhook guide" icon="webhook" href="/guides/webhooks">
    Receive replies to broadcast messages.
  </Card>
</CardGroup>