---
title: "Create inbox broadcast message"
method: POST
path: "/apps/{app_id}/inbox"
---

# Create inbox broadcast message

`POST /apps/{app_id}/inbox`

## Request

- Base URL: `https://api.onesignal.com`
- URL: `https://api.onesignal.com/apps/{app_id}/inbox`
- Auth: none required

Broadcast a message to users' inboxes.

## Path parameters

- `app_id` string, required

## Headers

- `Authorization` string, required

## Request body

- object
  - `name` string, required: An internal name you set to help organize and track messages. Not shown to recipients. Maximum 128 characters. Required, and must be non-empty.
  - `img_url` string: The URL to an image that is associated with this message.
  - `contents` object: The main message body with [language-specific values](/docs/en/multi-language-messaging#supported-languages). Supports [Message Personalization](/docs/en/message-personalization).
    - `en` string, required: The required message language type. See [Supported Languages](/docs/en/multi-language-messaging#supported-languages).
  - `subjects` object, required: The message's localized subjects, as a map of language codes to subjects. Each entry must have a language code as its key, mapped to the localized subject you would like users to receive for that language. Any language codes used must also be used within the contents property. This field supports tag substitutions and liquid syntax. Required, and must be non-empty. Example: `{"en": "English Title", "es": "Spanish Title"}`
    - `en` string
  - `send_after` string: Schedule delivery for a future date/time (in UTC). The format must be valid per the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) standard and compatible with [`JavaScript's Date() parser`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/Date#datestring). Example: `2025-09-24T14:00:00-07:00`
  - `data` string: An arbitrary string (which can contain encoded JSON if desired) that is passed through to messages. This is meant for use in client applications and is not processed in any special way by OneSignal. If you need structured data, encode it as a JSON string. Example: `"{\"abc\":\"123\"}"`
  - `custom_data` object: Include user or context-specific data (e.g., cart items, OTPs, links) in a message. Use with `template_id`. See [Message Personalization](/docs/en/message-personalization). Max size: 2KB (Push/SMS), 10KB (Email).
    - `key` string: JSON object that can be used as a source of message personalization data for fields that support tag variable substitution. Initially can accept up to 2,048 bytes of valid JSON. Example: {"order_id": 123, "currency": "USD", "amount": 25}. See [Message Personalization](/docs/en/message-personalization)

## Response `200`

200

- object
  - `id` string: The message ID in UUID v4 format.

## Other responses

- `429`: Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.
- `503`: Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.

## Changes

- **2026-11-03** `36dfd39b1be3`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/onesignal/apis/api-onesignal-com/changes/apps/:app_id/inbox/post.md)

---

[API](https://skmtc.dev/onesignal/apis/api-onesignal-com.md) - [All operations](https://skmtc.dev/onesignal/apis/api-onesignal-com/llms.txt) - [OpenAPI document](https://skmtc.dev/onesignal/apis/api-onesignal-com/revisions/36dfd39b1be3?raw)