> For the complete documentation index, see [llms.txt](https://docs.fstrk.io/knowledge_base/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fstrk.io/knowledge_base/api/obshaya-informaciya/auditornye-rassylki.md).

# Аудиторные рассылки

#### GET /api/partners/mailings/

🔒 *bot-key или OAuth*

**Кратко:** Получить список всех созданных рассылок.

**Параметры запроса:**

* `limit` (integer, опциональный) — кол-во элементов на странице (макс. 100)
* `offset` (integer, опциональный) — кол-во элементов для пропуска

**Возвращает:** `200 OK` — постраничный список объектов `Mailing`.

**Ошибки:** 401 — ошибка авторизации.

**Пример запроса:**

```bash
curl -X GET "https://dashboard.fstrk.io/api/partners/mailings/?limit=50" \
  -H "bot-key: your_bot_key"
```

***

#### POST /api/partners/mailings/

🔒 *bot-key или OAuth*

**Кратко:** Создать новую аудиторную рассылку.

**Что делает:** Создаёт рассылку по динамическому фильтру чатов или по файлу/массиву идентификаторов клиентов. Поддерживает отправку текста, узла сценария и WhatsApp-шаблонов (WABA). Может запустить рассылку немедленно, в запланированное время или по CRON-расписанию (регулярная рассылка).

**Тело запроса:**

* `name` (string, обязательный) — название рассылки (1–80 символов)
* `content_type` (string, опциональный) — тип контента: `TEXT`, `NODE`, `TEMPLATE_WHATSAPP`, `MIXED`
* `text` (string, опциональный) — текст сообщения (при `content_type: TEXT`)
* `node_name` (string, опциональный) — название узла сценария (при `content_type: NODE`)
* `node_get_params` (array, опциональный) — параметры для узла: `[{ "name": "key", "type": "string", "value": "val" }]`
* `filter_chats` (object, опциональный) — динамический фильтр аудитории (структура `all: [...]`)
* `customer_filter_field` (string, опциональный) — поле идентификации клиентов из файла/массива: `UUID`, `EXTERNAL_ID`, `PHONE_NUMBER`, `CHAT_UUID`
* `customer_filter_file` (string, uri, опциональный) — URL файла с идентификаторами клиентов
* `customer_filter_array` (array of string, опциональный) — массив идентификаторов клиентов
* `phone_numbers_file` (string, uri, опциональный) — URL XLSX-файла с номерами телефонов (для WABA)
* `template_whatsapp` (string, опциональный) — название согласованного WhatsApp-шаблона
* `template_variables` (object, опциональный) — переменные шаблона
* `planned_at` (string, date-time, опциональный) — дата запланированной отправки
* `regular_cron` (string, опциональный) — CRON-расписание для регулярной рассылки (например, `00 12 * * *`)
* `origin` (string, опциональный) — `chat_center` для отправки сквозь открытую чат-сессию

**Возвращает:** `201 Created` — объект `Mailing`.

**Ошибки:** 400 — некорректные данные; 401 — ошибка авторизации.

**Примеры запросов:**

```bash
# Отправить текст по динамическому фильтру (Telegram, московское время)
curl -X POST https://dashboard.fstrk.io/api/partners/mailings/ \
  -H "Content-Type: application/json" \
  -H "bot-key: your_bot_key" \
  -d '{
    "name": "Летняя акция",
    "filter_chats": {
      "all": [
        { "platform": "Telegram", "type": "attribute" },
        { "timezone": "Europe/Moscow", "type": "profile_attribute" }
      ]
    },
    "content_type": "TEXT",
    "text": "Привет! Специальное предложение только сегодня 🎁"
  }'

# Запланировать рассылку с узлом
curl -X POST https://dashboard.fstrk.io/api/partners/mailings/ \
  -H "Content-Type: application/json" \
  -H "bot-key: your_bot_key" \
  -d '{
    "name": "Акция сентябрь",
    "filter_chats": {
      "all": [
        { "platform": "Vkontakte", "type": "attribute" }
      ]
    },
    "content_type": "NODE",
    "node_name": "Приветственный узел",
    "node_get_params": [
      { "name": "promo", "type": "string", "value": "FALL2024" }
    ],
    "planned_at": "2024-09-01T10:00:00+03:00"
  }'

# Регулярная рассылка каждый день в 12:00 UTC
curl -X POST https://dashboard.fstrk.io/api/partners/mailings/ \
  -H "Content-Type: application/json" \
  -H "bot-key: your_bot_key" \
  -d '{
    "name": "Ежедневная рассылка",
    "filter_chats": {
      "all": [
        { "platform": "Telegram", "type": "attribute" }
      ]
    },
    "content_type": "NODE",
    "node_name": "Дайджест",
    "regular_cron": "00 12 * * *"
  }'

# WABA рассылка по файлу с номерами телефонов
curl -X POST https://dashboard.fstrk.io/api/partners/mailings/ \
  -H "Content-Type: application/json" \
  -H "bot-key: your_bot_key" \
  -d '{
    "name": "WABA акция",
    "phone_numbers_file": "https://example.com/phones.xlsx",
    "content_type": "TEMPLATE_WHATSAPP",
    "template_whatsapp": "order_confirmation",
    "template_variables": {
      "v1": { "type": "GLOBAL", "value": "Акция!" },
      "v2": { "type": "FILE" }
    }
  }'

# Рассылка по UUID-профилям из файла
curl -X POST https://dashboard.fstrk.io/api/partners/mailings/ \
  -H "Content-Type: application/json" \
  -H "bot-key: your_bot_key" \
  -d '{
    "name": "VIP рассылка",
    "customer_filter_field": "UUID",
    "customer_filter_file": "https://example.com/vip_uuids.csv",
    "content_type": "NODE",
    "node_name": "VIP узел"
  }'
```

***

#### GET /api/partners/mailings/{uuid}/

🔒 *bot-key или OAuth*

**Кратко:** Получить информацию о рассылке по UUID.

**Параметры пути:**

* `uuid` (string, обязательный) — UUID рассылки

**Возвращает:** `200 OK` — объект `Mailing` со статистикой.

<details>

<summary>Пример ответа:</summary>

{% code overflow="wrap" %}

```json
{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Летняя акция",
  "state": "completed",
  "content_type": "TEXT",
  "text": "Привет! Специальное предложение только сегодня 🎁",
  "created_at": "2024-06-01T09:00:00Z",
  "planned_at": null,
  "completed_at": "2024-06-01T09:45:00Z",
  "duration": "00:45:00",
  "statistics": {
    "count_planned": 10000,
    "count_sent": 9850,
    "count_delivered": 9600,
    "count_undelivered": 250,
    "count_read": 7200,
    "count_clicked": 1500,
    "count_jumped_url": 1100,
    "count_replied": 430,
    "count_platforms": {
      "Telegram": 6000,
      "Vkontakte": 4000
    }
  }
}
```

{% endcode %}

</details>

**Ошибки:** 401 — ошибка авторизации; 404 — рассылка не найдена.

**Пример запроса:**

```bash
curl -X GET https://dashboard.fstrk.io/api/partners/mailings/3fa85f64-5717-4562-b3fc-2c963f66afa6/ \
  -H "bot-key: your_bot_key"
```

***

#### POST /api/partners/mailings/{uuid}/calculate/

🔒 *bot-key или OAuth*

**Кратко:** Пересчитать статистику рассылки.

**Параметры пути:**

* `uuid` (string, обязательный) — UUID рассылки

**Параметры:** Нет.

**Возвращает:** `200 OK` — объект `Mailing` с обновлённой статистикой.

**Ошибки:** 401 — ошибка авторизации; 404 — рассылка не найдена.

**Пример запроса:**

```bash
curl -X POST https://dashboard.fstrk.io/api/partners/mailings/3fa85f64-5717-4562-b3fc-2c963f66afa6/calculate/ \
  -H "bot-key: your_bot_key"
```

***

#### POST /api/partners/mailings/{uuid}/stop/

🔒 *bot-key или OAuth*

**Кратко:** Остановить запущенную рассылку.

**Параметры пути:**

* `uuid` (string, обязательный) — UUID рассылки

**Параметры:** Нет.

**Возвращает:** `200 OK` — объект `Mailing` с обновлённым статусом.

**Ошибки:** 401 — ошибка авторизации; 404 — рассылка не найдена.

**Пример запроса:**

```bash
curl -X POST https://dashboard.fstrk.io/api/partners/mailings/3fa85f64-5717-4562-b3fc-2c963f66afa6/stop/ \
  -H "bot-key: your_bot_key"
```