---
title: "Retrieve the Mass Messages of an account"
method: GET
path: "/api/v0/accounts/{account_id}/mass-messages"
tags: ["mass-messages"]
---

# Retrieve the Mass Messages of an account

`GET /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

Pagination is by cursor: set `to` to the `created_at` of the last item of the page just read. The cursor has one-second precision — deduplicate by `id`.

The first page starts with every scheduled Mass Message, soonest first, then every Mass Message still sending, then the history newest first. The scheduled and sending ones are not counted against `limit`, so the first page may hold more than `limit` items. It is the only page that carries `total`; `total` reads `null` on every page after it.

**Required permission:** `mass_messages.view`

## Path parameters

- `account_id` string, required

## Query parameters

- `limit` integer
- `to` string, date-time

## Response `200`

A page of the account's Mass Messages. The first page starts with every scheduled message, soonest first, then every message still sending, then the history newest first; the scheduled and sending ones are not counted against `limit`, so it may hold more than `limit` items.

- object: A page of the account's Mass Messages. The first page starts with every scheduled message, soonest first, then every message still sending, then the history newest first; the scheduled and sending ones are not counted against `limit`, so it may hold more than `limit` items.
  - `items` object[], required
    - `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.
    - `can_unsend` boolean, required: True while the Mass Message can still be taken back.
    - `created_at` string, date-time, required: When the Mass Message was queued.
    - `created_by` object, required: Who sent the Mass Message: `user` with the identifier of the member, `api_key` with the identifier of the API key, resolvable through `GET /api/v0/api-keys`. `null` when the author is unknown.
      - `type` 'user' | 'api_key', required
      - `id` string, required
    - `scheduled_at` string, date-time, required: When the platform sends the Mass Message, in UTC. Null for a Mass Message sent right away.
    - `message` object, required: The content of a Mass Message.
      - `text` string, required: Text the fan receives. Null when the message carries none.
      - `text_is_paid` boolean, required: Whether the text sits behind the paywall. Null when it is not known for this message.
      - `price_gross` number, required: Price the fan pays for this message, before any platform deduction. Null when it is not known for this message.
      - `attachments` object[], required: Media attached to the message. Empty when it carries none.
        - `id` string, required: Identifier of the media on the platform.
        - `type` 'image' | 'video' | 'audio', required: Kind of media attached.
        - `is_paid` boolean, required: Whether the attachment sits behind the paywall. Null when the paid/free split is not known for this message.
      - `giphy_id` string, required: Identifier of the GIF sent with the message. Null when it carries none.
      - `user_list_ids` string[], required: Fan lists the message was sent to, as identifiers. Null when they are not known for this message.
      - `excluded_user_list_ids` string[], required: Fan lists left out of the audience, as identifiers. Null when they are not known for this message.
      - `tagged_platform_account_ids` string[], required: Platform accounts tagged in the message. Null when they are not known for this message.
    - `stats` object, required
      - `sent_messages_count` integer, required: Messages the platform has sent.
      - `viewed_messages_count` integer, required: Messages a fan has opened.
      - `purchased_messages_count` integer, required: Messages a fan has paid for.
      - `purchased_amount_gross` number, required: Price times purchases, before any platform deduction.
  - `has_more` boolean, required: True when more Mass Messages exist beyond this page.
  - `total` integer, required: The account's number of Mass Messages. Null on every page after the first.

## Other responses

- `400`: The request states something this endpoint cannot accept: a query value outside its bounds, or an account that is not an OnlyFans account. 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.
- `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. Repeating it is safe.
- `502`: The request failed for a reason that is not about the request.

## 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/get.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)