ONonlymonster
mass-messages

Send a Mass Message from an account

Changed on

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

post/api/v0/accounts/{account_id}/mass-messages

Request

  • Base URL
    https://omapi.onlymonster.ai
  • Auth
    API key in header x-om-auth-token

Path parameters

account_idstring required

OnlyMonster account whose Mass Messages are addressed.

Request body

textstring 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_paidboolean 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.

giphy_idstring required

Identifier of the GIF to send, or null to send none.

user_list_idsstring[] 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_idsstring[] required

Fan lists to leave out of the audience. Empty to leave out none.

tagged_platform_account_idsstring[] required

Platform accounts to tag in this message, by their identifier on the platform.

scheduled_atstring 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.

Example request

{
  "attachments": [
    {
      "id": "1289402"
    }
  ],
  "user_list_ids": [
    "1176334622"
  ],
  "excluded_user_list_ids": [
    "1176334622"
  ],
  "tagged_platform_account_ids": [
    "1"
  ],
  "scheduled_at": "2026-11-05T10:00:00Z"
}

Response

The queue state of the Mass Message that was just sent.

idstring 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_atstring date-time required

When the Mass Message was queued.

targeted_recipients_countinteger required

Fans the Mass Message is going out to. Null while the platform is still counting the audience.

pending_messages_countinteger required

Messages of this Mass Message still waiting to be sent.

can_unsendboolean required

True while the Mass Message can still be taken back.

unsend_window_secinteger required

Seconds the platform allows a Mass Message to be taken back within.

scheduled_atstring date-time required

When the platform sends the Mass Message, in UTC. Null for a Mass Message sent right away.

Example response

{
  "id": "4312"
}

Changes