---
title: "Send a message to a single recipient"
method: POST
path: "/v1/messages"
tags: ["Messages"]
---

# Send a message to a single recipient

`POST /v1/messages`

Sends a message to a single recipient. Supported recipient types: device, resourceGroup, webUser, resourceGroupMobile, resourceMobile, userMobile, userEmail, email, mobileNumber. (required scope messages:write)

## Headers

- `Customer-Id` integer, required

## Request body

- SendMessageModel — Represents the request body for sending a message
  - `recipientType` 'device' | 'resourceGroup' | 'webUser' | 'resourceGroupMobile' | 'resourceMobile' | 'userMobile' | 'userEmail' | 'email' | 'mobileNumber', required — The type of recipient for a message.<p>Possible values:</p><ul><li><b>device</b>: A tracked device assigned to a resource</li><li><b>resourceGroup</b>: A resource group (all devices in the group)</li><li><b>webUser</b>: A web user</li><li><b>resourceGroupMobile</b>: A resource group (SMS to all mobiles in the group)</li><li><b>resourceMobile</b>: A resource — sends SMS to the resource's mobile number</li><li><b>userMobile</b>: A web user — sends SMS to the user's mobile number</li><li><b>userEmail</b>: A web user — sends an email to the user's email address</li><li><b>email</b>: An arbitrary email address supplied in</li><li><b>mobileNumber</b>: An arbitrary mobile number supplied in</li></ul>
  - `recipientId` integer, nullable — The unique identifier of the recipient.<br/>Required for entity-based recipient types: device, resourceGroup, webUser, resourceGroupMobile, resourceMobile, userMobile, userEmail
  - `recipientAddress` string, nullable — The recipient address.<br/>Required for address-based recipient types: email (supply a valid email address), mobileNumber (supply a number in international format, e.g. +44 7777 123456)
  - `body` string — The message body. Maximum 1000 characters
  - `subject` string, nullable — The message subject. Maximum 50 characters. Optional — ignored for SMS recipient types (resourceMobile, userMobile, resourceGroupMobile)

## Response `201`

Created

- SendMessageResponseModel — Represents the response body returned after a message is sent
  - `messageId` integer — The unique identifier for the sent message
  - `status` string — The delivery status of the message. Possible values: queued, sent, failed
  - `sentAt` string, date-time — The UTC timestamp at which the message was sent

## Other responses

- `400` — Bad Request
- `403` — Forbidden
- `422` — Unprocessable Content
- `500` — Internal Server Error

---

[API](https://skmtc.net/bigchange/apis/bigchange-dx.md) · [All operations](https://skmtc.net/bigchange/apis/bigchange-dx/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/bigchange/bigchange-dx/revisions/916e669fc527/schema)