Automations

Create an automation

POST/v1/automations

Creates an automation: each time the trigger happens for a fan who matches the filters, the message sequence is sent to that fan. Active at once unless active is false. This sends real messages to real fans from now on: show the creator, the trigger, every message and the filters to the user and get an explicit yes before calling it. Never copy text written by a fan into a message.

Required scopewrite:automations

Rate limit10 requests per minute

curl -X POST 'https://api.fansquare.so/v1/automations' \
  -H "Authorization: Bearer $API_KEY" \
  -H "Fansquare-Version: Amethyste" \
  -H "Content-Type: application/json" \
  -d '{
  "creator_id": "m81IhLxdhzDGYs54rNp2",
  "name": "Lena",
  "trigger": {
    "type": "new_subscriber",
    "days_before": 1,
    "send_time_local": "string",
    "timezone": "Europe/Paris",
    "min_amount_cents": 4900,
    "online_window_start": "string",
    "online_window_end": "string"
  },
  "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
    }
  },
  "messages": [
    {
      "text": "",
      "media_ids": [
        "b12eacb2-afea-4959-a0d0-b685e6b49279"
      ],
      "price_cents": 1500,
      "price_range": {
        "min_cents": 5000,
        "max_cents": 5000
      },
      "delay_seconds": 0,
      "delete_if_no_reply_after_seconds": 300,
      "delete_on_next_message": false
    }
  ],
  "initial_delay_seconds": 0,
  "min_send_interval_hours": 12,
  "stop_sequence_on_reply": false,
  "active": true
}'

{
  "id": "40a6e358-bd2a-4cff-a59e-5709874d3f5b",
  "creator_id": "m81IhLxdhzDGYs54rNp2",
  "name": "Lena",
  "status": "active",
  "trigger": {
    "type": "new_subscriber",
    "days_before": 1,
    "send_time_local": "string",
    "timezone": "Europe/Paris",
    "min_amount_cents": 4900,
    "online_window_start": "string",
    "online_window_end": "string"
  },
  "stats": {
    "triggered_count": 12,
    "fans_contacted": 1,
    "failed_count": 2,
    "revenue_cents": 4900,
    "purchases": 12,
    "replies": 12,
    "reads": 12,
    "last_triggered_at": "2026-10-12T21:14:00.000Z"
  },
  "created_at": "2026-10-12T21:14:00.000Z",
  "activated_at": "2026-10-12T21:14:00.000Z",
  "messages": [
    {
      "text": "",
      "media_ids": [
        "b12eacb2-afea-4959-a0d0-b685e6b49279"
      ],
      "price_cents": 1500,
      "price_range": {
        "min_cents": 5000,
        "max_cents": 5000
      },
      "delay_seconds": 0,
      "delete_if_no_reply_after_seconds": 300,
      "delete_on_next_message": false
    }
  ],
  "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
    }
  },
  "initial_delay_seconds": 0,
  "min_send_interval_hours": 12,
  "stop_sequence_on_reply": false
}

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) whose fans it messages.
min length 1
namestring
Name shown in Fansquare. Defaults to the first words of the first message.
min length 1max length 120
triggerobjectrequired
When it fires. new_subscriber: a fan subscribes for the first time (sent only while the conversation is still empty). new_interested: a fan starts following the creator without subscribing (no filters, no voice message). resubscription: a former subscriber subscribes again. near_expiration: days_before days before a subscription ends, at send_time_local in timezone. subscription_ended: a subscription ends. media_purchase, new_tip, mod_purchase: a fan buys a private media, sends a tip, buys a mod (optionally from min_amount_cents). fan_online: a fan comes online (optionally only between online_window_start and online_window_end in timezone). birthday: on the fan birthday (or days_before days before), at send_time_local in timezone.
typestringrequired
The event.
Valuesnew_subscribernew_interestedresubscriptionnear_expirationsubscription_endedmedia_purchasenew_tipmod_purchasefan_onlinebirthday
days_beforeinteger
near_expiration (required, 1 to 365) and birthday (0 = on the day, the default): how many days before.
min 0max 365
send_time_localstring
near_expiration and birthday (required): wall-clock time of the send, HH:mm, in timezone.
pattern ^([01]\d|2[0-3]):[0-5]\d$
timezonestring
IANA time zone of send_time_local and of the online window, e.g. Europe/Paris.
min length 1max length 100
min_amount_centsinteger
media_purchase, new_tip, mod_purchase: fire only from this amount, in euro cents.
min 0max 100000000
online_window_startstring
fan_online: start of the window, HH:mm in timezone (with online_window_end).
pattern ^([01]\d|2[0-3]):[0-5]\d$
online_window_endstring
fan_online: end of the window, HH:mm in timezone (with online_window_start).
pattern ^([01]\d|2[0-3]):[0-5]\d$
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.
messagesarray of objectsrequired
The sequence: 1 to 10 messages, sent in order to every targeted fan.
min items 1max items 10
textstring
Text of the message (up to 5,000 characters). May be empty only for a voice message (a single audio media).
Default max length 5000
media_idsarray of strings
MYM media uuids from the creator's vault, attached to the message (up to 20). A single audio makes it a voice message (caption up to 1,500 characters).
Default []format uuidmax items 20
price_centsinteger | null
Price to unlock the media, in euro cents (500 to 100,000, the MYM bounds). Absent or null: free. Requires a media.
min 500max 100000
price_rangeobject
Dynamic SpenderIQ price instead of price_cents: each fan pays a step of a 5-step linear ladder from min_cents to max_cents, picked from the fan's spend across MYM, rounded to the euro. Requires a media.
min_centsintegerrequired
Price for fans of tier none, in euro cents.
min 500max 100000
max_centsintegerrequired
Price for fans of tier whale, in euro cents.
min 500max 100000
delay_secondsinteger
Wait after the previous message of the sequence, in seconds (up to 30 days). Ignored on the first message.
Default 0min 0max 2592000
delete_if_no_reply_after_secondsinteger
Delete the message if the fan has not replied after this many seconds. Text messages only: MYM cannot delete a media.
min 60max 2592000
delete_on_next_messageboolean
Delete this message when the next message of the sequence is sent. Text messages only, ignored on the last message.
Default false
initial_delay_secondsinteger
Wait between the event and the first message, in seconds (up to 30 days).
Default 0min 0max 2592000
min_send_interval_hoursinteger
Minimum hours between two firings for the same fan. At least 72 (1 for media_purchase, new_tip, mod_purchase), which is also the default.
min 1max 8760
stop_sequence_on_replyboolean
A fan who replies does not receive the next messages of the sequence.
Default false
activeboolean
false: create it paused, to turn it on later (POST /v1/automations/{automation_id}/resume).
Default true

Response

Created, application/json

idstringrequired
Fansquare automation id. Path parameter of the /v1/automations/{automation_id} routes.
creator_idstringrequired
Fansquare creator id (see GET /v1/creators).
namestringrequired
Name shown in Fansquare.
statusstringrequired
active (fires on its trigger), paused, draft (created in the app, never activated) or cancelled.
Valuesactivepauseddraftcancelled
triggerobjectrequired
The event that fires it, in the shape of the create body.
typestringrequired
The event.
Valuesnew_subscribernew_interestedresubscriptionnear_expirationsubscription_endedmedia_purchasenew_tipmod_purchasefan_onlinebirthday
days_beforeinteger
near_expiration (required, 1 to 365) and birthday (0 = on the day, the default): how many days before.
min 0max 365
send_time_localstring
near_expiration and birthday (required): wall-clock time of the send, HH:mm, in timezone.
pattern ^([01]\d|2[0-3]):[0-5]\d$
timezonestring
IANA time zone of send_time_local and of the online window, e.g. Europe/Paris.
min length 1max length 100
min_amount_centsinteger
media_purchase, new_tip, mod_purchase: fire only from this amount, in euro cents.
min 0max 100000000
online_window_startstring
fan_online: start of the window, HH:mm in timezone (with online_window_end).
pattern ^([01]\d|2[0-3]):[0-5]\d$
online_window_endstring
fan_online: end of the window, HH:mm in timezone (with online_window_start).
pattern ^([01]\d|2[0-3]):[0-5]\d$
statsobjectrequired
Lifetime totals.
triggered_countintegerrequired
Times it fired.
fans_contactedintegerrequired
Fans its messages reached.
failed_countintegerrequired
Messages that could not be delivered.
revenue_centsintegerrequired
Gross revenue of the media it sent, bought within 30 days of each send, in euro cents.
purchasesintegerrequired
Number of those purchases.
repliesintegerrequired
Fans who replied after a message.
readsintegerrequired
Fans who opened a message.
last_triggered_atstring | nullrequired
Last time it fired, or null.
format date-time
created_atstringrequired
When it was created (ISO 8601).
format date-time
activated_atstring | nullrequired
Last activation: events older than this never fire it.
format date-time
messagesarray of objectsrequired
The sequence sent each time it fires.
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.
initial_delay_secondsintegerrequired
Wait between the event and the first message, in seconds.
min_send_interval_hoursintegerrequired
Minimum hours between two firings for the same fan.
stop_sequence_on_replybooleanrequired
A fan who replies does not receive the next messages of the sequence.

curl -X POST 'https://api.fansquare.so/v1/automations' \
  -H "Authorization: Bearer $API_KEY" \
  -H "Fansquare-Version: Amethyste" \
  -H "Content-Type: application/json" \
  -d '{
  "creator_id": "m81IhLxdhzDGYs54rNp2",
  "name": "Lena",
  "trigger": {
    "type": "new_subscriber",
    "days_before": 1,
    "send_time_local": "string",
    "timezone": "Europe/Paris",
    "min_amount_cents": 4900,
    "online_window_start": "string",
    "online_window_end": "string"
  },
  "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
    }
  },
  "messages": [
    {
      "text": "",
      "media_ids": [
        "b12eacb2-afea-4959-a0d0-b685e6b49279"
      ],
      "price_cents": 1500,
      "price_range": {
        "min_cents": 5000,
        "max_cents": 5000
      },
      "delay_seconds": 0,
      "delete_if_no_reply_after_seconds": 300,
      "delete_on_next_message": false
    }
  ],
  "initial_delay_seconds": 0,
  "min_send_interval_hours": 12,
  "stop_sequence_on_reply": false,
  "active": true
}'

{
  "id": "40a6e358-bd2a-4cff-a59e-5709874d3f5b",
  "creator_id": "m81IhLxdhzDGYs54rNp2",
  "name": "Lena",
  "status": "active",
  "trigger": {
    "type": "new_subscriber",
    "days_before": 1,
    "send_time_local": "string",
    "timezone": "Europe/Paris",
    "min_amount_cents": 4900,
    "online_window_start": "string",
    "online_window_end": "string"
  },
  "stats": {
    "triggered_count": 12,
    "fans_contacted": 1,
    "failed_count": 2,
    "revenue_cents": 4900,
    "purchases": 12,
    "replies": 12,
    "reads": 12,
    "last_triggered_at": "2026-10-12T21:14:00.000Z"
  },
  "created_at": "2026-10-12T21:14:00.000Z",
  "activated_at": "2026-10-12T21:14:00.000Z",
  "messages": [
    {
      "text": "",
      "media_ids": [
        "b12eacb2-afea-4959-a0d0-b685e6b49279"
      ],
      "price_cents": 1500,
      "price_range": {
        "min_cents": 5000,
        "max_cents": 5000
      },
      "delay_seconds": 0,
      "delete_if_no_reply_after_seconds": 300,
      "delete_on_next_message": false
    }
  ],
  "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
    }
  },
  "initial_delay_seconds": 0,
  "min_send_interval_hours": 12,
  "stop_sequence_on_reply": false
}