> ## Documentation Index
> Fetch the complete documentation index at: https://api.fanvue.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# List mass messages
> Returns a paginated list of mass (broadcast) messages sent by the authenticated creator, including delivery and engagement statistics.
Each item includes recipient count, view count, purchase count, and total revenue generated.
Use the `includeDeleted` query parameter to also retrieve deleted (unsent) mass messages. Deleted messages will have a status of `UNSENT`.
This endpoint is only available to creators.
**Required scope**
* `read:chat` — Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.
## OpenAPI
````yaml /openapi.json get /chats/mass-messages
openapi: 3.1.0
info:
title: Fanvue API
version: '0.1'
servers: []
security: []
paths:
/chats/mass-messages:
get:
summary: List mass messages
description: >-
Returns a paginated list of mass (broadcast) messages sent by the
authenticated creator, including delivery and engagement statistics.
Each item includes recipient count, view count, purchase count, and
total revenue generated.
Use the `includeDeleted` query parameter to also retrieve deleted
(unsent) mass messages. Deleted messages will have a status of `UNSENT`.
This endpoint is only available to creators.
operationId: listMassMessages
parameters:
- $ref: '#/components/parameters/ApiVersionHeader'
- schema:
type: number
minimum: 1
default: 1
description: Page number to retrieve (starts from 1)
required: false
description: Page number to retrieve (starts from 1)
name: page
in: query
- schema:
type: number
minimum: 1
maximum: 50
default: 15
description: 'Number of items to return per page (1-50, default: 15)'
required: false
description: 'Number of items to return per page (1-50, default: 15)'
name: size
in: query
- schema:
type: string
enum:
- 'true'
- 'false'
default: 'false'
description: >-
Whether to include deleted (unsent) mass messages in the results.
Defaults to false.
required: false
description: >-
Whether to include deleted (unsent) mass messages in the results.
Defaults to false.
name: includeDeleted
in: query
responses:
'200':
description: List of mass messages with statistics
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
uuid:
type: string
format: uuid
text:
type:
- string
- 'null'
status:
type: string
enum:
- SENT
- UNSENT
- SENDING
- FAILED
- MODERATED
- SCHEDULED
description: Current status of the mass message
price:
type:
- number
- 'null'
description: >-
Price in cents for pay-to-view content, or null if
free
createdAt:
type:
- string
- 'null'
format: date
publishedAt:
type:
- string
- 'null'
format: date
description: When the message was published/sent
scheduledAt:
type:
- string
- 'null'
format: date
description: >-
When the message is scheduled to send, or null for
non-scheduled messages
recipientCount:
type: number
description: Number of recipients the message was sent to
viewCount:
type: number
description: Number of recipients who have viewed the message
purchaseCount:
type: number
description: >-
Number of recipients who purchased the pay-to-view
content
totalRevenue:
type: number
description: >-
Total revenue generated from purchases of this
message (in cents)
mediaUuids:
type: array
items:
type: string
format: uuid
description: >-
Ordered list of media UUIDs attached to this mass
message (display order)
includedLists:
type: object
properties:
smartListIds:
type: array
items:
type: string
enum:
- subscribers
- auto_renewing
- non_renewing
- followers
- free_trial_subscribers
- expired_subscribers
- spent_more_than_50
- muted
- creators
smartListUuids:
type: array
items:
type: string
enum:
- subscribers
- auto_renewing
- non_renewing
- followers
- free_trial_subscribers
- expired_subscribers
- spent_more_than_50
- muted
- creators
description: >-
Deprecated alias of `smartListIds`. Will be
removed in a future API version.
customListUuids:
type: array
items:
type: string
format: uuid
required:
- smartListIds
- smartListUuids
- customListUuids
description: >-
Smart and custom lists the mass message was sent to.
Inner arrays are empty when none were used.
excludedLists:
type: object
properties:
smartListIds:
type: array
items:
type: string
enum:
- subscribers
- auto_renewing
- non_renewing
- followers
- free_trial_subscribers
- expired_subscribers
- spent_more_than_50
- muted
- creators
smartListUuids:
type: array
items:
type: string
enum:
- subscribers
- auto_renewing
- non_renewing
- followers
- free_trial_subscribers
- expired_subscribers
- spent_more_than_50
- muted
- creators
description: >-
Deprecated alias of `smartListIds`. Will be
removed in a future API version.
customListUuids:
type: array
items:
type: string
format: uuid
required:
- smartListIds
- smartListUuids
- customListUuids
description: >-
Smart and custom lists excluded from the mass
message. Inner arrays are empty when none were used.
required:
- uuid
- text
- status
- price
- createdAt
- publishedAt
- scheduledAt
- recipientCount
- viewCount
- purchaseCount
- totalRevenue
- mediaUuids
- includedLists
- excludedLists
description: >-
Array of mass messages with delivery and engagement
statistics
pagination:
type: object
properties:
page:
type: number
description: Current page number
size:
type: number
description: Number of records returned in this response
hasMore:
type: boolean
description: >-
Whether there are more items available on subsequent
pages
required:
- page
- size
- hasMore
description: Pagination information
required:
- data
- pagination
example:
data:
- uuid: d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90
text: Hey everyone! Check out my new exclusive content 🔥
status: SENT
price: 500
createdAt: '2024-01-15T00:00:00.000Z'
publishedAt: '2024-01-15T00:00:00.000Z'
scheduledAt: null
recipientCount: 1250
viewCount: 890
purchaseCount: 156
totalRevenue: 78000
mediaUuids:
- a1b2c3d4-e5f6-7890-abcd-ef1234567890
includedLists:
smartListIds:
- subscribers
- auto_renewing
smartListUuids:
- subscribers
- auto_renewing
customListUuids:
- f1e2d3c4-b5a6-9788-c0d1-e2f3a4b5c6d7
excludedLists:
smartListIds: []
smartListUuids: []
customListUuids: []
- uuid: e5f6a7b8-c9d0-1e2f-3a4b-5c6d7e8f9012
text: Good morning! Hope you all have a great day ☀️
status: SENT
price: null
createdAt: '2024-01-14T00:00:00.000Z'
publishedAt: '2024-01-14T00:00:00.000Z'
scheduledAt: null
recipientCount: 1180
viewCount: 720
purchaseCount: 0
totalRevenue: 0
mediaUuids: []
includedLists:
smartListIds:
- followers
smartListUuids:
- followers
customListUuids: []
excludedLists:
smartListIds:
- muted
smartListUuids:
- muted
customListUuids: []
pagination:
page: 1
size: 2
hasMore: true
'400':
description: Bad Request - API version not supported OR validation failed
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/UnsupportedVersionError'
- $ref: '#/components/schemas/ValidationError'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/UnauthorizedResponse'
'410':
$ref: '#/components/responses/SunsetVersionResponse'
'429':
$ref: '#/components/responses/RateLimitResponse'
security:
- BearerAuth:
- read:chat
components:
parameters:
ApiVersionHeader:
name: X-Fanvue-API-Version
in: header
required: true
schema:
type: string
default: '2025-06-26'
example: '2025-06-26'
description: API version to use for the request
schemas:
UnsupportedVersionError:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
- message
description: API version not supported
ValidationError:
type: object
properties:
errors:
type: array
items:
type: string
required:
- errors
description: Request validation failed
responses:
UnauthorizedResponse:
description: Unauthorized Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
required:
- error
SunsetVersionResponse:
description: API version no longer supported (sunset)
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
nextVersion:
type: string
required:
- error
- message
RateLimitResponse:
description: Too many requests - rate limit exceeded
headers:
Retry-After:
description: Number of seconds to wait before retrying the request
schema:
type: integer
X-RateLimit-Limit:
description: The maximum number of requests allowed in the current window
schema:
type: integer
X-RateLimit-Remaining:
description: The number of requests remaining in the current window
schema:
type: integer
X-RateLimit-Reset:
description: The Unix timestamp (seconds) when the rate limit window resets
schema:
type: integer
content:
application/json:
schema:
type: object
properties:
error:
type: string
required:
- error
securitySchemes:
BearerAuth:
type: oauth2
description: >-
OAuth 2.0 access token, presented as a JWT bearer token in the
`Authorization` header. Obtain a token via the authorization-code flow;
the scopes granted to the token determine which operations it may call.
flows:
authorizationCode:
authorizationUrl: https://auth.fanvue.com/oauth2/auth
tokenUrl: https://auth.fanvue.com/oauth2/token
refreshUrl: https://auth.fanvue.com/oauth2/token
scopes:
read:self: >-
Access your own user profile information, including basic account
details and settings.
read:chat: >-
Read chat conversations, messages, and chat-related data. This
includes viewing chat lists and message history.
write:chat: >-
Create new chats and send messages. This scope is required for any
chat-related actions that modify data.
read:experience: >-
Exchange a fan's experience token for the resolved experience and
the fan's identity, so an embedded fan-facing experience can
render the right content.
write:experience: >-
Request that the creator publish or unpublish a fan-facing
experience. The app mints a request token; the creator confirms
and Fanvue performs the change.
read:fan: Access fan-related data and information within the platform.
read:post: Read posts, including post details, comments, likes, and tips.
write:post: Create, edit, and manage posts and content on behalf of users.
read:media: Access media files, images, videos, and other content assets.
write:media: >-
Upload, modify, and manage media files and content assets. Also
required for vault folder management.
read:creator: >-
Access creator profiles, content, and creator-specific
information.
write:creator: Modify creator profiles, settings, and creator-specific data.
read:insights: >-
Access analytics, metrics, and insights data for performance
tracking.
read:tracking_links: >-
Read tracking links and the users associated with them, including
per-user tracking metadata.
write:tracking_links: Create and delete tracking links.
read:agency: Read agency information, including the agency's team members.
write:agency: >-
Manage agency team members and invites, including inviting new
team members and creators.
````