---
title: "Send an SMS to all members of a contact group"
method: POST
path: "/v1/contact-groups/{id}/messages"
tags: ["Contact Groups"]
---

# Send an SMS to all members of a contact group

`POST /v1/contact-groups/{id}/messages`

## Request

- Base URL: `https://api.honkio.ca`
- URL: `https://api.honkio.ca/v1/contact-groups/{id}/messages`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Always answers 207, whether every member sent or every member failed: check each entry in `results` rather than the HTTP status. Each result names the member `to` number. A live broadcast repeated with the same Idempotency-Key within 24 hours answers with the first attempt's stored 207, without running the whole-group checks again or using another daily broadcast slot. A later retry with that key runs the checks again (and can use a slot) but never re-messages a member the first attempt already reached.

Requires `messages:w`.

## Path parameters

- `id` string, required

## Headers

- `idempotency-key` string

## Request body

- object
  - `from` string, required: Sending number (E.164, must be owned by account)
  - `body` string, required: Up to 1600 characters and 10 SMS parts. Longer bodies are rejected with 422 MESSAGE_TOO_LONG before any member is messaged.
  - `skip_consent_check` boolean

## Response `207`

Always 207: check each result, not the status. A live broadcast repeated with the same Idempotency-Key within 24 hours answers with the first attempt's stored result.

- object: Always 207: check each result, not the status. A live broadcast repeated with the same Idempotency-Key within 24 hours answers with the first attempt's stored result.
  - `group_id` string, required
  - `sent_to` integer, required: Members not failed.
  - `failed` integer, required
  - `results` object[], required
    - `to` string, required: The member's number.
    - `status` string, required: Lowercase: the message status (queued, sent, delivered and so on), or failed.
    - `message_id` string: Absent when the member failed before a message was created.
    - `error` string: An error code: why the member failed, or the message's own error_code.
  - `estimated_completion_at` string, date-time, nullable: An estimate of when the carrier will have sent the last member, from the sending number's queue. Null in test mode. Absent from a stored replay of a broadcast sent before it existed.

## Other responses

- `401`: Missing, invalid, revoked or expired API key.
- `402`: INSUFFICIENT_BALANCE: the balance cannot cover the send. Also PAYMENT_REQUIRED when a LIVE key is used before the first top-up.
- `403`: FORBIDDEN (skip_consent_check on a live key, or the key lacks messages:w), ACCOUNT_NOT_VERIFIED, SENDING_PAUSED, or TOLL_FREE_NOT_VERIFIED (a toll-free from number without an approved toll-free verification; test keys too). A live member without a confirmed double opt-in fails alone in the results with DOUBLE_OPT_IN_REQUIRED.
- `404`: CONTACT_GROUP_NOT_FOUND.
- `422`: VALIDATION_ERROR, BROADCAST_TOO_LARGE, MESSAGE_TOO_LONG or LINK_SHORTENER_BLOCKED.
- `429`: BROADCAST_LIMIT_REACHED, DAILY_LIMIT_REACHED, FANOUT_LIMIT_REACHED, NUMBER_QUEUE_FULL (the broadcast's message parts would overfill the sending number's carrier queue; Retry-After is set when waiting would make room) or RECIPIENT_RATE_LIMITED, or RATE_LIMITED at 100 requests per second.
- `500`: Unexpected server error.

---

[API](https://skmtc.dev/honkio/apis/honkio-api.md) · [All operations](https://skmtc.dev/honkio/apis/honkio-api/llms.txt) · [OpenAPI document](https://skmtc.dev/honkio/apis/honkio-api/revisions/ce4ed3fe9691?raw)