Для разработчиков

API для email-рассылок

Управляйте рассылками, подписчиками и шаблонами писем со своего сайта, не заходя в аккаунт: 7 интерфейсов, 29 методов и обратные вызовы о событиях в реальном времени.

XML или JSON
ключ из 32 символов
UTF-8
тарифы Basic и Pro

Войти в кабинет Тарифы с API

интерфейсы

api.falconsender.ru/deliveries.html5 методов
api.falconsender.ru/files.html3 метода
api.falconsender.ru/templates.html5 методов
api.falconsender.ru/subscribers.html6 методов
api.falconsender.ru/subscribe.html3 метода
api.falconsender.ru/groups.html1 метод
api.falconsender.ru/stats.html6 методов

Общие сведения

API сервиса Falconsender позволяет управлять вашим аккаунтом автора, не заходя в него, то есть удалённо — например, с вашего сайта.

Доступ	Только авторам на платных тарифах — Basic и Pro
Кодировка	UTF-8 для передачи всех данных
Формат ответа	XML по умолчанию, JSON — по параметру `format`
Интерфейсов	7, у каждого свой адрес

Параметры любого запроса

Любой из запросов может включать в себя следующие параметры.

Параметр	Описание
`format`	Формат ответа сервера — XML (по умолчанию) или JSON (если в запросе указана специальная переменная).
`fields`	Наименования полей, указанные через запятую, которые могут быть получены в результате запроса. Например, вам необходимо получить лишь ID и названия рассылок, нужно будет указать fields=id,title в запросе к соответствующему интерфейсу и т.д. По умолчанию возвращаются все наименования полей.
`fields_exclude`	Наименования полей, указанные через запятую, которые должны быть исключены из результата запроса. Например, вам необходимо получить все поля из интерфейса списка шаблонов за исключением html_body и text_body , тогда нужно будет указать fields_exclude=html_body,text_body .

Аутентификация

В качестве аутентификации используется уникальный 32-символьный API-ключ. Чтобы получить доступ ко всем интерфейсам, нужен только он.

Параметр	Описание
`api_key`обязательный	Уникальный 32-символьный API-ключ. Получить данный ключ можно в настройках аккаунта автора в разделе "API". Чтобы получить доступ ко всем API-интерфейсам необходим только данный ключ.

Формат ответа

Каждый ответ содержит результат выполнения, ошибку, если она возникла, и данные интерфейса.

xml

<response>
<result></result>
<error code="" message=""/>
<данные>
...
<данные>
</response>

Поле Описание

Поле	Описание
`result`	Результат исполнения запроса. `1` — запрос исполнен удачно (не возникло системных ошибок) `0` — запрос не исполнен или исполнен с ошибками
`error`	Если во время выполнения возникли какие-либо ошибки, то данное поле содержит код ошибки ( code ) и текст сообщения об ошибке ( message ). Если ошибок не возникло, поле error отсутствует
`данные`	Набор полей с данными того или иного API-интерфейса. Поля разнятся в зависимости от выбранного интерфейса. Если интерфейс не возвращает никаких данных, данные могут отсутствовать.

result

Результат исполнения запроса.

1 — запрос исполнен удачно (не возникло системных ошибок)
0 — запрос не исполнен или исполнен с ошибками

error Если во время выполнения возникли какие-либо ошибки, то данное поле содержит код ошибки ( code ) и текст сообщения об ошибке ( message ). Если ошибок не возникло, поле error отсутствует

данные Набор полей с данными того или иного API-интерфейса. Поля разнятся в зависимости от выбранного интерфейса. Если интерфейс не возвращает никаких данных, данные могут отсутствовать.

Рассылки

Список рассылок, создание, редактирование и удаление, управление шаблонами внутри автоматической серии.

URL интерфейсаhttp://api.falconsender.ru/deliveries.html

Список рассылок

action=list

Параметр	Описание
`action`обязательный	`list` — получение списка рассылок
`id`	Если есть необходимость получить не весь список рассылок, а только некоторые из них, можно указать их id через запятую. В противном случае в ответе будет содержаться весь список.

Ответ

xml

<response>
 <result></result>
 <list count="">
  <element>
   <id></id>
   <date_started></date_started>
   <date_updated></date_updated>
   <lang></lang>
   <title></title>
   <ar_state></ar_state>
   <author_name></author_name>
   <email_from></email_from>
   <subscriber_default_name></subscriber_default_name>
   <url_redirect></url_redirect>
   <url_redirect_activation></url_redirect_activation>
   <url_redirect_unsubscribe></url_redirect_unsubscribe>
   <cnt_subscribers></cnt_subscribers>
   <cnt_subscribers_active></cnt_subscribers_active>
   <cnt_subscribers_activation></cnt_subscribers_activation>
   <counter_key></counter_key>
   <templates>
    <template id="" offset_days="" f_offset_date="" offset_hour="" offset_minute="" subject=""/>
   </templates>
  </element>
  <element>
  ...
  </element>
 </list>
</response>

Создание/редактирование рассылки

action=create

Параметр	Описание
`action`обязательный	`create` — создание рассылки `update` — редактирование рассылки
`id`	ID рассылки. Передавать только в том случае, если необходимо редактировать определенную рассылку
`lang`обязательный	Язык рассылки: `ru` — русский `en` — английский
`title`обязательный	Название рассылки (не более 128 символов)
`author_name`обязательный	Имя автора рассылки
`email_from`обязательный	Обратный email-адрес рассылки
`subscriber_default_name`	Если у подписчика не указано имя, значение будет подставлено вместо [first_name]
`url_redirect`	URL для переадресации после подписки
`url_redirect_activation`	URL для переадресации после подтверждения подписки
`url_redirect_unsubscribe`	URL для переадресации после отписки или удаления

Ответ

xml

<response>
 <result></result>
 <id></id>
</response>

Удаление рассылки

action=delete

Параметр	Описание
`action`обязательный	`delete` — удалить рассылку
`id`обязательный	ID рассылки для удаления. Через запятую можно перечислить несколько ID.

Ответ

xml

<response>
 <result></result>
</response>

Добавление/редактирование шаблона в серии

action=add_template

Параметр	Описание
`action`обязательный	`add_template` — добавить шаблон в серию писем
`delivery_id`обязательный	ID рассылки, в которую вы хотите добавить шаблон или шаблон которой вы хотите изменить
`template_id`обязательный	ID шаблона, который вы хотите добавить в серию писем или данные которого вы хотите изменить
`offset_days`обязательный	На какой день отправлять шаблон после подписки.
`f_offset_date`	Использовать ли смещение отправки в часах и минутах (значение 1 — да, 0 - нет)
`offset_hour`	Час отправки ( 0 — 23 )
`offset_minute`	Минута отправки ( 0 — 59 )

Ответ

xml

<response>
 <result></result>
</response>

Исключение шаблона из серии писем

action=remove_template

Параметр	Описание
`action`обязательный	`remove_template` — исключение
`delivery_id`обязательный	ID серии писем из которой вы хотите исключить шаблон
`template_id`обязательный	ID шаблона, который вы хотите исключить. Через запятую можно указать несколько ID.

Ответ

xml

<response>
 <result></result>
</response>

Файлы

Файлы, которые потом прикрепляются к шаблонам и письмам.

URL интерфейсаhttp://api.falconsender.ru/files.html

Список файлов

action=list

Параметр	Описание
`action`обязательный	`list` — получение списка файлов
`id`	Если есть необходимость получить не весь список файлов, а только некоторые из них, можно указать их id через запятую. В противном случае в ответе будет содержаться весь список.

Ответ

xml

<response>
 <result></result>
 <list count="">
  <element>
   <id></id>
   <date_created></date_created>
   <date_updated></date_updated>
   <name></name>
   <mime></mime>
   <size></size>
   <url_external></url_external>
  </element>
  <element>
  ...
  </element>
 </list>
</response>

Поля ответа

Поле	Описание
`list`	`count` — количество записей
`list/element`	Описание файла
`id`	ID файла
`date_created`	Дата создания в формате ДД/ММ/ГГГГ ЧЧ:ММ:СС (+02GMT)
`date_updated`	Дата изменения в формате ДД/ММ/ГГГГ ЧЧ:ММ:СС (+02GMT)
`name`	Название файла
`mime`	MIME-тип
`size`	Размер файла в байтах
`url_external`	Внешний URL для загрузки файла

Загрузка/обновление файла

action=upload

Параметр	Описание
`action`обязательный	`upload` — загрузка файла
`name`обязательный	Название файла (не более 128 символов). Если необходимо обновить уже загруженный файл, следует загрузить отредактированный файл с идентичным названием.
`mime`обязательный	MIME-тип файла
`content`обязательный	Важно! Содержимое файла обязательно кодировать в BASE64.

Ответ

xml

<response>
 <result></result>
 <id></id>
</response>

Поля ответа

Поле	Описание
`id`	ID файла возвращается только в том случае, если был загружен новый файл.

Удаление файла

action=delete

Параметр	Описание
`action`обязательный	`delete` — удаление
`id`	ID файла для удаления. Через запятую можно указать несколько ID.

Ответ

xml

<response>
 <result></result>
</response>

Шаблоны писем

Шаблоны писем: текстовая и HTML-часть, прикреплённые файлы.

URL интерфейсаhttp://api.falconsender.ru/templates.html

Список шаблонов

action=list

Параметр	Описание
`action`обязательный	`list` — получение списка шаблонов
`id`	Если есть необходимость получить не весь список шаблонов, а только некоторые из них, можно указать их id через запятую. В противном случае в ответе будет содержаться весь список.
`delivery_id`	ID рассылки, из которой вы хотите получить шаблоны.
`sortorder`	Сортировка шаблонов: `date_created` — по дате создания `subject` — тема шаблона `offset_days` — дате отправки шаблона

Ответ

xml

<response>
 <result></result>
 <list count="">
  <element>
   <id></id>
   <delivery_id></delivery_id>
   <date_created></date_created>
   <date_updated></date_updated>
   <code></code>
   <subject></subject>
   <offset_days></offset_days>
   <offset_hour></offset_hour>
   <offset_minute></offset_minute>
   <text_body></text_body>
   <f_text_wrap></f_text_wrap>
   <text_wrap_cnt></text_wrap_cnt>
   <html_body></html_body>
   <files count="">
    <file id="" name="" size=""/>
    ...
    <file .../>
   </files>
  </element>
  <element>
  ...
  </element>
 </list>
</response>

Поля ответа

Поле	Описание
`list`	`count` — количество записей
`id`	ID шаблона
`delivery_id`	ID серии писем, в которую добавлен шаблон. Если не добавлен ни в одну из серий, значение равно нулю.
`date_created`	Дата создания в формате ДД/ММ/ГГГГ ЧЧ:ММ:СС (+02GMT)
`date_updated`	Дата изменения в формате ДД/ММ/ГГГГ ЧЧ:ММ:СС (+02GMT)
`code`	Код шаблона. Допустимы только латинские буквы и цифры.
`subject`	Тема шаблона (не более 128 символов)
`offset_days`	На какой день отправляется шаблон в серии писем, если он туда добавлен.
`offset_hour`	Часы отправки в указанный день.
`offset_minute`	Минуты отправки в указанный день
`text_body`	Текстовая часть шаблона
`text_wrap_cnt`	Ширина строки в символах (до 70)
`html_body`	HTML-часть шаблона
`files`	Список файлов, прикрепленных к шаблону (count — количество файлов). В случае отсутствия элемента - к шаблону не прикреплены файлы.
`files/file`	Описание файла: `id` — ID файла `name` — название файла `size` — размер файла (в байтах)

Создание/редактирование шаблона

action=create

Параметр	Описание
`action`обязательный	`create` — создание шаблона `update` — обновление шаблона
`id`	ID шаблона. Передавать только в том случае, если есть необходимость в редактировании шаблона.
`code`	Код шаблона. Допустимы только латинские буквы и цифры.
`subject`	Тема шаблона (не более 128 символов)
`text_body`	Текстовая часть шаблона
`f_text_wrap`	Форматировать ширину строки. 0 — да, 1 - нет.
`text_wrap_cnt`	Ширина строки в символах (до 70)
`html_body`	HTML-часть шаблона

Ответ

xml

<response>
 <result></result>
 <id></id>
</response>

Поля ответа

Поле	Описание
`id`	ID шаблона возвращается только в случае, если был добавлен новый шаблон.

Удаление шаблона

action=delete

Параметр	Описание
`action`обязательный	`delete` — удаление
`id`обязательный	ID шаблона для удаления. Через запятую можно указать несколько ID.

Ответ

xml

<response>
 <result></result>
</response>

Прикрепление файла к шаблону

action=attach_file

Параметр	Описание
`action`обязательный	`attach_file` — прикрепить файл к шаблону
`template_id`обязательный	ID шаблона, к которому необходимо прикрепить файл
`file_id`обязательный	ID файла, который необходимо прикрепить. Через запятую можно указать несколько ID.

Ответ

xml

<response>
 <result></result>
</response>

Удаление файла из шаблона

action=deattach_file

Параметр	Описание
`action`обязательный	`deattach_file` — открепление файла от шаблона
`template_id`обязательный	ID шаблона, от которого вы хотите открепить файл
`file_id`обязательный	ID файла, который вы хотите исключить из списка файлов шаблона. Через запятую можно указать несколько ID.

Ответ

xml

<response>
 <result></result>
</response>

Подписчики

База подписчиков: выборка по фильтрам, добавление, обновление, удаление и распределение по рассылкам и группам.

URL интерфейсаhttp://api.falconsender.ru/subscribers.html

Список подписчиков

action=list

Параметр	Описание
`action`обязательный	`list` — Получение списка подписчиков
`sortorder`	Сортировка списка: `date_added` — по дате добавления `email` — по email-адресу По умолчанию — по убыванию даты добавления
`sortorderdir`	Направление сортировки: `0` — значение по умолчанию `1` — изменить на противоположное
`records_on_page`	Количество записей на странице (от 1 до 1000)
`page`	Номер страницы выборки, начиная с 0
`id`	Если есть необходимость получить не весь список подписчиков, а только некоторых из них, можно указать их id через запятую. В противном случае в ответе будет содержаться весь список.
`search[...]`	Критерии поиска подписчиков: `search[date_from_day]` (день), `search[date_from_month]` (месяц), `search[date_from_year]` (год) — подписчики, попавшие в список позже выбранной даты в формате ДД.ММ.ГГГГ `search[date_to_day]` (день), `search[date_to_month]` (месяц), `search[date_to_year]` (год) — подписчики, попавшие в список ранее выбранной даты в формате ДД.ММ.ГГГГ `search[email]` — поиск по email-адресу `search[name_first]` — по имени `search[name_mid]` — по отчеству `search[name_last]` — по фамилии `search[email_state]` — состояние адреса: `disabled` — несуществующий `active` — активированный `activation` — неактивированный `search[country_id]` — по ID страны `search[city]` — по городу `search[address]` — по адресу `search[phones]` — по телефону `search[sex]` — по полу: 0 - если не указан, m - мужской, w - женский `search[queue]` — 0 - не получают серии, 1 - получают `search[birth_day]` (день), `search[birth_month]` (месяц), `search[birth_year]` (год) — дата рождения `search[deliveries_ids]` — id рассылок через запятую `search[f_included_in_deliveries]` — 1 - подписаны на рассылки, указанные в search[deliveries_ids], 0 - не подписаны `search[groups_ids]` — id групп через запятую

Ответ

xml

<response>
 <result></result>
 <list count="">
  <element>
   <id></id>
   <date_added></date_added>
   <state></state>
   <email></email>
   <first_name></first_name>
   <middle_name></middle_name>
   <last_name></last_name>
   <sex></sex>
   <country></country>
   <city></city>
   <address></address>
   <phones></phones>
   <birth_year></birth_year>
   <birth_month></birth_month>
   <birth_day></birth_day>
   <homepage></homepage>
   <extra_fields>
     <field id="" value=""/>
   </extra_fields>
   <deliveries>
    <delivery id="" date_added=""/>
    ...
   </deliveries>
   <groups>
    <group id="" date_added=""/>
    ...
   </groups>
  </element>
  <element>
  ...
  </element>
 </list>
</response>

Поля ответа

Поле	Описание
`id`	ID подписчика
`date_added`	Дата добавления в формате ДД/ММ/ГГГГ ЧЧ:ММ:СС (+02GMT)
`state`	Состояние подписчика в вашем списке: `active` — активированный `activation` — неактивированный `disabled` — несуществующий email-адрес
`email`	Email-адрес
`first_name`	Имя
`middle_name`	Отчество
`last_name`	Фамилия
`sex`	Пол: w — женский, m - мужской
`country`	Страна
`element/country_id`	ID страны
`city`	Город
`address`	Адрес
`phones`	Телефон
`birth_year`	Год рождения
`birth_month`	Месяц рождения
`birth_day`	День рождения
`extra_fields`	Дополнительные поля подписчика: id — код поля, value - значение
`deliveries`	Рассылки, на которые подписан подписчик, где id — id рассылок, date_added - дата подписки в формате ДД:ММ:ГГГГ ЧЧ:ММ:СС
`groups`	Группы, в которые добавлен подписчик, где id — id групп, date_added - дата добавления в формате ДД:ММ:ГГГГ ЧЧ:ММ:СС

Добавление/редактирование подписчика

action=create

Параметр	Описание
`action`обязательный	`create` — добавление `update` — обновление данных подписчика
`id`	ID подписчика, данные которого вы хотите обновить. Передавать только при обновлении.
`delivery_id`	ID рассылки для подписки Обязательный параметр при добавлении нового подписчика
`group_id`	ID группы, в которую будет включен подписчик после добавления. Через запятую можно указать несколько id.
`email`	Обязательный параметр при добавлении нового подписчика, в дальнейшем неизменяем.
`first_name`	Имя
`middle_name`	Отчество
`last_name`	Фамилия
`birth_year`	Год рождения
`birth_month`	Месяц рождения
`birth_day`	День рождения
`sex`	Пол: m — мужской, w - женский
`country_id`	ID страны
`city`	Город
`address`	Адрес
`company`	Компания
`homepage`	URL сайта
`phones`	Номера телефонов
`extra_[код]`	Дополнительные поля подписчика

Ответ

xml

<response>
 <result></result>
 <id></id>
</response>

Поля ответа

Поле	Описание
`id`	ID подписчика возвращается только в случае добавления нового подписчика

Удаление из списка

action=delete

Параметр	Описание
`action`обязательный	`delete` — удаление
`id`обязательный	ID подписчика для удаления. Через запятую можно указать несколько ID.

Ответ

xml

<response>
 <result></result>
 <count_deleted></count_deleted>
</response>

Добавление в рассылку или группу

action=link_with_delivery

Параметр	Описание
`action`обязательный	`link_with_delivery` — добавление в рассылку (подписчик НЕ начнёт получать письма из серии), `link_with_group` — добавление в группу Советуем изначально делать запрос с получением списка подписчиков, далее если он вас устроит производить данный запрос, заменив action.
`delivery_id`	ID рассылки, в которую вы хотите добавить подписчика. Через запятую можно указать несколько ID.
`group_id`	ID группы, в которую вы хотите добавить подписчика. Через запятую можно указать несколько ID.

Ответ

xml

<response>
 <result></result>
</response>

Исключение из рассылки или группы

action=unlink_with_delivery

Параметр	Описание
`action`обязательный	`unlink_with_delivery` — исключение из рассылки, `unlink_with_group` — исключение из группы Советуем изначально делать запрос с получением списка подписчиков, далее если он вас устроит производить данный запрос, заменив action.
`delivery_id`	ID рассылки, из списка которой вы хотите исключить подписчика. Через запятую можно указать несколько ID.
`group_id`	ID группы, из списка которой вы хотите исключить подписчика. Через запятую можно указать несколько ID.

Ответ

xml

<response>
 <result></result>
</response>

Проверка нахождения адреса в списке

action=check_email

Параметр	Описание
`action`	`check_email` — проверка нахождения email-адреса в списке
`email`	Email-адреса, которые нужно найти. Можно указать до 300 через запятую

Ответ

xml

<response>
 <result></result>
 <list count="">
   <subscriber id="" email=""/>
   ...
 </list>
</response>

Подписка и отправка писем

Подписка на рассылку и отправка писем — готового шаблона или нового письма.

URL интерфейсаhttp://api.falconsender.ru/subscribe.html

Подписка на рассылку

action=on_delivery

Параметр	Описание
`action`обязательный	`on_delivery` — подписка на рассылку
`delivery_id`обязательный	ID рассылки, на которую будет подписан подписчик. Через запятую можно указать несколько рассылок. Подписчик сразу начнет получать письма серии.
`id`	ID подписчиков, которых вы хотите подписать на выбранную рассылку. ID указываются через запятую. По умолчанию, если не указать параметр ID, на рассылку будет подписан весь список
`search[...]`	Критерии поиска подписчиков: `search[date_from_day]` (день), `search[date_from_month]` (месяц), `search[date_from_year]` (год) — подписчики, попавшие в список позже выбранной даты в формате ДД.ММ.ГГГГ `search[date_to_day]` (день), `search[date_to_month]` (месяц), `search[date_to_year]` (год) — подписчики, попавшие в список ранее выбранной даты в формате ДД.ММ.ГГГГ `search[email]` — поиск по email-адресу `search[name_first]` — по имени `search[name_mid]` — по отчеству `search[name_last]` — по фамилии `search[email_state]` — состояние адреса: `disabled` — несуществующий `active` — активированный `activation` — неактивированный `search[country_id]` — по ID страны `search[city]` — по городу `search[address]` — по адресу `search[phones]` — по телефону `search[sex]` — по полу: 0 - если не указан, m - мужской, w - женский `search[queue]` — 0 - не получают серии, 1 - получают `search[birth_day]` (день), `search[birth_month]` (месяц), `search[birth_year]` (год) — дата рождения `search[deliveries_ids]` — id рассылок через запятую `search[f_included_in_deliveries]` — 1 - подписаны на рассылки, указанные в search[deliveries_ids], 0 - не подписаны `search[groups_ids]` — id групп через запятую

Ответ

xml

<response>
 <result></result>
</response>

Отправка шаблона

action=on_template

Параметр	Описание
`action`обязательный	`on_template` — отправка шаблона указанному списку подписчиков.
`template_id`обязательный	ID шаблона
`from_name`обязательный	Имя отправителя письма
`from_email`обязательный	Обратный email-адрес
`archive_delivery_id`	ID рассылки, в архив которой будет положено письмо после отправки, если это необходимо.

Ответ

xml

<response>
 <result></result>
 <job_id></job_id>
</response>

Поля ответа

Поле	Описание
`job_id`	ID созданного задания на отправку

Отправка нового письма

action=on_message

Параметр	Описание
`action`обязательный	`on_message` — отправка нового письма
`from_name`обязательный	Имя отправителя письма
`from_email`обязательный	Обратный email-адрес
`subject`	Тема письма
`text_body`	Текстовая часть письма
`text_wrap_cnt`	Ширина строки в символах (до 70)
`html_body`	HTML-часть письма
`shift_date`	Планирование отправки письма на более поздний срок. Необходимо указать дату отправки в формате ДД.ММ.ГГГГ,ЧЧ:ММ (например, 1 января 2017 года 15:00 это 1.1.2017,15:00). Созданное задание отобразится в разделе планирования писем.
`archive_delivery_id`	ID рассылки, в архив которой будет положено письмо после отправки, если это необходимо
`file_id`	ID файла, который необходимо прикрепить. Через запятую можно указать несколько ID.

Ответ

xml

<response>
 <result></result>
 <job_id></job_id>
</response>

Поля ответа

Поле	Описание
`job_id`	ID созданного задания на отправку

Группы подписчиков

Группы подписчиков со счётчиками по состоянию адресов.

URL интерфейсаhttp://api.falconsender.ru/groups.html

Список групп

action=list

Параметр Описание

actionобязательный list — получение списка групп

Параметр	Описание
`action`обязательный	`list` — получение списка групп
`id`	Если есть необходимость получить не весь список групп, а только некоторые из них, можно указать их id через запятую. В противном случае в ответе будет содержаться весь список. По умолчанию список сортируется по дате создания
`sortorder`	Сортировка групп: `date_created` — по дате создания `title` — по названию группы.

id

Если есть необходимость получить не весь список групп, а только некоторые из них, можно указать их id через запятую. В противном случае в ответе будет содержаться весь список.

По умолчанию список сортируется по дате создания

sortorder

Сортировка групп:

date_created — по дате создания
title — по названию группы.

Ответ

xml

<response>
 <result></result>
 <list count="">
  <element>
   <id></id>
   <date_created></date_created>
   <date_updated></date_updated>
   <title></title>
   <cnt_subscribers></cnt_subscribers>
   <cnt_subscribers_active></cnt_subscribers_active>
   <cnt_subscribers_activation></cnt_subscribers_activation>
   <cnt_subscribers_disabled></cnt_subscribers_disabled>
  </element>
  <element>
  ...
  </element>
 </list>
</response>

Поля ответа

Поле	Описание
`list`	`count` — количество групп
`id`	ID группы
`date_created`	Дата создания в формате ДД/ММ/ГГГГ ЧЧ:ММ:СС (+02GMT)
`date_updated`	Дата обновления в формате ДД/ММ/ГГГГ ЧЧ:ММ:СС (+02GMT)
`title`	Название
`cnt_subscribers`	Количество подписчиков
`cnt_subscribers_active`	Количество активированных подписчиков
`cnt_subscribers_activation`	Количество неактивированных подписчиков
`cnt_subscribers_disabled`	Количество несуществующих подписчиков

Статистика

Статистика отправленных писем: открытия, переходы и нажатия на «Спам».

URL интерфейсаhttp://api.falconsender.ru/stats.html

Статистика рассылок

action=list

Параметр	Описание
`action`обязательный	`list` — получение списка статистики по рассылкам
`id`	Если есть необходимость получить статистику не всего списка рассылок, а только некоторых из них, можно указать их id через запятую. В противном случае в ответе будет содержаться весь список. По умолчанию список сортируется по дате создания
`records_on_page`	Количество записей на странице (от 1 до 1000)
`page`	Номер страницы выборки, начиная с 0
`sortorder`	Сортировка списка: tstamp по дате рассылки subscribers_count по количеству подписчиков cnt_sent по количеству отправленных писем cnt_confirmed по количеству открытых писем cnt_clicked по количеству переходов по ссылкам cnt_fbl_clicked по количеству нажатий на спам

Ответ

xml

<response>
<result>1</result>
<list count="">
 <element>
  <id></id>
  <subject></subject>
  <status></status>
  <sent_date></sent_date>
  <subscribers_count></subscribers_count>
  <sent_count></sent_count>
  <open_count></open_count>
  <click_count></click_count>
  <click_spam></click_spam>
  <target></target>
 </element>
</list>
</response>

Поля ответа

Поле	Описание
`list`	`count` — количество записей
`list/element`	Статистика конкретной рассылки
`id`	ID задания
`subject`	Тема письма
`status`	`Done` — исполнено `Busy` — в очереди `Free` — создано
`sent_date`	Дата отправки в формате ДД/ММ/ГГГГ ЧЧ:ММ:СС (+02GMT)
`subscribers_count`	Количество подписчиков
`sent_count`	Количество отправленных писем
`open_count`	Количество открытых писем
`click_count`	Количество кликов по ссылкам
`click_spam`	Количество нажатий на спам
`target`	Адресаты письма

Открытия письма

action=list_openings

Параметр	Описание
`action`обязательный	`list_openings` — список открытий
`job_id`обязательный	ID задания

Ответ

xml

<response>
<result>1</result>
<list count="">
 <element>
  <date></date>
  <subscriber></subscriber>
  </element>
</list>
</response>

Поля ответа

Поле	Описание
`list/element`	Открытия письма
`date`	Дата открытия в формате ДД/ММ/ГГГГ ЧЧ:ММ:СС (+02GMT)
`subscriber`	Email-адрес подписчика

Переходы по ссылкам

action=list_clicks

Параметр	Описание
`action`обязательный	`list_clicks` — список переходов
`job_id`обязательный	ID задания

Ответ

xml

<response>
<result></result>
 <list count="">
  <element>
   <subscriber></subscriber>
   <clicks count="">
    <click date="" link=""/>
   </clicks>
  </element>
 </list>
</response>

Поля ответа

Поле	Описание
`list/element`	Клики по ссылкам
`subscriber`	Email-адрес подписчика
`clicks/click`	`date` — дата клика в формате ДД/ММ/ГГГГ ЧЧ:ММ:СС (+02GMT) `link` — ссылка, по которой был совершен клик

Нажатия на спам

action=list_spam

Параметр	Описание
`action`обязательный	`list_spam` — список нажавших на спам
`job_id`обязательный	ID задания

Ответ

xml

<response>
 <result>
  <list count="">
   <subscriber></subscriber>
  </list>
</result>
</response>

Поля ответа

Поле	Описание
`list/subscriber`	Нажавшие на спам
`subscriber`	Email-адрес подписчика

Последний переход по ссылке

action=last_click

Параметр	Описание
`action`обязательный	`last_click` — последний клик по ссылке
`job_id`обязательный	ID задания на отправку

Ответ

xml

<response>
<result>1</result>
<click date="" link="" subscirber=""/>
</response>

Поля ответа

Поле	Описание
`click`	`date` — дата клика в формате ДД/ММ/ГГГГ ЧЧ:ММ:СС (+02GMT) `link` — ссылка, по которой был совершен клик `subscriber` — email-адрес подписчика

Последнее открытие письма

action=last_opening

Параметр	Описание
`action`обязательный	`last_opening` — последнее открытие письма
`job_id`обязательный	ID задания

Ответ

xml

<response>
<result>1</result>
<opening date="30.09.2015 00:00" subscirber="info@falconsender.ru"/>
</response>

Поля ответа

Поле	Описание
`opening`	`date` — дата открытия в формате ДД/ММ/ГГГГ ЧЧ:ММ:СС (+02GMT) `subscriber` — email-адрес подписчика

Обратные вызовы (callbacks)

Специализированный набор функций API, с помощью которого вы можете удалённо отслеживать изменения в вашем аккаунте на Falconsender в режиме реального времени.

Подключение

Введите URL уже готового скрипта в разделе API в настройках авторского аккаунта. Скрипт должен обрабатывать запросы от нашего сервера.
После сохранения к скрипту придёт GET-запрос с переменной action=test. Чтобы скрипт был принят, он должен вернуть строку TEST:OK — именно в верхнем регистре.
Дальше после каждого вызова скрипт должен возвращать строку из ID запроса, кода действия и слова ok, разделённых двоеточием. В любом другом случае запрос считается неудачным, и в течение 24 часов каждые 5 минут вызов будет повторяться.

Falconsender вызывает скрипт

url

http://yoursite/falcon_callback.html?request_id=12345&action=subscriber_added...

Скрипт должен вернуть

ответ

12345:subscriber_added:ok

Для передачи всех данных используется кодировка UTF-8. Данные поступают POST-запросом.

Переменные в каждом запросе

Переменная	Описание
`request_id`	Уникальный ID запроса. Желательно сохранять его на своей стороне и всегда проверять, чтобы не дублировать события.
`date_tstamp`	Дата события в формате UNIX-времени. Часовой пояс (GMT) Москвы.
`date`	Дата события в формате " ДД/ММ/ГГГГ ЧЧ:ММ:CC ". Часовой пояс (GMT) Москвы.
`subscriber_id`	ID подписчика
`email`	Электронный адрес подписчика
`action`	Код события. Могут передаваться дополнительные переменные. Значения переменной action указаны ниже.

Коды событий

Значение переменной action. С некоторыми событиями передаются дополнительные переменные.

action	Событие
`subscriber_added`	Добавлен новый подписчик `name_last`, `name_first`, `name_mid` — Фамилия, имя и отчество подписчика `birth_day`, `birth_month`, `birth_year` — Дата рождения подписчика `city` — Город подписчика `company` — Компания подписчика
`subscriber_subscribed`	Подписка на рассылку `delivery_id` — ID рассылки, на которую подписчик подписался
`subscriber_unsubscribed`	Подписчик отписался `delivery_id` — ID рассылки, от которой произошла отписка
`subscriber_activated`	Подписчик активирован без дополнительных переменных
`subscriber_deleted`	Подписчик удалил себя из списка автора без дополнительных переменных

Частые вопросы об API

Доступ и формат

На каких тарифах доступен API?

Только на платных — Basic и Pro. На бесплатном тарифе API не работает.

Где взять API-ключ?

В настройках аккаунта автора, в разделе API. Ключ состоит из 32 символов, и для доступа ко всем интерфейсам нужен только он.

В каком формате приходит ответ?

По умолчанию в XML. Чтобы получить JSON, передайте в запросе параметр format. Все данные передаются в кодировке UTF-8.

Как узнавать о новых подписчиках сразу?

Через обратные вызовы: укажите в настройках API адрес своего скрипта, и сервис будет присылать ему POST-запрос при каждом событии — подписке, отписке, активации и удалении подписчика.

Что подключают через API

Формы подписки Автоматические серии База и сегментация Статистика рассылок

Подключите API на платном тарифе

API работает на тарифах Basic и Pro. Ключ — в настройках аккаунта, раздел API.

Выбрать тариф Войти в кабинет