Получатели

SMS

VK OK

ВКонтакте (Одноклассники)

ЗВОНКИ И ГОЛОСОВЫЕ ОПОВЕЩЕНИЯ

КАСКАД

Каскадная рассылка

ТОКЕН

Авторизация по токену

E-MAIL

Получатели

Создание получателя

Метод создает получателя в группе получателей. При создании нового получателя вы можете прикреплять дополнительную информацию в виде тегов или параметров получателя. Параметры имеют название и значения, которые присоединены к получателю в рамках группы. Теги — это дополнительная информация (метка) получателя, которая прикреплена в рамках аккаунта и доступна во всех группах где будет создан получатель с аналогичным email

Вы можете использовать Параметры и Теги для персонализации макета письма и фильтрации при создании рассылок из личного кабинета.

Пример JSON для запроса

{
  "email":"alice@example.org",
  "unconfirmed": true,
  "values":[
    {
      "parameter_id":"1",
      "value":"Alice"
    },
    {
      "parameter_id":"2",
      "value":"22"
    }
  ],
  "tags":[
    "buyer",
    "regular customer"
  ]
}

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

curl -X POST https://app.smsgold.ru/v1/email/lists/1/recipients \
     -H 'Content-Type: application/json'                       \
     -H 'Authorization: Bearer $API_TOKEN'                     \
     -d '...JSON...'

Пример ответа в случае успеха

{
  "id":1,
  "email":"alice@example.org",
  "confirmed":false,
  "list_id":1,
  "status": "active",
  "values":[
    {
      "value":"Alice",
      "kind":"string",
      "parameter_id":1
    },
    {
      "value":22.0,
      "kind":"numeric",
      "parameter_id":2
    }
  ],
  "tags":[
    "buyer",
    "regular customer"
  ]
}

POST /email/lists/:id/recipients

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

Параметр	Описание	Обязательный
email	email получателя	Да
unconfirmed	Создать неподтвержденного получателя. Необходимо задать любое значение, например, true, t или 1. По умолчанию создается подтвержденный получатель	Нет
values	Массив значений с параметрами получателя	Нет
tags	Массив значений с тегами получателя	Нет

Элементы массива значений с параметрами получателя

Параметр	Описание	Обязательный
parameter_id	ID параметра группы получателей	Да
value	Значение параметра	Да

Элементы массива значений с тегами получателя*

Массив значений тегов состоит из обычного массива. Например, ['tag1', 'tag2']

Ответ сервера

Ответ сервера содержит JSON со следующими атрибутами:

Атрибут	Описание
id	Идентификатор
email	Адрес
confirmed	Подтвержден получатель или нет
status	Статус получателя. Возможные значения: active, incorrect, unconfirmed, unsubscribed
values	Массив значений параметров
tags	Массив значений тегов

Элементы массива значений параметров

Параметр	Описание
parameter_id	ID параметра группы получателей
kind	Тип параметра
value	Значение параметра

Информация о получателе

Данный метод позволяет получить информацию о получателе по ID.

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

curl -X GET https://app.smsgold.ru/v1/email/lists/1/recipients/2 \
     -H 'Content-Type: application/json'                   \
     -H 'Authorization: Bearer $API_TOKEN'

Пример ответа в случае успеха

{
  "id":2,
  "email":"alice@example.org",
  "confirmed":false,
  "list_id":1,
  "status": "active",
  "values":[
    {
      "value":"Alice",
      "kind":"string",
      "parameter_id":1
    },
    {
      "value":22.0,
      "kind":"numeric",
      "parameter_id":2
    }
  ],
  "tags":[
    "buyer",
    "regular customer"
  ]
}

GET /email/lists/:list_id/recipients/:id

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

Параметр	Описание	Обязательный
list_id	ID группы	Да
id	ID получателя	Да

Ответ сервера

Ответ сервера содержит JSON со следующими атрибутами:

Атрибут	Описание
id	Идентификатор
email	Адрес
confirmed	Подтвержден получатель или нет
status	Статус получателя. Возможные значения: active, incorrect, unconfirmed, unsubscribed
values	Массив значений
tags	Массив значений тегов

Элементы массива значений

Параметр	Описание
parameter_id	ID параметра группы получателей
kind	Тип параметра
value	Значение

Обновление получателя

Этот метод позволяет обновить параметры и теги получателя

Пример JSON для запроса

{
  "email":"alice@example.org",
  "values":[
    {
      "parameter_id":"1",
      "value":"Alice"
    },
    {
      "parameter_id":"2",
      "destroy":"true"
    }
  ],
  "tags":[
    {
      "value":"buyer"
    },
    {
      "value":"customer",
      "destroy":"true"
    }
  ]
}

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

curl -X PATCH https://app.smsgold.ru/v1/email/lists/1/recipients/1 \
     -H 'Content-Type: application/json'                     \
     -H 'Authorization: Bearer $API_TOKEN'                   \
     -d '...JSON...'

Пример ответа в случае успеха

{
  "id":1,
  "email":"alice@example.org",
  "confirmed":true,
  "status": "active",
  "list_id":1,
  "values":[
    {
      "value":"Alice",
      "kind":"string",
      "parameter_id":1
    }
  ],
  "tags":[
    "buyer",
    "regular customer"
  ]
}

PATCH /email/lists/:list_id/recipients/:id

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

Параметр	Описание	Обязательный
email	Email получателя	Да
values	Массив значений параметров получателя	Нет
tags	Массив значений тегов	Нет
run_triggers	Запустить связанные триггеры. Необходимо задать любое значение, например, true, t или 1.	Нет

Элементы массива значений параметра values

Параметр	Описание	Обязательный
parameter_id	ID параметра группы получателей	Да
value	Не может быть одновременно использован с параметром destroy	Нет
destroy	Используется для удаления значения. Для удаления значения необходимо задать любое значение, например, true, t или 1. Не может быть использован одновременно с параметром value	Нет

Элементы массива значений параметра tags

tags состоит из массива значений [ 'tag1', 'tag2', 'tag3' ]

Ответ сервера

Ответ сервера содержит JSON со следующими атрибутами:

Атрибут	Описание
id	Идентификатор
email	Адрес
confirmed	Подтвержден получатель или нет
status	Статус получателя. Возможные значения: active, incorrect, unconfirmed, unsubscribed
values	Массив значений
tags	Массив значений тегов

Элементы массива значений

Параметр	Описание
parameter_id	ID параметра группы получателей
kind	Тип параметра
value	Значение параметра

Список получателей

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

curl -X GET https://app.smsgold.ru/v1/email/lists/1/recipients \
     -H 'Content-Type: application/json'                 \
     -H 'Authorization: Bearer $API_TOKEN'

Данный метод поддерживает постраничную выдачу результатов. Максимальный page_size равняется 1000.

Пример ответа в случае успеха

{
  "total_count":2,
  "total_pages":1,
  "page_number":1,
  "page_size":25,
  "collection":[
    {
      "id":1,
      "email":"alice@example.org",
      "confirmed":true,
      "status": "active",
      "list_id":1,
      "values":[
        {
          "value":"Alice",
          "kind":"string",
          "parameter_id":9
        },
        {
          "value":22.0,
          "kind":"numeric",
          "parameter_id":10
        }
      ],
      "tags":[
        "buyer",
        "regular customer"
      ]
    },
    {
      "id":2,
      "email":"bob@example.org",
      "confirmed":true,
      "status": "active",
      "list_id":1,
      "values":[
      ],
      "tags":[
      ]
    }
  ]
}

GET /email/lists/:id/recipients

Ответ сервера

Ответ сервера содержит коллекцию получателей группы. Каждый элемент содержит следующие атрибуты:

Атрибут	Описание
id	Идентификатор получателя
email	Email получателя
confirmed	Подтвержден получатель или нет
status	Статус получателя. Возможные значения: active, incorrect, unconfirmed, unsubscribed
values	Массив значений параметра получателей
tags	Массив значений тегов

Элементы массива значений values

Параметр	Описание
parameter_id	ID параметра группы получателей
kind	Тип параметра
value	Значение

Удаление получателя

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

curl -X DELETE https://app.smsgold.ru/v1/email/lists/1/recipients/1 \
     -H 'Content-Type: application/json'                      \
     -H 'Authorization: Bearer $API_TOKEN'

DELETE /email/lists/:list_id/recipients/:id

Импорт большого количества получателей

POST /email/lists/:id/recipients/imports

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

Параметр	Описание	Обязательный
recipients	Массив получателей. Максимальный размер 10000	Да
run_triggers	Запустить связанные триггеры. Возможные значения: `trigger_any` `trigger_fresh`	Нет
tags	Массив значений тегов	Нет
callback_url	url, на который будет отправлен запрос после завершения импорта	Нет

Массив получателей recipients

Параметр	Описание	Обязательный
email	Email получателя	Да
values	Массив значений параметров	Нет

Элементы массива значений values

Параметр	Описание	Обязательный
parameter_id	ID параметра группы получателей	Да
value	Значение параметра	Да

Параметр run_triggers

Значение	Описание
trigger_any	Запустить связанные триггеры для всех получателей
trigger_fresh	Запустить связанные триггеры только для новых получателей

Ответ сервера

Параметр	Описание
id	Идентификатор импорта. В дальнейшем может использоваться для получения информации о ходе импорта
status	Статус импорта
callback_url	url, на который будет отправлен запрос после окончания импорта

Пример JSON для запроса

{
  "recipients":[
    {
      "email":"alice@example.org",
      "values":[
        {
          "parameter_id":"1",
          "value":"Alice"
        },
        {
          "parameter_id":"2",
          "value":"22"
        }
      ]
    },
    {
      "email":"bob@example.org",
      "values":[
        {
          "parameter_id":"1",
          "value":"Bob"
        },
        {
          "parameter_id":"2",
          "value":"11"
        }
      ]
    }
  ],
  "tags":[
    "buyer",
    "regular customer"
  ]
}

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

curl -X POST https://app.smsgold.ru/v1/email/lists/1/recipients/imports \
     -H 'Content-Type: application/json'                       \
     -H 'Authorization: Bearer $API_TOKEN'                     \
     -d '...JSON...'

Пример ответа в случае успеха

{
  "id":7,
  "status":"queued",
  "callback_url": null
}

Пример запроса после окончания импорта, если указан callback url

{
  "id":7,
  "status":"completed",
  "callback_url":"https://my-callback-url.com/some-secret"
}

Поиск получателей

Метод осуществляет поиск получателя по email, например, чтобы определить в каких группах он присутствует.

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

curl -X GET https://app.smsgold.ru/v1/email/recipients/search?email=foo@bar.com \
     -H 'Content-Type: application/json'                                  \
     -H 'Authorization: Bearer $API_TOKEN'

Пример ответа в случае успеха

{
  "total_count": 2,
  "total_pages": 1,
  "page_number": 1,
  "page_size": 25,
  "collection": [
    {
      "email": "foo@bar.com",
      "recipients": [
        {
          "list_id": 1,
          "list_title": "List #1",
          "recipient_id": 1
        },
        {
          "list_id": 2,
          "list_title": "List #2",
          "recipient_id": 2
        }
      ]
    }
  ],
  "query": "test"
}

GET /email/recipients/search

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

Параметр	Описание	Обязательный
email	Искомый адрес	Да

Ответ сервера

Ответ сервера содержит коллекцию получателей в группе. Каждый элемент содержит следующие атрибуты:

Атрибут	Описание
email	Email получателя
recipients	Массив, содержащий информацию о списках, в которых найден получатель

Сегменты

Список сегментов

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

curl -X GET https://app.smsgold.ru/v1/email/segments \
     -H 'Content-Type: application/json'       \
     -H 'Authorization: Bearer $API_TOKEN'

Данный метод поддерживает постраничную выдачу результатов. Максимальный page_size равняется 1000.

Пример ответа в случае успеха

{
  "total_count":2,
  "total_pages":1,
  "page_number":1,
  "page_size":25,
  "collection":[
     {
       "id" : 1,
       "title" : "Segment Number One"
     }
  ]
}

GET /email/segments

Ответ сервера

Ответ сервера содержит коллекцию сегментов. Каждый элемент содержит следующие атрибуты:

Атрибут	Описание
id	Идентификатор сегмента
title	Название сегмента

Рекламные/
Сервисные рассылки

Авторизация/
Аутентификация

В реестре отечественного ПО

Получатели

SMS

VK OK

ЗВОНКИ И ГОЛОСОВЫЕ ОПОВЕЩЕНИЯ

TELEGRAM

КАСКАД

ТОКЕН

E-MAIL

Получатели

Создание получателя

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

Ответ сервера

Информация о получателе

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

Ответ сервера

Обновление получателя

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

Ответ сервера

Список получателей

Ответ сервера

Удаление получателя

Импорт большого количества получателей

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

Ответ сервера

Поиск получателей

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

Ответ сервера

Сегменты

Список сегментов

Ответ сервера