Skip to main content
Send or schedule a message for selected fans or user lists. The API adds the message to a queue and returns its ID. Save that ID to check progress or cancel the send.

Before you start

Ask the user to authorize your app with messages:write to send messages. Also request queue:read to check progress and queue:write to cancel. These scopes are permissions. Use the returned token and select a linked account the user shared with your app. Install the TypeScript SDK version 4. Create a client on your server:
Use this client for the rest of this guide. The SDK sends the access token and linked account ID for you.

Choose recipients

Use fan IDs for userIds and user-list IDs for userLists. These are different from the linked account ID in the request header. Read /v3/access/lists for available user lists. Its response uses items and page. Choose userIds for individual fans or userLists for saved groups. Both fields accept numeric IDs or IDs written as strings. A string cannot be empty.
Save queued.id. It is the mass message ID that every later step uses (see Mass message IDs). The response includes these queue status fields: id, date, isReady, isDone, total, pending, canUnsend, unsendSeconds, hasError, and isCanceled. Only create and update return total, pending, and isDone. The message has entered the queue. Delivery to every fan may not be complete yet. If you set userTags or releaseForms, also save them. You need them to update the message later, because the read does not return them in request form. Everything else, including the recipients, can be read back.

Send to lists and exclude groups

Pass this object as body to client.access.chats.massMessages.create():
excludeUserLists excludes lists, not individual user IDs. To exclude specific fans, put them in an excluded list or leave them out of userIds. The request does not accept excludeUserIds.

Attach paid content and schedule delivery

Use a future ISO timestamp with a timezone. Omit scheduledDate for immediate delivery. Put preview media first. An upload reference works for one successful post, message, or mass message. Use numeric Vault IDs to reuse media. The content options match individual messages: text, mediaItems, price, previewMediaCount, isLockedText, isMarkdown, replyToMessageId, releaseForms, userTags, and isForwardedMessage.

Mass message IDs

The id returned by create is the mass message’s queue ID. The routes give it different names, but it is the same value: A schedule ID is different. client.access.queue.schedules.list() returns queue items whose id is the scheduleId for PUT /v3/access/queue/schedules/:scheduleId/publish. For an item with type: "chat", entity.queueId is the mass message ID.

Track delivery and purchases

The sent analytics route accepts startDate, endDate, and cursor. Buyers accept limit and cursor. Check the returned fields in the API reference before using the analytics.

Update a queued message

client.access.chats.massMessages.update() replaces the whole message. Fields you leave out return to their defaults: leave out price and the message becomes free; leave out scheduledDate and it is no longer scheduled. Always send the full message. Read the queued message and send its fields back. The recipient fields use the same names as the request, so you can copy them unchanged:
Leave out a recipient field only when the read leaves it out. The response’s releaseForms array is OnlyFans’ own format, not the request’s users/partners/guests object, so do not send it back as-is. Even though the read returns the recipients, still send the full message on every update.

Cancel a queued message

To cancel, call client.access.queue.deleteMessage({ queueMessageId: 987654 }). This sends DELETE /v3/access/queue/messages/987654. There is no DELETE operation at /chats/mass-messages/:massMessageId. First read the message with client.access.queue.getMessage() and check that canUnsend is true. unsendSeconds is the time left to cancel. Do not assume you can cancel a message after delivery. Read V3 errors before retrying a creation request. Use the saved queue ID to check progress. Do not create another mass message to check whether the first one was sent.