---
title: "Send a message to a user."
method: POST
path: "/api/v1/messages"
tags: ["Messages"]
---

# Send a message to a user.

`POST /api/v1/messages`

Sends a message to one of your users on the selected channels (in-app inbox, mobile push, email, SMS). The user must belong to your operator.<br/><br/>Messages do not support the `partnerExternalId` / `partnerCustomPayload` custom-data fields (§11) — they are transient delivery records rather than partner-managed entities.<br/><br/>Clients may send an `Idempotency-Key` header for safe retry semantics; the header is currently accepted and ignored (no enforcement yet).<br/><br/>Required scope: `messages:write`

## Headers

- `Idempotency-Key` string

## Request body

- SendMessageRequest — A message to send to one of your users.
  - `recipientUserId` integer — Id of the user to send the message to. The user must belong to your operator.
  - `body` string, required — The message body. 1–4096 characters.
  - `subject` string, nullable — Optional subject / title. Up to 140 characters. Used as the push/email title; falls back to a default when omitted.
  - `actionUrl` string, nullable — Optional deep link opened from the message. Must be an `https://` URL, a `monta-app://` deeplink, or an internal `/path`.
  - `channels` MessageChannels, required — The channels a message is delivered on. The in-app inbox is on by default; push, email, and SMS are opt-in. At least one channel must be enabled.
    - `webInbox` boolean — Deliver to the user's in-app inbox.
    - `mobilePush` boolean — Deliver as a mobile push notification.
    - `email` boolean — Deliver as an email.
    - `sms` boolean — Deliver as an SMS.

## Response `201`

The message was accepted and is being delivered

- Message — A message your operator sent to a user. Note: messages do not support the `partnerExternalId` / `partnerCustomPayload` custom-data fields (§11) — they are transient delivery records, not partner-managed entities.
  - `id` string, required — Id of the message.
  - `recipientUserId` integer — Id of the user the message was sent to.
  - `body` string, required — The message body.
  - `subject` string, nullable — Subject / title, if one was set.
  - `actionUrl` string, nullable — Deep link carried by the message, if any.
  - `channels` MessageChannels, required — The channels a message is delivered on. The in-app inbox is on by default; push, email, and SMS are opt-in. At least one channel must be enabled.
    - `webInbox` boolean — Deliver to the user's in-app inbox.
    - `mobilePush` boolean — Deliver as a mobile push notification.
    - `email` boolean — Deliver as an email.
    - `sms` boolean — Deliver as an SMS.
  - `deliveryResults` MessageDeliveryResults, required — Per-channel delivery outcome. A channel is absent until its delivery is attempted.
    - `webInbox` MessageDeliveryStatus — Delivery outcome for a single channel.
      - `status` 'queued' | 'delivered' | 'failed' | 'token_invalid' | 'rate_limited' | 'skipped', required — Delivery status.
      - `at` string, date-time, required — When this status was recorded.
    - `mobilePush` MessageDeliveryStatus — Delivery outcome for a single channel.
      - `status` 'queued' | 'delivered' | 'failed' | 'token_invalid' | 'rate_limited' | 'skipped', required — Delivery status.
      - `at` string, date-time, required — When this status was recorded.
    - `email` MessageDeliveryStatus — Delivery outcome for a single channel.
      - `status` 'queued' | 'delivered' | 'failed' | 'token_invalid' | 'rate_limited' | 'skipped', required — Delivery status.
      - `at` string, date-time, required — When this status was recorded.
    - `sms` MessageDeliveryStatus — Delivery outcome for a single channel.
      - `status` 'queued' | 'delivered' | 'failed' | 'token_invalid' | 'rate_limited' | 'skipped', required — Delivery status.
      - `at` string, date-time, required — When this status was recorded.
  - `readAt` string, date-time, nullable — When the recipient read the message, or null if unread.
  - `createdAt` string, date-time, required — When the message was created.

## Other responses

- `400` — The request is invalid
- `401` — Consumer with provided credentials was not found
- `403` — Operator doesn't have access to resource
- `404` — Entity with the provided id was not found

---

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