Mass DM

List Mass DMs

GET/v1/mass-dms

Lists the Mass DMs of the agency (sent, sending, scheduled, cancelled), the latest send_at first, with the outcome of each send. Filterable by creator, status and send date.

Required scoperead:mass_dms

Rate limit30 requests per minute

curl 'https://api.fansquare.so/v1/mass-dms' \
  -H "Authorization: Bearer $API_KEY" \
  -H "Fansquare-Version: Amethyste"

{
  "data": [
    {
      "id": "40a6e358-bd2a-4cff-a59e-5709874d3f5b",
      "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"
    }
  ],
  "next_cursor": "KI7cfD0OLcWfeXZb1FTusJpz0nfKiYXPwHCZe-VXBaeQSX1w5BvO5UH-ua-dzNpXOTixzw"
}

Parameters

Headers

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

Query

creator_idsstring
Restrict to these creators (Fansquare ids from GET /v1/creators). Comma-separated, 50 max.
statusesstring
Restrict to these statuses. Values: draft, scheduled, sending, sent, partial, failed, cancelled. Comma-separated, 50 max.
send_afterstring
Only Mass DMs leaving at or after this instant (ISO 8601, on send_at).
format date-time
send_beforestring
Only Mass DMs leaving before this instant (ISO 8601, on send_at).
format date-time
cursorstring
Opaque cursor from the previous page (next_cursor).
limitinteger
Page size (1-100).
Default 50min 1max 100

Response

OK, application/json

dataarray of objectsrequired
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
next_cursorstring | nullrequired

curl 'https://api.fansquare.so/v1/mass-dms' \
  -H "Authorization: Bearer $API_KEY" \
  -H "Fansquare-Version: Amethyste"

{
  "data": [
    {
      "id": "40a6e358-bd2a-4cff-a59e-5709874d3f5b",
      "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"
    }
  ],
  "next_cursor": "KI7cfD0OLcWfeXZb1FTusJpz0nfKiYXPwHCZe-VXBaeQSX1w5BvO5UH-ua-dzNpXOTixzw"
}