> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ofauth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Send a mass message

> Target fans and lists, schedule delivery, and track mass messages

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](https://docs.ofauth.com/v3/guides/link.md) 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](https://docs.ofauth.com/v3/sdk/typescript.md) version 4. Create a client on your server:

```typescript theme={null}
import { OFAuthClient } from "@ofauth/onlyfans-sdk"

const client = new OFAuthClient({
	accessToken: process.env.ACCESS_TOKEN!,
	linkedAccountId: process.env.LINKED_ACCOUNT_ID!
})
```

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.

```typescript theme={null}
const queued = await client.access.chats.massMessages.create({
	body: {
		text: "New content is available.",
		userIds: [123456, 234567]
	}
})
```

Save `queued.id`. It is the mass message ID that every later step uses (see [Mass message IDs](#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()`:

```json theme={null}
{
	"text": "An update for recent subscribers",
	"userLists": [101],
	"excludeUserLists": [202],
	"subscribedAfterDate": "2026-10-01T00:00:00.000Z"
}
```

`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

```json theme={null}
{
	"text": "The new set",
	"userLists": [101],
	"mediaItems": [789, 790],
	"price": 9.99,
	"previewMediaCount": 1,
	"scheduledDate": "2027-01-10T18:00:00.000Z"
}
```

Use a future ISO timestamp with a timezone. Omit `scheduledDate` for immediate delivery. Put preview media first. An [upload reference](https://docs.ofauth.com/v3/guides/media-items.md) works for one successful post, message, or mass message. Use numeric Vault IDs to reuse media.

The content options match [individual messages](https://docs.ofauth.com/v3/guides/messaging.md): `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:

| Name | Where |
| - | - |
| `id` | Create response |
| `massMessageId` | `GET` and `PUT /v3/access/chats/mass-messages/:massMessageId`, `/v3/access/analytics/mass-messages/:massMessageId/buyers`, and the `massMessageId` field of the read responses |
| `queueMessageId` | `GET` and `DELETE /v3/access/queue/messages/:queueMessageId` |
| `queueId` | Field of the read responses and of a chat schedule's `entity` |

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

| Method | Route | Returns |
| - | - | - |
| `GET` | `/v3/access/queue/messages/:queueMessageId` | The queued message: content, `price`, `previewMediaCount`, `scheduledDate`, recipients (`userIds`, `userLists`, `excludeUserLists`, `subscribedAfterDate`), `canUnsend`, `unsendSeconds` |
| `GET` | `/v3/access/chats/mass-messages/:massMessageId` | The message as a chat message, with `price`, `previewMediaCount`, `canUnsend`, `unsendSeconds`. No schedule or recipients |
| `GET` | `/v3/access/analytics/mass-messages/sent` | Sent mass messages with counts |
| `GET` | `/v3/access/analytics/mass-messages/:massMessageId/buyers` | Fans who bought the message |

The sent analytics route accepts `startDate`, `endDate`, and `cursor`. Buyers accept `limit` and `cursor`. Check the returned fields in the [API reference](https://docs.ofauth.com/v3/api-reference.md) 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:

```typescript theme={null}
const current = await client.access.queue.getMessage({ queueMessageId: 987654 })
const previewIds = new Set(current.previewIds)
const mediaIds = current.media.map((media) => media.id)

await client.access.chats.massMessages.update({
	massMessageId: 987654,
	body: {
		text: current.text,
		isMarkdown: false,
		mediaItems: [
			...mediaIds.filter((id) => previewIds.has(id)),
			...mediaIds.filter((id) => !previewIds.has(id))
		],
		previewMediaCount: current.previewMediaCount,
		price: Number(current.price ?? 0),
		isLockedText: current.lockedText,
		scheduledDate: current.scheduledDate,
		userIds: current.userIds,
		userLists: current.userLists,
		excludeUserLists: current.excludeUserLists,
		subscribedAfterDate: current.subscribedAfterDate
		// Add userTags and releaseForms from your saved request if you set them.
	}
})
```

| Request field | Read from |
| - | - |
| `text` | `text`. It is HTML, so send `isMarkdown: false`. `rawText` has the plain text |
| `mediaItems` | `media[].id`, with preview media (`previewIds`) first |
| `previewMediaCount` | `previewMediaCount` |
| `price` | `price`. May be a number or a numeric string |
| `isLockedText` | `lockedText` |
| `scheduledDate` | `scheduledDate` |
| `userIds` | `userIds`. Empty when you sent to lists |
| `userLists` | `userLists`. List IDs; absent when you sent only to `userIds`. `userListDetails` adds list names when OnlyFans returns them |
| `excludeUserLists` | `excludeUserLists`. Absent when no list is excluded |
| `subscribedAfterDate` | `subscribedAfterDate`. Absent when not set |
| `userTags`, `releaseForms` | Not returned in request form. Use your saved request |

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](https://docs.ofauth.com/v3/api-reference/errors.md) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.