Mass Messages

Send Mass Message

Sends a mass message to selected fan lists and/or individual users. Supports text, media, PPV, GIFs, scheduling, and audience filters. Requires permission api_mass_messages_send.

https://public-api.fansmetric.com

POST/v1/{account_id}/mass-messages

API keyBearer

Authorization

default

AuthorizationBearer <token>

Send your FansMetric API key as a Bearer token in the Authorization header.

In: header

Path Parameters

account_id*integer
OnlyFans numeric account ID.

Request Body

application/json

textstring
Message text (HTML supported). Sent on every call — defaults to empty string when omitted. Required unless mediaFiles or giphyId is set.
lockedTextboolean
Boolean. Hide text behind paywall. Sent on every call — defaults to false when omitted.
mediaFilesarray
Array of integers (vault media IDs). Sent on every call — defaults to [] when omitted.
pricestring
Number. PPV price in USD (0 = free, 3-200 = paid). Sent on every call — defaults to 0 when omitted.
previewsarray
Array of integers (preview media IDs for PPV, must be a subset of mediaFiles). Sent on every call — defaults to [] when omitted.
rfTagstring
Array of integers (release-form creator IDs). Sent on every call — defaults to [] when omitted.
rfGueststring
Array of integers (release-form guest IDs). Always sent — currently forced to [] server-side.
rfPartnerstring
Array of integers (release-form partner IDs). Always sent — currently forced to [] server-side.
filtersstring
Audience filters object. Sent on every call — defaults to {} when omitted. Supported keys: totalSpent, tips, duration, inactive, online, signedUpAfter, signedUpBefore.
userListsstring
Array of list IDs (string for system slugs, integer for custom lists). Only forwarded when non-empty. Required unless userIds is provided. Example: ["fans"], [47382], ["fans", 47382].
userIdsstring
Array of integers (individual user IDs). Only forwarded when non-empty. Required unless userLists is provided.
excludedListsstring
Array of list IDs (string system slug or integer custom ID). Only forwarded when non-empty.
recommendersstring
Integer. Set to 1 to send only to recommended users. Only forwarded when set.
giphyIdstring
String. Giphy GIF ID — get from /v1/gifs/trending or /v1/gifs/search. Only forwarded when set.
isScheduledstring
Integer. Set to 1 to schedule. Only forwarded when set; pairs with scheduledDate.
scheduledDatestring
ISO 8601 timestamp for the scheduled send. Only forwarded when scheduling. Required when isScheduled=1.

Response Fields

data.idinteger
Queue ID. Use this to cancel / look up the mass message.
data.datestring
ISO 8601 timestamp of creation.
data.isReadyboolean
True when the queue item is ready to send / currently sending.
data.isDoneboolean
True when sending is complete.
data.totalinteger
Total recipients. -1 or 0 while the count is still being resolved.
data.pendinginteger
Recipients still pending.
data.canUnsendboolean
Whether the mass message can still be cancelled.
data.unsendSecondsinteger
Seconds remaining to unsend.
data.hasErrorboolean
True if sending hit an error.
data.isCanceledboolean
True if the mass message was cancelled.
data.isCouplePeopleMediaboolean
True when the media contains multiple people (release-form trigger).
dataobject | array
Endpoint-specific payload. See the fields below for this route.
_meta._credits.usedinteger
Credits consumed by this request (currently always 1).
_meta._rate_limits.limit_minuteinteger
Maximum requests per minute for the organization.
_meta._rate_limits.remaining_minuteinteger
Remaining requests in the current minute window.
_meta._rate_limits.limit_dayinteger
Maximum requests per day for the organization.
_meta._rate_limits.remaining_dayinteger
Remaining requests in the current day window.

Field	Type	Description
data.id	integer	Queue ID. Use this to cancel / look up the mass message.
data.date	string	ISO 8601 timestamp of creation.
data.isReady	boolean	True when the queue item is ready to send / currently sending.
data.isDone	boolean	True when sending is complete.
data.total	integer	Total recipients. `-1` or `0` while the count is still being resolved.
data.pending	integer	Recipients still pending.
data.canUnsend	boolean	Whether the mass message can still be cancelled.
data.unsendSeconds	integer	Seconds remaining to unsend.
data.hasError	boolean	True if sending hit an error.
data.isCanceled	boolean	True if the mass message was cancelled.
data.isCouplePeopleMedia	boolean	True when the media contains multiple people (release-form trigger).
data	object \| array	Endpoint-specific payload. See the fields below for this route.
_meta._credits.used	integer	Credits consumed by this request (currently always `1`).
_meta._rate_limits.limit_minute	integer	Maximum requests per minute for the organization.
_meta._rate_limits.remaining_minute	integer	Remaining requests in the current minute window.
_meta._rate_limits.limit_day	integer	Maximum requests per day for the organization.
_meta._rate_limits.remaining_day	integer	Remaining requests in the current day window.

curl --request POST "https://public-api.fansmetric.com/v1/100000001/mass-messages" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "text": "Hello everyone!",
  "userLists": ["fans"],
  "mediaFiles": [],
  "price": 0,
  "filters": {}
}'

Response

200

{"data":{"id":10000000001
"date":"2026-05-14T18:05:07+00:00"
"isReady":true
"isDone":false
"total":1500
"pending":200
"canUnsend":true
"unsendSeconds":1000000
"hasError":false
"isCanceled":false
"isCouplePeopleMedia":false
}
"_meta":{"_credits":{"used":1
}
"_rate_limits":{"limit_minute":1000
"remaining_minute":999
"limit_day":50000
"remaining_day":49999
}
}
}

Mass Message Statistics

List Mass Message Fan Lists