---
title: "simple_send"
method: POST
path: "/simple_send"
tags: ["Send"]
---

# simple_send

`POST /simple_send`

## Request

- Base URL: `https://api.commpeak.com/textpeak/streams`
- URL: `https://api.commpeak.com/textpeak/streams/simple_send`
- Auth: API key in header `Authorization`

Send one or more SMS messages in a single request. Each message is queued and delivered independently, so a batch can partially succeed — always inspect every item in the response.

**Senders.** Set a top-level `sender` for the whole request, a `sender` on individual messages, or both: a message's own `sender` overrides the top-level one. With neither, the stream's default sender is used.

- **Batch size:** up to 250 messages per request.
- **Correlation:** set an `internal_id` per message; it is echoed back in the response and in delivery webhooks.
- **Media:** on WhatsApp Business and Telegram streams a message can carry `media` (from **Upload file**) instead of, or with, `message_content`.

**Response.** HTTP `200` with a `task_id` and one entry per message. `status` is `false` when any message failed: failed entries come first and carry `error` (hex code) and `details`; accepted entries carry `message_uuid` (and `conversation_uuid` on two-way channels). Match entries by `internal_id`. Final delivery status is sent asynchronously to your configured webhook.

**Whole-request errors.** Invalid JSON field types return HTTP `200` with `status: false`, `error_code` `0x1` and no `task_id`. `402` (`0x41`) means the balance is depleted.

**Authentication:** stream token in the `Authorization` header (see **Authentication** in the API Overview).

## Request body

- SimpleSendRequest
  - `sender` string, nullable: Default sender for every message. An alphanumeric sender ID or a phone number registered on the stream. Omit it to use the stream's default sender.
  - `messages` SimpleSendMessage[], required: The messages to send, up to 250 per request.
    - `internal_id` string, nullable: Your identifier for the message. Echoed back in the response and in delivery webhooks (`internal_id`). Up to 36 characters are kept; longer values are cut. Not checked for uniqueness.
    - `sender` string, nullable: Sender for this message; overrides the top-level `sender`.
    - `recipient_phone` string, nullable: Recipient phone number in international format, as a string. `+`, spaces, `-` and parentheses are removed before validation. Not needed when `conversation_uuid` or `contact.phone` identifies the recipient.
    - `message_content` string, nullable: The text body. Required unless `media` is set.
    - `media` MediaRef
      - `media_id` string, required: The `media_id` returned by **Upload file**. Valid for 20 minutes after the upload has been processed; an unknown or expired ID fails the whole request with `0x17`.
    - `contact` Contact
      - `display_name` string, nullable: Name shown in the inbox. Defaults to `first_name` + `last_name`.
      - `first_name` string, nullable: First name.
      - `last_name` string, nullable: Last name.
      - `phone` string, nullable: Phone number; used as the recipient when `recipient_phone` is not set.
      - `email` string, nullable: E-mail address.
      - `external_id` string, nullable: Your CRM identifier for the contact; stored as the conversation lead ID.
      - `additional` object, nullable: Extra contact attributes. `additional.lead_id` takes precedence over `external_id`.
    - `conversation_uuid` string, nullable: Continue an existing conversation: the sender and recipient are taken from it. Two-way channels only (WhatsApp, Telegram, two-way SMS); ignored on one-way SMS.
    - `conversation_info` object, nullable: Metadata stored on new conversations (inbox). Merged over the top-level `conversation_info`.
  - `conversation_info` object, nullable: Metadata stored on new conversations (inbox).
  - `senders_pool` string[], nullable: Candidate senders, used only when no sender is set on the message, the request or the stream: a sender allowed for the destination is picked at random. When none is allowed, the whole request fails with `0x61`.
  - `schedule_to` string, nullable: Send at this time instead of now (ISO 8601 date-time).

## Response `200`

Successful Response

- SendResponse
  - `status` boolean, required: `true` when every message was accepted; `false` when at least one failed. The HTTP status is `200` either way.
  - `task_id` string, required: Identifier of this request.
  - `messages` SendResultItem[], required: One entry per message. Failed messages are listed first, then accepted ones; match them by `internal_id`.
    - `internal_id` string, nullable: Your `internal_id`, echoed back (cut to 36 characters).
    - `message_uuid` string, nullable: Platform message identifier. Accepted messages only; use it with **Get message status**.
    - `conversation_uuid` string, nullable: The conversation the message belongs to. Two-way channels only.
    - `error` string, nullable: Failed messages only: the hex error code, for example `0x1` (invalid input), `0x19` (duplicate) or `0x31` (daily limit).
    - `details` string, nullable: Failed messages only: why it failed.

## Other responses

- `401`: Invalid token, or the token is not valid from this IP address.
- `402`: Payment required: the account balance is depleted (`0x41`).
- `403`: Missing token, blocked IP address, or the stream is not available (`0x11`, `0x16`, `0x21`, `0x22`).
- `422`: Validation Error
- `500`: The request was rejected as a whole (`0x0`): for example an unknown template or more than 250 items.

---

[API](https://skmtc.dev/commpeak/apis/commpeak-textpeak-streams-api.md) - [All operations](https://skmtc.dev/commpeak/apis/commpeak-textpeak-streams-api/llms.txt) - [OpenAPI document](https://skmtc.dev/commpeak/apis/commpeak-textpeak-streams-api/revisions/b9aaa8b4efa2?raw)