Mass DM

Estimate the audience of a Mass DM

POST/v1/mass-dms/estimate

Counts the fans a Mass DM with these filters would reach right now, without creating anything. Use it to check the filters before POST /v1/mass-dms.

Required scoperead:mass_dms

Rate limit10 requests per minute

curl -X POST 'https://api.fansquare.so/v1/mass-dms/estimate' \
  -H "Authorization: Bearer $API_KEY" \
  -H "Fansquare-Version: Amethyste" \
  -H "Content-Type: application/json" \
  -d '{
  "creator_id": "m81IhLxdhzDGYs54rNp2",
  "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
    }
  },
  "media_ids": [
    "b12eacb2-afea-4959-a0d0-b685e6b49279"
  ],
  "include_spender_tiers": false
}'

{
  "count": 12,
  "spender_tier_counts": {
    "none": 1,
    "low": 1,
    "medium": 1,
    "high": 1,
    "whale": 1
  }
}

Parameters

Headers

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

Body

application/json

creator_idstringrequired
Fansquare creator id (see GET /v1/creators).
min length 1
filtersobject
Who receives it. Every condition is optional and they add up (AND). Absent: every fan with a conversation on the account. Fans removed, disabled or blacklisted on MYM are always left out.
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.
media_idsarray of strings
The media the Mass DM will send: needed only by the already_unlocked_media and already_received_media exclusions.
Default []format uuidmax items 100
include_spender_tiersboolean
Also count the targeted fans per SpenderIQ tier (to price a price_range message).
Default false

Response

OK, application/json

countintegerrequired
Fans the filters target right now. Indicative: the audience is resolved again at send time.
spender_tier_countsobject
Same fans per SpenderIQ tier of the dynamic price ladder, when include_spender_tiers is true.
noneintegerrequired
lowintegerrequired
mediumintegerrequired
highintegerrequired
whaleintegerrequired

curl -X POST 'https://api.fansquare.so/v1/mass-dms/estimate' \
  -H "Authorization: Bearer $API_KEY" \
  -H "Fansquare-Version: Amethyste" \
  -H "Content-Type: application/json" \
  -d '{
  "creator_id": "m81IhLxdhzDGYs54rNp2",
  "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
    }
  },
  "media_ids": [
    "b12eacb2-afea-4959-a0d0-b685e6b49279"
  ],
  "include_spender_tiers": false
}'

{
  "count": 12,
  "spender_tier_counts": {
    "none": 1,
    "low": 1,
    "medium": 1,
    "high": 1,
    "whale": 1
  }
}