---
title: "Send message"
method: POST
path: "/api/v2/messages"
tags: ["Outbound Messages"]
---

# Send message

`POST /api/v2/messages`

<a class="try-sandbox-link" href="https://sandbox.textmagic.com/#/Messages%3A%20Send%0A/sendMessage" target="_blank">Try in sandbox</a><br>This is the main entrypoint to send messages. See the examples above for the reference.

## Request body

- object
  - `text` string, required — Message text. Required if the **template_id** is not set.
  - `templateId` integer — Template used instead of message text. Required if the **text** is not set.
  - `sendingTime` integer — DEPRECATED, consider using sendingDateTime and sendingTimezone parameters instead: Optional (required with rrule set). Message sending time in unix timestamp format. Default is now.
  - `sendingDateTime` string — Sending time in Y-m-d H:i:s format (e.g. 2022-05-27 13:05:10). This time is relative to **sendingTimezone**. Note: for correct operation, the value of seconds must not be less than 10.
  - `sendingTimezone` string — ID or ISO-name of timezone used for sending when sendingDateTime parameter is set. E.g. if you specify sendingDateTime = \"2016-05-27 13:02:33\" and sendingTimezone = \"America/Buenos_Aires\", your message will be sent at May 27, 2016 13:02:33 Buenos Aires time, or 16:02:33 UTC. Default is account timezone.
  - `contacts` string — Comma separated array of contact resources id message will be sent to.
  - `lists` string — Comma separated array of list resources id message will be sent to.
  - `phones` string, required — Comma separated array of E.164 phone numbers message will be sent to.
  - `cutExtra` boolean — Should sending method cut extra characters which not fit supplied partsCount or return 400 Bad request response instead.
  - `partsCount` integer — Maximum message parts count (Textmagic allows sending 1 to 6 message parts).
  - `referenceId` integer — Custom message reference id which can be used in your application infrastructure.
  - `from` string — One of allowed Sender ID (phone number or alphanumeric sender ID). If specified Sender ID is not allowed for some destinations, a fallback default Sender ID will be used to ensure delivery. See [Get timezones](https://docs.textmagic.com/#tag/Sender-IDs).
  - `rrule` string — iCal RRULE parameter to create recurrent scheduled messages. When used, sendingTime is mandatory as start point of sending. See https://www.textmagic.com/free-tools/rrule-generator for format details.
  - `createChat` boolean — Should sending method try to create new Chat (if not exist) with specified recipients?
  - `tts` boolean — Send a Text-to-Speech message.
  - `local` boolean — Treat phone numbers passed in the \'phones\' field as local.
  - `localCountry` string — The 2-letter ISO country code for local phone numbers, used when \'local\' is set to true. Default is the account country.
  - `destination` string — Messsage destination type allowed [mms, tts].
  - `resources` string — File name from mms attachment response (named as resource)

## Response `201`

Returned when successful.

- SendMessageResponse
  - `id` integer, required — Message ID.
  - `href` string, required — URI of the message session.
  - `type` 'message' | 'session' | 'schedule' | 'bulk', required — Message response type: * **message** – when the message is sent to a single recipient. * **session** – when the message is sent is to multiple recipients. * **schedule** - when the message is scheduled for sending. * **bulk** - when the message is sent to multiple recipients and the number of recipients requires asynchronous processing See [Sending more than 1,000 messages in one session](https://docs.textmagic.com/#section/Tutorials/Sending-more-than-1000-messages-in-one-session).
  - `sessionId` integer, nullable, required — Message session ID.
  - `bulkId` integer, nullable, required — Bulk Session ID. See [Sending more than 1,000 messages in one session](https://docs.textmagic.com/#section/Tutorials/Sending-more-than-1000-messages-in-one-session).
  - `messageId` integer, nullable, required — Message ID.
  - `scheduleId` integer, nullable, required — Message Schedule ID.
  - `chatId` integer, nullable, required — Message Chat ID.

## Other responses

- `202` — Returned when a bulk session has been created.
- `400` — Bad request.
- `401` — Unauthorized request.

---

[API](https://skmtc.net/textmagic/apis/textmagic-api.md) · [All operations](https://skmtc.net/textmagic/apis/textmagic-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/textmagic/textmagic-api/revisions/3e4029d19684/schema)