Mass DM

Get a Mass DM

GET/v1/mass-dms/{mass_dm_id}

Returns a Mass DM with its messages, its filters and the outcome of its send. 404 if it does not exist in the agency.

Required scoperead:mass_dms

Rate limit60 requests per minute

curl 'https://api.fansquare.so/v1/mass-dms/1b7431ca-849c-4728-acc2-fe033419f18a' \
  -H "Authorization: Bearer $API_KEY" \
  -H "Fansquare-Version: Amethyste"

{
  "id": "1b7431ca-849c-4728-acc2-fe033419f18a",
  "creator_id": "m81IhLxdhzDGYs54rNp2",
  "name": "Lena",
  "status": "draft",
  "scheduled_at": "2026-10-14T19:00:00.000Z",
  "send_at": "2026-10-12T21:14:00.000Z",
  "estimated_audience_count": 12,
  "results": {
    "audience_count": 12,
    "delivered_count": 128,
    "failed_count": 2,
    "revenue_cents": 4900,
    "purchases": 12,
    "replies": 12,
    "reads": 12,
    "started_at": "2026-10-12T21:14:00.000Z",
    "completed_at": "2026-10-12T21:14:00.000Z"
  },
  "created_at": "2026-10-12T21:14:00.000Z",
  "messages": [
    {
      "text": "string",
      "media_ids": [
        "b12eacb2-afea-4959-a0d0-b685e6b49279"
      ],
      "price_cents": 1500,
      "price_range": {
        "min_cents": 5000,
        "max_cents": 5000
      },
      "delay_seconds": 300,
      "delete_if_no_reply_after_seconds": 300,
      "delete_on_next_message": true
    }
  ],
  "filters": {
    "include": {
      "statuses": [
        "active_subscriber"
      ],
      "tag_ids": [
        "58368a92-838b-4cb0-ab37-d54ce826ea11"
      ],
      "min_spend_cents": 5000,
      "min_tips_cents": 5000,
      "min_subscription_months": 12,
      "is_online": true,
      "min_paid_spend_7d_cents": 5000,
      "min_paid_spend_30d_cents": 5000,
      "min_paid_spend_90d_cents": 5000,
      "min_payments_7d": 1,
      "min_payments_30d": 1,
      "min_payments_90d": 1,
      "spender_tiers": [
        "none"
      ],
      "media_purchase": {
        "mode": "within",
        "hours": 12
      }
    },
    "exclude": {
      "tag_ids": [
        "58368a92-838b-4cb0-ab37-d54ce826ea11"
      ],
      "messaged_within_hours": 12,
      "fan_messaged_within_hours": 12,
      "has_unread_from_fan": true,
      "already_unlocked_media": true,
      "already_received_media": true
    }
  },
  "stop_sequence_on_reply": true
}

Parameters

Headers

Fansquare-Versionstringrequired
API version to pin. Accepts the mineral name or the release date of a version.

Path

mass_dm_idstringrequired
Fansquare Mass DM id (the id field of Mass DM items).
format uuid

Response

OK, application/json

idstringrequired
Fansquare Mass DM id. Path parameter of the /v1/mass-dms/{mass_dm_id} routes.
creator_idstringrequired
Fansquare creator id (see GET /v1/creators).
namestringrequired
Name shown in Fansquare.
statusstringrequired
scheduled (waiting for scheduled_at), sending, sent, partial (sent, some fans could not be reached), failed, cancelled, or draft (created in the app, never activated).
Valuesdraftscheduledsendingsentpartialfailedcancelled
scheduled_atstring | nullrequired
Scheduled send time (ISO 8601), or null for a Mass DM sent at creation.
format date-time
send_atstringrequired
When it leaves or left: scheduled_at, or the creation time for an immediate one. The list is sorted on it.
format date-time
estimated_audience_countinteger | nullrequired
Fans targeted, counted when it was scheduled (indicative). null for an immediate Mass DM: see results.audience_count.
resultsobject | nullrequired
Outcome of the send, null until it starts. The counters are refreshed every few minutes during 30 days.
audience_countinteger | nullrequired
Fans actually targeted, resolved when the send started.
delivered_countinteger | nullrequired
Fans the sequence reached. null until first computed (within a few minutes).
failed_countinteger | nullrequired
Messages that could not be delivered.
revenue_centsinteger | nullrequired
Gross revenue (before the MYM commission) of the media of this Mass DM bought within 30 days, in euro cents.
purchasesinteger | nullrequired
Number of those purchases.
repliesinteger | nullrequired
Fans who replied after receiving it.
readsinteger | nullrequired
Fans who opened it (read, or replied).
started_atstring | nullrequired
When the send started.
format date-time
completed_atstring | nullrequired
When the send finished.
format date-time
created_atstringrequired
When it was created (ISO 8601).
format date-time
messagesarray of objectsrequired
The sequence sent to every targeted fan.
textstringrequired
Text of the message.
media_idsarray of stringsrequired
MYM media uuids from the creator's vault.
price_centsinteger | nullrequired
Fixed price to unlock the media, in euro cents. null: free, or dynamic (see price_range).
price_rangeobject | nullrequired
Dynamic SpenderIQ price range in euro cents, or null for a fixed price.
min_centsintegerrequired
max_centsintegerrequired
delay_secondsintegerrequired
Wait after the previous message, in seconds (0 on the first message).
delete_if_no_reply_after_secondsinteger | nullrequired
Deleted if the fan has not replied after this many seconds, or null.
delete_on_next_messagebooleanrequired
Deleted when the next message of the sequence is sent.
filtersobjectrequired
Audience filters, in the shape of the create body: only the conditions that are set.
includeobject
Conditions a fan must ALL meet to be targeted.
statusesarray of strings
Subscription status of the fan on this account, same vocabulary as the statuses filter of GET /v1/accounts/{account_id}/fans: active_subscriber, former_subscriber, interested (follows the creator without subscribing). Any of them. Absent or empty: no status condition, every fan with a conversation is in, whatever their status.
Valuesactive_subscriberformer_subscriberinterestedmax items 3
tag_idsarray of strings
Only fans carrying at least one of these tags (ids from GET /v1/tags).
format uuidmax items 100
min_spend_centsinteger
Total à-la-carte spend of the fan on this account at least this amount, in euro cents, gross (before the MYM commission). Same figure as spend.total_cents of a fan in GET /v1/accounts/{account_id}/fans.
min 0max 100000000
min_tips_centsinteger
Sum of the tips the fan sent this account at least this amount, in euro cents.
min 0max 100000000
min_subscription_monthsinteger
Fans whose first subscription to this account started at least this many months ago.
min 0max 1200
is_onlineboolean
true: only fans online on MYM when the audience is resolved (at send time for a Mass DM, at the trigger for an automation). false or absent: no condition.
min_paid_spend_7d_centsinteger
Paid spend (subscriptions and purchases) of the fan on this account over the last 7 days at least this amount, in euro cents.
min 0max 100000000
min_paid_spend_30d_centsinteger
Same over the last 30 days.
min 0max 100000000
min_paid_spend_90d_centsinteger
Same over the last 90 days.
min 0max 100000000
min_payments_7dinteger
Number of paid orders of the fan on this account over the last 7 days at least this value.
min 0max 100000
min_payments_30dinteger
Same over the last 30 days.
min 0max 100000
min_payments_90dinteger
Same over the last 90 days.
min 0max 100000
spender_tiersarray of strings
SpenderIQ tiers, any of them, from the paid spend of the fan on this account over the last 90 days: none (nothing), low (under 50 EUR), medium (50 EUR or more), high (300 EUR or more), whale (1,500 EUR or more).
Valuesnonelowmediumhighwhalemax items 5
media_purchaseobject
Last private media purchase of the fan on this account.
modestringrequired
within: the fan bought a private media in the last hours. not_since: no private media purchase for hours (fans who never bought are in).
Valueswithinnot_since
hoursintegerrequired
Window in hours (1 to 8760).
min 1max 8760
excludeobject
Conditions that leave a fan out.
tag_idsarray of strings
Leave out fans carrying any of these tags. A tag cannot be both included and excluded.
format uuidmax items 100
messaged_within_hoursinteger
Leave out fans the account sent a message to in the last N hours (a chatter, a script or another Mass DM sent from Fansquare).
min 1max 8760
fan_messaged_within_hoursinteger
Leave out fans who wrote to the account in the last N hours: never push into a live conversation. Checked again on MYM at send time.
min 1max 8760
has_unread_from_fanboolean
true: leave out fans whose last message to the account is still unread.
already_unlocked_mediaboolean
true: leave out fans who already have a media of this campaign unlocked (sent free, or bought).
already_received_mediaboolean
true: leave out fans who already received a media of this campaign, bought or not.
stop_sequence_on_replybooleanrequired
A fan who replies does not receive the next messages of the sequence.

curl 'https://api.fansquare.so/v1/mass-dms/1b7431ca-849c-4728-acc2-fe033419f18a' \
  -H "Authorization: Bearer $API_KEY" \
  -H "Fansquare-Version: Amethyste"

{
  "id": "1b7431ca-849c-4728-acc2-fe033419f18a",
  "creator_id": "m81IhLxdhzDGYs54rNp2",
  "name": "Lena",
  "status": "draft",
  "scheduled_at": "2026-10-14T19:00:00.000Z",
  "send_at": "2026-10-12T21:14:00.000Z",
  "estimated_audience_count": 12,
  "results": {
    "audience_count": 12,
    "delivered_count": 128,
    "failed_count": 2,
    "revenue_cents": 4900,
    "purchases": 12,
    "replies": 12,
    "reads": 12,
    "started_at": "2026-10-12T21:14:00.000Z",
    "completed_at": "2026-10-12T21:14:00.000Z"
  },
  "created_at": "2026-10-12T21:14:00.000Z",
  "messages": [
    {
      "text": "string",
      "media_ids": [
        "b12eacb2-afea-4959-a0d0-b685e6b49279"
      ],
      "price_cents": 1500,
      "price_range": {
        "min_cents": 5000,
        "max_cents": 5000
      },
      "delay_seconds": 300,
      "delete_if_no_reply_after_seconds": 300,
      "delete_on_next_message": true
    }
  ],
  "filters": {
    "include": {
      "statuses": [
        "active_subscriber"
      ],
      "tag_ids": [
        "58368a92-838b-4cb0-ab37-d54ce826ea11"
      ],
      "min_spend_cents": 5000,
      "min_tips_cents": 5000,
      "min_subscription_months": 12,
      "is_online": true,
      "min_paid_spend_7d_cents": 5000,
      "min_paid_spend_30d_cents": 5000,
      "min_paid_spend_90d_cents": 5000,
      "min_payments_7d": 1,
      "min_payments_30d": 1,
      "min_payments_90d": 1,
      "spender_tiers": [
        "none"
      ],
      "media_purchase": {
        "mode": "within",
        "hours": 12
      }
    },
    "exclude": {
      "tag_ids": [
        "58368a92-838b-4cb0-ab37-d54ce826ea11"
      ],
      "messaged_within_hours": 12,
      "fan_messaged_within_hours": 12,
      "has_unread_from_fan": true,
      "already_unlocked_media": true,
      "already_received_media": true
    }
  },
  "stop_sequence_on_reply": true
}