--- title: "Send a Mass Message from an account" method: POST path: "/api/v0/accounts/{account_id}/mass-messages" tags: ["mass-messages"] --- # Send a Mass Message from an account `POST /api/v0/accounts/{account_id}/mass-messages` ## Request - Base URL: `https://omapi.onlymonster.ai` - URL: `https://omapi.onlymonster.ai/api/v0/accounts/{account_id}/mass-messages` - Auth: API key in header `x-om-auth-token` **Rate limit:** 5 requests per second **A send is a real broadcast to every fan of the selected lists, not a draft, and this endpoint is not idempotent.** A send without `scheduled_at` is never refused as a duplicate: sending it again, a retry after a timeout or a `502` included, is a second Mass Message to every one of those fans. Only a send with `scheduled_at` repeated within 45 s is refused with a `409`; after that, it is a second scheduled Mass Message. With `scheduled_at` the platform holds the Mass Message and sends it at that moment. Until then it lists as `scheduled`; the unsend endpoint cancels it. A `502` means whether the Mass Message went out is unknown: list the Mass Messages of the account before retrying, and unsend a duplicate while the platform window allows it. Listing or reading a Mass Message needs `mass_messages.view` in addition to `mass_messages.edit`. **Required permission:** `mass_messages.edit` ## Path parameters - `account_id` string, required ## Request body - object - `text` string, required: Text the fan receives. Null for a message that carries only media or a GIF. A message carries text, at least one attachment, or a GIF. - `text_is_paid` boolean, required: True to put the text itself behind the paywall, so the fan buys the message to read it. Requires text that is not empty or whitespace. - `price_gross` union, required: Price the fan pays for this message, before any platform deduction. 0 makes it free; any other amount is between 3 and 200. A price requires something behind the paywall — `text_is_paid` or an attachment with `is_paid` — and either of those requires a price. - 0 - number - `attachments` object[], required: Media to attach. Empty for a message that carries none. A GIF is not an attachment — it travels as `giphy_id`. - `id` string, required: Identifier of the media on the platform. - `type` 'image' | 'video' | 'audio', required: Kind of media being attached. - `is_paid` boolean, required: True to put the attachment behind the paywall, hiding it from the preview the fan sees before paying. - `giphy_id` string, required: Identifier of the GIF to send, or null to send none. - `user_list_ids` string[], required: Fan lists this message is sent to, up to 100. Empty to send to every fan except the excluded lists; at least one list is stated here or in `excluded_user_list_ids`. - `excluded_user_list_ids` string[], required: Fan lists to leave out of the audience. Empty to leave out none. - `tagged_platform_account_ids` string[], required: Platform accounts to tag in this message, by their identifier on the platform. - `scheduled_at` string, date-time: When the platform should send the Mass Message, as an ISO 8601 date-time with an offset (`Z` for UTC). The value is read as an instant and stored in UTC. Seconds and milliseconds are dropped, since the platform keeps the minute, and the response carries that minute. It must be at least one minute and at most one year ahead, counted from that minute. Omit to send right away. Refused with 400 while scheduling is not enabled for the organisation. A scheduled Mass Message lists as `scheduled` until then and is cancelled with the unsend endpoint. ## Response `201` The queue state of the Mass Message that was just sent. - object: The queue state of the Mass Message that was just sent. - `id` string, required: Identifier of the Mass Message. - `status` 'scheduled' | 'sending' | 'done' | 'unsent', required: Where the Mass Message stands: `scheduled` while it waits for `scheduled_at`, `sending` while the platform is still delivering it, `done` once every message has gone out, `unsent` once it has been taken back. A `scheduled` Mass Message is cancelled with the unsend endpoint. - `created_at` string, date-time, required: When the Mass Message was queued. - `targeted_recipients_count` integer, required: Fans the Mass Message is going out to. Null while the platform is still counting the audience. - `pending_messages_count` integer, required: Messages of this Mass Message still waiting to be sent. - `can_unsend` boolean, required: True while the Mass Message can still be taken back. - `unsend_window_sec` integer, required: Seconds the platform allows a Mass Message to be taken back within. - `scheduled_at` string, date-time, required: When the platform sends the Mass Message, in UTC. Null for a Mass Message sent right away. - `created_by` object, required: The API key that made this request. - `type` 'api_key', required - `id` string, required: Identifier of the API key that sent the Mass Message. ## Other responses - `400`: The request states something this endpoint cannot accept: a value outside its bounds, a message whose price and paywall disagree, a message that carries nothing, an account that is not an OnlyFans account, an account past its daily Mass Message limit on the platform, a `scheduled_at` while scheduling is not enabled for the organisation, or a send the platform refused. A refusal this endpoint decides itself carries no code. - `401`: The token is missing or invalid. - `403`: The API key lacks the permission this endpoint requires, or the request is outside what the organisation or the API key can access. - `409`: The same Mass Message with `scheduled_at` was sent from this account within the last 45 s. Nothing was scheduled the second time. A send without `scheduled_at` is never refused as a duplicate. - `422`: The account's platform session or proxy cannot be used. - `429`: A rate limit was exceeded: the token or per-endpoint limit of this API, or the platform's limit on the account. - `500`: The request failed for a reason this API does not describe. The Mass Message may still have gone out: list the Mass Messages of the account before retrying. - `502`: The send failed or could not be confirmed. Whether the Mass Message went out is unknown — list the account's Mass Messages before retrying, and take a duplicate back while the window allows. ## Changes - **2026-11-03** `20f58411c6c5`: 1 info - endpoint added [Operation history](https://skmtc.dev/onlymonster/apis/om-api-service/changes/api/v0/accounts/:account_id/mass-messages/post.md) --- [API](https://skmtc.dev/onlymonster/apis/om-api-service.md) - [All operations](https://skmtc.dev/onlymonster/apis/om-api-service/llms.txt) - [OpenAPI document](https://skmtc.dev/onlymonster/apis/om-api-service/revisions/0003edb0288a?raw)