Fanvue API Documentation

By the end of this page you’ll have sent a mass message, free or paid, now or scheduled, and read back how many fans it reached. A mass message goes to every fan in the lists you include, minus the fans in the lists you exclude, so you pick lists first and then post one request. You need an access token for the creator with the scopes below. Add them on your app’s Authentication tab; see Scopes.

Scopes

Call	Scopes
List smart, custom or dynamic lists	`read:chat` and `read:fan`
`POST /chats/mass-messages`	`write:chat` and `read:fan`
`GET /chats/mass-messages`	`read:chat`
`PATCH` or `DELETE /chats/mass-messages/{messageUuid}`	`write:chat`

Pick the lists

There are three kinds of list, and each goes in its own field of the send body.

Kind	Who defines it	Read with	Field in the send body	Values
Smart lists	Fanvue, read-only	`GET /chats/lists/smart`, members at `GET /chats/lists/smart/{uuid}`	`smartListIds`	Fixed identifiers, not UUIDs
Custom lists	The creator, by hand	`GET /chats/lists/custom`, members at `GET /chats/lists/custom/{uuid}`	`customListUuids`	UUIDs
Dynamic lists	The creator, as a saved filter	`GET /v1/chats/lists/dynamic` (v1 only)	`dynamicSmartListUuids`	UUIDs

Smart list identifiers are lowercase strings: subscribers, auto_renewing, non_renewing, followers, free_trial_subscribers, expired_subscribers, spent_more_than_50, muted, creators. The smart list response names each one in a uuid key for backward compatibility, and the body also accepts the deprecated alias smartListUuids. Send smartListIds in new code. Each custom list item carries uuid, name, membersCount and createdAt. Dynamic lists are available to creators who have dynamic lists enabled, and the dynamic list endpoints answer 403 for other accounts. See Build dynamic lists.

Send the message

POST /chats/mass-messages returns 201. The body takes these fields:

Field	Rule
`text`	1 to 5000 characters. Required unless `mediaUuids` is present.
`includedLists`	Object with `smartListIds`, `customListUuids` and `dynamicSmartListUuids`. At least one list is required.
`excludedLists`	Same keys. Fans in an excluded list are removed from the recipients.
`price`	USD cents, minimum `300`. Requires `mediaUuids`.
`mediaUuids`	Media UUIDs in display order.
`mediaPreviewUuid`	One attached item shown free. Requires `price` and `mediaUuids`.
`scheduledAt`	ISO 8601 datetime. When present, the message is queued instead of sent.

The optional Idempotency-Key header makes a send safe to retry. Reuse the same key on a retry and the original result is replayed once the first attempt finishes. Two cases return 409: a retry while the first attempt is still running, and a key reused for a different message. Keys are scoped to your app and the sending creator and are remembered for 24 hours.

curl -X POST "https://api.fanvue.com/chats/mass-messages" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Fanvue-API-Version: 2025-06-26" \
  -H "Idempotency-Key: spring-drop-2026-03-04" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "New set is live, 12 photos from the shoot",
    "includedLists": {
      "smartListIds": ["subscribers"],
      "customListUuids": ["4e1b2c3d-5f6a-4b7c-8d9e-0f1a2b3c4d5e"]
    },
    "excludedLists": {
      "customListUuids": ["9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d"]
    },
    "mediaUuids": ["0b4a3c1e-2f6d-4b8a-9c1d-5e7f8a9b0c1d"],
    "price": 1500
  }'

The 201 response:

{
  "uuid": "c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f",
  "status": "SENDING",
  "publishedAt": "2026-03-04T18:21:09.000Z",
  "recipientCount": null
}

Field	Meaning
`uuid`	The mass message.
`status`	`SENDING` or `SCHEDULED` when dispatch is asynchronous. Absent otherwise.
`publishedAt`	When the message was sent, or `null` when scheduled.
`recipientCount`	Recipients resolved at request time, or `null` when an immediate send resolves them asynchronously. A scheduled message re-resolves its recipients at send time.

Check the result

GET /chats/mass-messages lists the creator’s mass messages with page and size. Each item carries uuid, text, status, price, createdAt, publishedAt, scheduledAt, recipientCount, viewCount, purchaseCount, totalRevenue (USD cents), mediaUuids, includedLists and excludedLists. Status values are SENT, UNSENT, SENDING, FAILED, MODERATED and SCHEDULED. recipientCount stays 0 while the status is SCHEDULED. Pass includeDeleted=true to include deleted messages, which report UNSENT. To read the final recipientCount, poll the list until the item’s status leaves SENDING or SCHEDULED, or wait for the creator.message.mass_sent webhook event, which fires when a send completes. For a scheduled message, PATCH /chats/mass-messages/{messageUuid} updates it and DELETE /chats/mass-messages/{messageUuid} cancels it.

TypeScript example

This script puts the steps together. It lists the smart lists, sends to subscribers and polls for the final count.

const API = "https://api.fanvue.com";
const headers = {
  Authorization: `Bearer ${process.env.FANVUE_TOKEN}`,
  "X-Fanvue-API-Version": "2025-06-26",
  "Content-Type": "application/json",
};

async function api(path: string, init: RequestInit = {}) {
  const res = await fetch(`${API}${path}`, { ...init, headers: { ...headers, ...init.headers } });
  if (!res.ok) throw new Error(`${res.status} on ${path}: ${await res.text()}`);
  return res.json();
}

async function run() {
  const smartLists = await api("/chats/lists/smart");
  const subscribers = smartLists.find((l: any) => l.uuid === "subscribers");
  console.log(`subscribers: ${subscribers?.count ?? 0}`);

  const sent = await api("/chats/mass-messages", {
    method: "POST",
    headers: { "Idempotency-Key": `weekly-${new Date().toISOString().slice(0, 10)}` },
    body: JSON.stringify({
      text: "This week's set is live",
      includedLists: { smartListIds: ["subscribers"] },
    }),
  });

  for (let i = 0; i < 20; i++) {
    const page = await api("/chats/mass-messages?page=1&size=15");
    const item = page.data.find((m: any) => m.uuid === sent.uuid);
    if (item && item.status !== "SENDING" && item.status !== "SCHEDULED") {
      console.log(`${item.status}: ${item.recipientCount} recipients`);
      return;
    }
    await new Promise((r) => setTimeout(r, 3000));
  }
}

run().catch(console.error);

Agency

Agencies send on a creator’s behalf with POST /creators/{creatorUserUuid}/chats/mass-messages. The creator-scoped routes need read:creator in addition to the scopes in the Scopes table. GET, PATCH and DELETE have the same creator-scoped twins under /creators/{creatorUserUuid}/chats/mass-messages.

Things that can go wrong

Response	Cause	Fix
`400` “At least one list must be provided”	`includedLists` has no non-empty array	Add at least one of `smartListIds`, `customListUuids` or `dynamicSmartListUuids`.
`400` smart list not found	A `smartListIds` value is not one of the nine identifiers, or is uppercase	Send lowercase identifiers such as `subscribers`.
`400` price below minimum	`price` under `300`	Send at least `300` USD cents.
`403`	Token lacks `write:chat` or `read:fan`, or the account has no dynamic lists	Add the scopes on the Authentication tab and reconnect the user.
`409`	`Idempotency-Key` reused while the first send runs, or for a different message	Wait for the first send, or pick a new key.

Start here

Authentication

API concepts

Guides

Send a mass message

Scopes

Pick the lists

Send the message

Check the result

TypeScript example

Agency

Things that can go wrong

​Scopes

​Pick the lists

​Send the message

​Check the result

​TypeScript example

​Agency

​Things that can go wrong

Scopes

Pick the lists

Send the message

Check the result

TypeScript example

Agency

Things that can go wrong