> ## 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 SMS and MMS messages

> Send individual messages, MMS attachments, templates, broadcasts, and private comments with POST /v1/message/send.

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

<Warning>
  `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.
</Warning>

## Steps

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

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

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

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

    ```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,
        "phone_number": "15105553344",
        "text": "Hi! Your order has shipped and will arrive by Friday."
      }'
    ```
  </Step>

  <Step title="Store the response ID">
    A successful request returns the created message `id`, the send `date`, and `gallery_url` when applicable.

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

## Examples

<CodeGroup>
  ```bash Individual SMS 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,
      "phone_number": "15105553344",
      "text": "Hi! Your order has shipped and will arrive by Friday."
    }'
  ```

  ```bash MMS with media 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,
      "phone_number": "15105553344",
      "text": "Here is your receipt.",
      "media_url": "https://example.com/receipt.png"
    }'
  ```

  ```bash Template 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,
      "phone_number": "15105553344",
      "template_id": 301
    }'
  ```

  ```bash Private comment 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,
      "chat_id": 123456,
      "text": "Customer asked about their renewal date.",
      "private": true,
      "author": "Support Bot"
    }'
  ```
</CodeGroup>

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

## Related pages

<CardGroup cols={2}>
  <Card title="Messages" icon="message" href="/concepts/messages">
    Understand message targets, content, and delivery models.
  </Card>

  <Card title="Send message reference" icon="code" href="/api-reference/messages/send">
    Review all request fields and response fields.
  </Card>

  <Card title="Message history reference" icon="history" href="/api-reference/messages/get-history">
    Retrieve messages for a conversation when you need to verify delivery or replies.
  </Card>

  <Card title="Webhook guide" icon="webhook" href="/guides/webhooks">
    Receive inbound replies and message events in real time.
  </Card>
</CardGroup>