# Send Targeted Mass Messages and PPV Campaigns via API

> Programmatically send mass messages to user lists, schedule PPV campaigns with media, and track unlock rates with real-time webhooks. Built for agencies managing multiple creators at scale.

[Start Free Trial](https://app.onlyfansapi.com/register) · [Read the Docs](https://docs.onlyfansapi.com/api-reference/mass-messaging/send-mass-message)

## How Mass Messaging Works via API

Upload media, target fan segments, send at scale, and track revenue — all programmatically with real-time status callbacks.

### Upload Media

Push photos or videos to OnlyFans CDN

### Target Fans

Select user lists or individual fan IDs

### Send Campaign

Mass message queued and sent progressively

### Track Revenue

PPV unlock webhooks fire in real time

## Real Webhook-Driven Mass Messaging Use Cases

Each use case shows the webhook event that triggers it and the API endpoint you call. Build these into your messaging pipeline.

### Send PPV Campaigns to Fan Segments

Target specific user lists with PPV content. Upload media, set a price, and send to thousands of fans with a single API call.
- API: `POST /api/{account}/mass-messaging` — Send a mass message with media, price, and user list targeting
- Webhook: `chat_queue.finished` — Fires when the mass message batch completes sending

### Track PPV Unlock Revenue

Get notified the instant a fan unlocks a paid message. Track revenue per campaign and per fan in real time.
- API: `GET /api/{account}/engagement/messages/mass-messages` — Get mass message engagement stats and revenue
- Webhook: `messages.ppv.unlocked` — Fires when a fan purchases a paid message with amount data

### Build Smart Target Lists

Create user lists by segment — top spenders, recent subscribers, expired fans — and use them as mass message targets.
- API: `POST /api/{account}/user-lists` — Create a new user list for targeting
- Webhook: `subscriptions.new` — Fires on new subscription — add to welcome campaign list

### Upload and Attach Media

Upload photos and videos to the OnlyFans CDN, then attach them to mass messages as free or PPV content.
- API: `POST /api/{account}/media/upload` — Upload a file or URL to the OnlyFans CDN
- Webhook: `chat_queue.updated` — Fires as the message batch sends — track progress

### Monitor Campaign Performance

Track which messages drive the most revenue. See buyer lists, unlock rates, and top-performing content.
- API: `GET /api/{account}/engagement/messages/top-message` — Get the highest-revenue message across all campaigns
- Webhook: `messages.ppv.unlocked` — Fires per unlock — aggregate for campaign stats

### Schedule and Manage Queue

View queued messages, update pending campaigns, or cancel messages before they send. Full control over your send pipeline.
- API: `PUT /api/{account}/mass-messaging/{id}` — Update a queued mass message before it sends
- Webhook: `chat_queue.updated` — Fires on queue status changes — e.g. progress updates

## Production-Ready Code Examples

Real API calls for sending mass messages, tracking PPV revenue, and pulling campaign analytics.

### Send PPV Campaign

Upload media, create a user list, and send a mass PPV message to targeted fans — all in one workflow.

```ts
// Step 1: Upload media to OnlyFans CDN
const mediaResponse = await fetch(
  'https://app.onlyfansapi.com/api/acct_XXXX/media/upload',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_your_api_key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      file_url: 'https://your-cdn.com/exclusive-content.mp4'
    })
  }
);
const media = await mediaResponse.json();

// Step 2: Send mass PPV message to a user list
const massMessageResponse = await fetch(
  'https://app.onlyfansapi.com/api/acct_XXXX/mass-messaging',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_your_api_key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      text: 'Exclusive content just for you 🔥',
      price: 15.00,
      mediaFiles: [media.data.id],
      userLists: ['top_spenders_list_id']
    })
  }
);
const campaign = await massMessageResponse.json();
console.log('Campaign sent:', campaign.data.id);
```

### Track PPV Revenue via Webhook

Listen for PPV unlock webhooks and aggregate revenue per campaign. Update your analytics in real time.

```ts
// Webhook handler: messages.ppv.unlocked
app.post('/webhooks/onlyfans', async (req, res) => {
  const { event, account_id, payload } = req.body;

  if (event === 'messages.ppv.unlocked') {
    // payload.user = buyer profile
    // payload.fanData.spending = lifetime spend breakdown
    // payload.replacePairs['{AMOUNT}'] = purchase amount
    const { user, fanData, replacePairs } = payload;
    const purchaseAmount = replacePairs['{AMOUNT}'];

    // Log the PPV unlock
    console.log(
      user.username + ' unlocked PPV for ' + purchaseAmount
    );

    // Update campaign revenue in your database
    await db.campaigns.updateRevenue({
      eventId: payload.id,
      fanId: user.id,
      fanUsername: user.username,
      purchaseAmount: purchaseAmount,
      fanLifetimeSpend: fanData.spending.total,
      fanTipSpend: fanData.spending.tips,
      fanMessageSpend: fanData.spending.messages,
    });

    // If whale spender, send a personalized follow-up
    if (fanData.spending.total > 500) {
      await fetch(
        'https://app.onlyfansapi.com/api/' + account_id + '/chats/' + user.id + '/messages',
        {
          method: 'POST',
          headers: {
            'Authorization': 'Bearer sk_your_api_key',
            'Content-Type': 'application/json'
          },
          body: JSON.stringify({
            text: 'Thanks for the support! Here is a bonus 💎'
          })
        }
      );
    }
  }

  res.sendStatus(200);
});
```

### Pull Campaign Analytics

Fetch mass message performance — overview stats, per-message revenue, and buyer lists.

```ts
// Get mass messaging overview
const overviewResponse = await fetch(
  'https://app.onlyfansapi.com/api/acct_XXXX/mass-messaging/overview',
  {
    headers: {
      'Authorization': 'Bearer sk_your_api_key',
      'Content-Type': 'application/json'
    }
  }
);
const overview = await overviewResponse.json();
console.log('Total campaigns:', overview.data);

// Get engagement stats for mass messages
const engagementResponse = await fetch(
  'https://app.onlyfansapi.com/api/acct_XXXX/engagement/messages/mass-messages',
  {
    headers: {
      'Authorization': 'Bearer sk_your_api_key',
      'Content-Type': 'application/json'
    }
  }
);
const engagement = await engagementResponse.json();

// Get the top revenue-generating message
const topMessageResponse = await fetch(
  'https://app.onlyfansapi.com/api/acct_XXXX/engagement/messages/top-message',
  {
    headers: {
      'Authorization': 'Bearer sk_your_api_key',
      'Content-Type': 'application/json'
    }
  }
);
const topMessage = await topMessageResponse.json();
console.log('Top message:', topMessage.data);

// Get buyer list for a specific message
const buyersResponse = await fetch(
  'https://app.onlyfansapi.com/api/acct_XXXX/engagement/messages/'
    + topMessage.data.id + '/buyers',
  {
    headers: {
      'Authorization': 'Bearer sk_your_api_key',
      'Content-Type': 'application/json'
    }
  }
);
const buyers = await buyersResponse.json();
console.log('Buyers:', buyers.data);
```

## Available Endpoints and Webhooks

Every endpoint and webhook event for mass messaging. Full documentation at docs.onlyfansapi.com.

| Method | Path | Description |
| --- | --- | --- |
| POST | `/api/{account}/mass-messaging` | Send a mass message to user lists or user IDs. |
| GET | `/api/{account}/mass-messaging` | List all queued mass messages. |
| GET | `/api/{account}/mass-messaging/overview` | Get mass messaging overview statistics. |
| GET | `/api/{account}/mass-messaging/{id}` | Retrieve a specific mass message. |
| PUT | `/api/{account}/mass-messaging/{id}` | Update a pending mass message. |
| DELETE | `/api/{account}/mass-messaging/{id}` | Delete or unsend a mass message. |
| POST | `/api/{account}/media/upload` | Upload media to the OnlyFans CDN. |
| GET | `/api/{account}/user-lists` | List all user lists available for targeting. |
| POST | `/api/{account}/user-lists` | Create a new user list. |
| POST | `/api/{account}/user-lists/{id}/users` | Add users to an existing list. |
| GET | `/api/{account}/engagement/messages/mass-messages` | Retrieve mass message engagement statistics. |
| GET | `/api/{account}/engagement/messages/top-message` | Get the highest-revenue mass message. |
| GET | `/api/{account}/engagement/messages/{id}/buyers` | List buyers for a specific mass message. |

**Webhook events**

- `chat_queue.finished` — Mass message batch has completed sending to all recipients.
- `chat_queue.updated` — Mass message batch status changed — track sending progress.
- `messages.ppv.unlocked` — Fan purchased a paid message, including purchase amount and spending data.
- `messages.sent` — Outgoing message delivered to a fan — confirm delivery status.
- `transactions.new` — Payment received — track PPV revenue alongside subscriptions and tips.

## OnlyFans Mass Messaging API — Frequently Asked Questions

Common questions about sending mass messages and PPV campaigns via API.

### Can I send PPV mass messages with media via the API?

Yes. Upload media using the media/upload endpoint (supports direct file upload or URL), then pass the media IDs to the mass-messaging endpoint with a price. The message gets queued and sent to all targeted fans. You can target by user list IDs, individual user IDs, or both.

### How do I target specific fan segments?

Create user lists via the API (or in the dashboard), add fans to those lists based on your criteria, then pass the list IDs when sending a mass message. Common segments: top spenders, active subscribers, expired fans, fans from specific traffic sources.

### Can I track how much revenue each mass message generates?

Yes. The messages.ppv.unlocked webhook fires in real time when a fan unlocks paid content, including the purchase amount and fan spending data. The engagement endpoints give you aggregate stats, top-performing messages, and buyer lists.

### Can I schedule mass messages for later?

Yes. The mass messaging endpoint supports scheduling. You can also manage the queue — view pending messages, update content or targeting before send, or cancel messages entirely.

### What is the send rate for mass messages?

Mass messages are queued and sent progressively to avoid rate limits on OnlyFans. The chat_queue.updated webhook fires with progress updates so you can track delivery in real time. The chat_queue.finished webhook fires when the batch completes.

### Can I A/B test mass messages?

Yes. Create two user lists with overlapping segments, send different messages to each, then compare revenue and unlock rates using the engagement endpoints. The messages.ppv.unlocked webhook gives you per-message revenue data for real-time comparison.

### Is there a limit on how many fans I can message?

The API follows OnlyFans native limits. You can message all fans in a user list or pass thousands of user IDs. The queue system handles delivery pacing automatically. Your RPM (requests per minute) allocation depends on your plan tier.

### Can I use this with Make.com or Zapier?

Yes. OnlyFans API has native connectors for Make.com, Zapier, and n8n. You can build mass messaging workflows triggered by events — for example, automatically send a welcome PPV to every new subscriber.

## Every Day Without Automated Messaging Is Revenue Left on the Table.

Start free. Send your first mass message campaign in minutes.

[Start For Free](https://app.onlyfansapi.com/register) · [See Pricing](https://onlyfansapi.com/pricing)

## Links

- View on site: https://onlyfansapi.com/onlyfans-mass-messaging-api
- Send mass message docs: https://docs.onlyfansapi.com/api-reference/mass-messaging/send-mass-message
- All 320+ endpoints: https://docs.onlyfansapi.com/api-reference/overview
- All 25 webhook events: https://docs.onlyfansapi.com/webhooks/available-events
- Pricing: https://onlyfansapi.com/pricing
- Sign up: https://app.onlyfansapi.com/register