API для email-розсилок

Selzy API — це спеціальний інтерфейс для розробників, який дозволяє інтегрувати можливості електронної розсилки практично з будь-яким відкритим веб-сервісом або десктоп-додатком.

Наш API для масових email-розсилок дозволяє управляти списками контактів, створювати та надсилати різні типи повідомлень, дивитися статистику, а також надає можливості для роботи партнерів.

Користуватися API можна безкоштовно на будь-якому обліковому записі. Щоб отримати доступ до API для email-розсилок, потрібен ключ, який можна скопіювати в особистому кабінеті.

 

Ключ доступу не варто передавати стороннім особам або робити видимим у коді веб-сторінок. Інакше хтось інший зможе надсилати розсилки від Вашого імені.

У чому користь Selzy API

Інтеграція Selzy у сервіс, яким Ви постійно користуєтеся, значно спрощує вирішення завдань із email-маркетингу для Вашої компанії. Вам не доведеться постійно вручну синхронізувати списки контактів, усе відбуватиметься автоматично:

• Усі нові покупці з інтернет-магазину одразу будуть додані до цього списку розсилки.
• Статуси контактів будуть синхронізовані з Вашою CRM.
• Статистика розсилок буде передаватися в системи аналізу та data mining.

Швидкий старт

Ми підготували бібліотеку для класу PHP, щоби Ви могли швидко додати можливість надсилання повідомлень у Ваш веб-проєкт.

Також для налаштування API використовуйте базову інструкцію зі створення інтеграції.

Принцип використання API

Виклик методу

Звернення до методів API для email-розсилок — це HTTPS-запит до URL виду:

https://api.selzy.com/LANG/api/METHOD?format=json&api_key=KEY&arg1=ARG_1&argN=ARG_N

де:

LANG *	мова повідомлень сервера API (наразі підтримується en, ua, ru)
METHOD *	назва методу
KEY *	ключ доступу до API
ARG_1 ... ARG_N	аргументи методу (свої для кожного методу)

Усі параметри повинні бути в кодуванні UTF-8. У наведеному прикладі параметри зазначено в GET-запиті, але можна передавати їх і в POST. Більше того, параметр api_key ми наполегливо радимо передавати через POST, щоби він не зберігався в логах проксі-серверів.

Відповідь приходить у вигляді об'єкта формату JSON.

Як запит, так і відповідь можуть бути стиснуті алгоритмами gzip або bzip2.

Результат успішного виклику методу

Якщо виклик успішний, то об'єкт міститиме поле "result", вміст якого залежить від викликаного методу, і не буде містити поле "error".

Також у разі успішного виклику припустима наявність поля "warnings", яке містить масив об'єктів-попереджень з єдиним рядковим полем "warning".

Приклад відповіді успішного виклику методу:

{

"result": {

"message_id":34423432

},

"warnings": [

{"warning":"probably not a mobile phone"}

]

}

Результат неуспішного виклику методу

Якщо під час виконання методу виникла помилка, в об'єкті відповіді Ви побачите поле "error" із HTML-повідомленням про помилку, а також поле "code" із рядковим кодом помилки. Поле "result" у разі помилки повинно бути проігнороване.

Приклад відповіді з помилкою:

{

"code": "invalid_arg",

"error": "fields: This value \"mymail@@@@gmail.com\" is not a valid email address.",

"result": ""

}

Основні коди помилок під час роботи з API

Список доступних методів

Робота зі списками контактів
Робота з додатковими полями та мітками
Створення та надсилання повідомлень
Робота з шаблонами
Отримання статистики
Методи для партнерських сайтів

Робота зі списками контактів:

• getLists — отримати списки для розсилок із їх кодами;
• createList — створити новий список розсилки;
• updateList — змінити властивості списку розсилки;
• deleteList — видалити список розсилки;
• subscribe — підписати адресата на один або декілька списків розсилки;
• exclude — виключити адресата зі списків розсилки;
• unsubscribe — відписати адресата від розсилки;
• importContacts — масовий імпорт і синхронізація контактів;
• exportContacts — експорт даних контактів;
• getTotalContactsCount —
• отримати інформацію про розмір бази користувача;
• getContactCount — отримати кількість контактів у списку;
• getContact — отримати інформацію про один контакт.

Робота з додатковими полями та мітками:

• getFields — отримати список призначених для користувача полів;
• createField — створити нове поле;
• updateField — змінити параметри поля;
• deleteField — видалити поле;
• getTags — отримати список користувацьких міток;
• deleteTag — видалити мітку.

Створення та надсилання повідомлень:

• createEmailMessage — створити email для розсилки;
• createSmsMessage — створити SMS для масової розсилки;
• createCampaign — запланувати масове надсилання email або SMS повідомлення;
• cancelCampaign — скасувати заплановане раніше масове надсилання;
• getActualMessageVersion — отримати актуальну версію листа;
• sendSms — відправити SMS-повідомлення;
• checkSms — перевірити статус доставки SMS;
• sendEmail — спрощене надсилання індивідуальних email-повідомлень;
• sendTestEmail — відправити тестову email-розсилку (на свою адресу);
• checkEmail — перевірити статус доставки email;
• updateOptInEmail — змінити текст листа з посиланням підтвердження підписки;
• getWebVersion — отримати посилання на веб-версію надісланого листа;
• deleteMessage — видалити повідомлення;
• updateEmailMessage — редагувати email для масової розсилки.

Робота з шаблонами:

• createEmailTemplate  — створити шаблон повідомлення для масової розсилки;
• updateEmailTemplate — редагувати наявний шаблон повідомлення;
• deleteTemplate — видалити шаблон;
• getTemplate — отримати інформацію про шаблон;
• getTemplates — отримати список усіх шаблонів, створених у системі;
• listTemplates — отримати список усіх шаблонів без body.

Отримання статистики:

• getCampaignDeliveryStats — отримати звіт про статуси доставки повідомлень для заданої розсилки;
• getCampaignCommonStats — отримати загальні відомості про результати доставки для зазначеної розсилки;
• getVisitedLinks — отримати статистику переходів за посиланнями;
• getCampaigns — отримати список розсилок;
• getCampaignStatus — отримати статус розсилки;
• getMessages — отримати список повідомлень;
• getMessage — отримати інформацію про SMS або email-повідомлення;
• listMessages — отримати список повідомлень без тіла та вкладень.

Методи для партнерських сайтів:

• getCheckedEmail — отримати список email-адрес (підтверджених/непідтверджених);
• validateSender — підтвердити зворотну адресу;
• register — зареєструвати користувача (для партнерських сайтів);
• checkUserExists — перевірити існування користувача за логіном або email;
• getUserInfo — отримати інформацію про користувача (для партнерських сайтів);
• getUsers — отримати інформацію про користувачів (для партнерських сайтів);
• transferMoney — перевести гроші на рахунок користувача (для партнерських сайтів);
• setSenderDomain — отримати DKIM-ключ для домену відправника.

Порядок виклику методів

У Вас може бути один або декілька списків контактів. Передбачається, що кожен список email-адрес відповідає певній тематиці розсилки, а адресат може бути підписаний на один або кілька списків одночасно.

Перш ніж розсилати email або SMS за списком, потрібно дізнатися код списку за допомогою методу getLists або створити новий список email адрес за допомогою методу createList.

Далі потрібно додати контакти до списку, чи масово за допомогою методу importContacts, або по одному за допомогою методу subscribe.

Тепер можна надсилати повідомлення. Розсилка створюється за допомогою методу createEmailMessage (або createSmsMessage). Обов'язково зазначте id списку з адресатами. Тоді лист буде призначено для всіх підписників із цього списку, активних на момент виклику createEmailMessage або createSmsMessage.

Отже, розсилку створено, але поки не надіслано. Для надсилання повідомлення використовуйте метод createCampaign. Зазначте message_id, який Ви отримали після надсилання методу createEmailMessage (або createSmsMessage), і надішліть розсилку відразу чи заплануйте на потрібний час.

Якщо потрібно надіслати інший лист за тим самим списком, то знову викликайте createEmailMessage/crеateSmsMessage і далі дійте як описано вище.

Якщо текст листа змінювати не треба, а потрібно надіслати той самий лист із того самого списку ще раз, можете знову викликати createCampaign з таким самим message_id. Розсилку буде надіслано повторно.

Після розсилки можна отримати результати надсилання методом getCampaignDeliveryStats.

Система повідомлень про події (Webhooks)

Webhook — механізм оповіщення користувачів системи про події, який використовують для відстеження зміни статусів листів у реальному часі.

Події, про які може повідомляти Webhook:

• зміна статусу листа (надіслано, доставлено, відхилено, прочитано, одержувач перейшов за посиланням);
• контакт відписався від списку/підписався на інший список;
• зміна статусу розсилки;
• зміна даних користувача;
• додавання підтвердженої зворотної адреси;
• зміна стану рахунку;
• додавання нового користувача (для реселерів).

Вебхуками можна управляти в особистому кабінеті в «Налаштуваннях» на вкладці «Webhook».