Есть ли библиотеки?
Язык: Ruby | creadone/dashamail | Автор: | Репозиторий на GitHub:
Если у вас есть библиотека для работы с ДашаМейл.ру или вы очень хотите, чтобы оно появилось - не стесняйтесь и пишите сразу же на support@dashamail.ru. Мы всегда рады талантливым разработчикам!
Может быть удобнее в Postman?
Вы можете протестировать весь текущий функционал, описанный в документации, в платформе Postman. Мы создали коллекции для быстрого и удобного тестирования методов отправки и получения отчетов. Dashamail Postman Коллекции
Введение
Методы транзакционного API доступны всем клиентам сервиса, которые настроили собственный домен отправки (DKIM&SPF) в разделе "Аккаунт"=>"Мои домены".
На бесплатном тарифном плане API по умолчанию отключен. Для работы попросите нашу техподдержку открыть его для вашего аккаунта.
Как обращаться к API?
Работа с API осуществляется при помощи отправки HTTP-запросов (методы GET, POST) по адресу:
api.dashamail.ru
Возможно использование протоколов HTTP либо HTTPS. Кодировка: UTF-8.
Авторизация производится помощью параметра api_key. Для отправки писем используется метод transactional.send Пример запроса:
http://api.dashamail.com/?method=transactional.send&api_key=88854bb15344453a0193df0a4acbe793 &format=xml&to=test@mymail.ru&message=<p>test message=</p>&from_email=testsender@example.ru&subject=TestSubject
Обязательные параметры запроса
- api_key – ключ для авторизации (можно найти в разделе «Интеграции» => «Транзакционные письма»)
- method – вызываемый метод апи. В данном случае это transactional.send
- to – email-адрес получателя. В случае задания нескольких получателей разделяются через запятую. Возможен формат с именем, например, Даша Савицкая <dasha@dashamail.ru>
- from_email – email-адрес отправителя. Важно! Обратный адрес, используемый в поле From («От кого»), должен быть подтвержден в разделе «Доставляемость» => «Подтвержденные отправители».
- subject – заголовок «Тема письма». В случае, если в message передается ID рассылки, то параметр необязателен и подставляется из темы письма указанной рассылки. В параметре также допустим теги динамического контента.
Необязательные параметры запроса
- message html-код сообщения или id рассылки или шаблона, откуда его взять
- plain_text plain_text версия вашего письма. Если параметр не задан или пуст, будет сгенерирована автоматически из html.
- multi_to если задан данный параметр, то при задании нескольких адресов в поле «Кому» (to) через запятую они будут отображаться в соответствующем заголовке письма. По-умолчанию – не отображаются.
- from_name имя отправителя для заголовка «От кого»
- cc email-адреса в поле «Копия». В случае задания нескольких получателей разделяются через запятую. Возможен формат с именем, например, Владимир Владимирович <putin@kremlin.ru>.
- bcc email-адреса в поле «Скрытая копия». В случае задания нескольких получателей разделяются через запятую. Возможен формат с именем, например, Феликс Эдмундович <dzerzinksy@kgb.su>.
- message_id id сообщения, по которому вы потом сможете идентифицировать вебхук. В случае задания нескольких получателей разделяются через запятую.
- delivery_time timestamp времени, когда письмо должно быть доставлено.
- replace сериализованный массив замен в шаблоне. Также может быть в формате JSON. В случае использования нескольких email-адресов в параметре to можно использовать ассоциативный массив с замен с email-адресами в качестве ключей.
- domain домен отправки, который будет использоваться для DKIM/SPF подписей. По-умолчанию используется первый в списке в разделе «Аккаунт» => «Доставляемость» => «Настройка домена отправки (DKIM&SPF)»
- stat_domain домен отслеживания статистики, который будет использоваться для подмены ссылок и пикселя отслеживания открытий. По-умолчанию используется первый в списке в разделе «Аккаунт» => «Доставляемость» => «Настройка домена статистики»
- campaign_id пользовательский id кампании для группировки статистики по транзакционным письмам
- no_track_opens передается для отключения трекинга открытий.
- no_track_clicks передается для отключения трекинга (подмены) ссылок.
- headers JSON-объект, содержащий произвольные заголовки письма. Например, {"Reply-To":"Test Reply <testreply@example.ru>", "CustomHeader": "any value"}
- template_data - JSON-объект, содержащий данные для условных операторов {{}}. Например, {"name":"Иван", "phone": "79999999999"}. Подробнее о динамическом контенте и условных операторах.
- attachments – JSON-массив, содержащий прикладываемые файлы в base64-кодировке. Наример, [{"name": "image1.png", "filebody": "base64encoded_content_1"},{"name": "image2.png", "filebody": "base64encoded_content_2"}].
- inline – JSON-массив, содержащий прикладываемые к письму изображения. Изображения размещаются внутри письма с помощью Content-ID идентификаторов, например, src="cid:<Content-ID>>". Объекты изображений в JSON-массиве передаются со следующими параметрами:
- mime_type – MIME тип изображения, поддерживаются: image/jpeg, image/png и image/gif.
- filename – файловое имя изображения, например, victory.png
- body – base64-encoded содержимое файла картинки
- cid – идентификатор Content-ID который добавлен в тело письма для подстановки
- ignore_delivery_policy передается для игнорирования единой политики коммуникаций на аккаунте.
Параметры запроса могут передаваться как в виде get- или post-параметров, так и в формате JSON в теле POST-запроса.
Возвращаемые данные
Ответ может быть в одном из нескольких форматов. Для его задания используйте переменную format:
- JSON (default)
- JSONP
- XML
Даша возвращает данные структурированные следующим образом:
- <msg> сообщение о выполнении действия (в случае успеха принимает значение ОК) <err_code> - числовой код ошибки (0 - нет ошибок), <text> - текстовое сообщение, <type> - тип сообщения (message – нет ошибок, notice и error – ошибки)
- <data> transaction_id - уникальный id сообщения, по которому потом можно проверить статус (см. ниже).
Замена значений в теле шаблона
Допустима произвольная замена значений в шаблоне с помощью массива, передаваемого в параметре replace.
- Ключи массива – искомые значения (needle) для замены.
- Значения массива являются значениями замены.
Например, передав массив replace = array('%ИМЯ%'=>'Даша') мы произведем замену всех вхождение строки %ИМЯ% на строку Даша.
Прикладывание файлов
К каждому письму вы можете приложить сколько угодно файлов суммарным объемом до 5 Мб. Допускаются любые файлы, кроме *.exe и *.php. Необходимо избегать любых спецсимволов и знаков препинания (в том числе знаков процента) в именах файлов. Файлы отправляются стандартным образом в теле POST запроса при обращении к API.
Важно! Именем параметра при этом должен быть массив attachments. Например, при отправке запроса с помощью CURL, это будет выглядеть следующим образом:
$post['attachments[1]'] = '@index1.log';
Даже если прикладываемый файл всего один, он должен передаваться в $post['attachments[0]'], а не в $post['attachments'].
Получение отчетов
Отчеты о различных событиях, которые происходят с отправляемыми письмами, реализованы в виде вебхуков (webhooks). В разделе "Интеграции"=>"Транзакционные письма" вы можете задать адреса скриптов, которые будут вызываться при наступлении определенных событий (возврат, жалоба на спам или невозможность доставки).
При наступлении соответствующего события на указанный адрес будет передан POST-запрос с информацией о событии.
- Доставка (Delivered): $_POST['event'] значение 'delivered'.
- Возврат (Bounce): $_POST['event'] значение 'bounced'.
- Жалоба на спам (Spam Complaints): $_POST['event'] значение 'complained'.
- Открытие (Opens): $_POST['event'] значение 'opened'.
- Клик (Clicks): $_POST['event'] значение 'clicked'.
- Отписка (Unsubscribe): $_POST['event'] значение 'unsubscribed' (только если в письме присутствует ссылка отписки с id или class="unsub_link".
Дополнительно могут передаваться:
- $_POST['email'] - адрес получателя
- $_POST['code'] - код ошибки
- $_POST['description'], $_POST['error'], $_POST['reason'] - описание и причины ошибки
- $_POST['event_time'] - время события
- $_POST['custom_vars'] - JSON-массив пользовательских переменных из заголовка X-Dashamail-Variables
- $_POST['secret'] - ключ для проверки валидности вебхука, формируется как md5($_POST['email'].$_POST['message_id'].$webhook_key), где $webhook_key – ключ, который можно найти в разделе "Интеграции"=>"Транзакционные письма".
Например, если возврат произошел после многократных попыток доставить, $_POST['reason'] имеет значение 'old', а если есть четкая причина возврата, то 'hardfail'. При этом сам текст ошибки будет содержаться в $_POST['description']. Обычно, коды ошибок, начинающиеся с 5, относятся к "жестким" возвратам (несуществующий или заблокированный ящик и т.п.), а начинающиеся с 4 - к "мягким" (временная невозможность доставки). В случае нажатия кнопки "это спам" чаще всего возвращается код 9.9.9.
Проверка статуса письма
Проверить статус отправленного письма можно методом transactional.check, который принимает в качестве параметра transaction_id, полученный при отправке письма. В выводе в параметре data отображается последний активный статус, а в параметр log выводится история всех статусов письма.
Например, http://api.dashamail.com/?method=transactional.check&api_key=my_key&transaction_id=my_email_id
Получение лога событий
Получить лог событий по транзакционным письмам (отправки, открытия, клики и так далее) можно методом transactional.get_log, который принимает в качестве параметров следующие значения (все параметры опциональные):
- event_type - тип события (all, sent, opened, clicked, bounced, unsubscribed, complained). Возможно задать несколько событий через запятую.
- emails - список email получателей, разделенных запятой
- campaign_id - фильтр по дополнительному параметру campaign_id
- sort - desc или asc (по event_time)
- start и limit - с какой позиции начинать и сколько выводить
- from - с какого event_time выводить (формат yyyy-mm-dd hh:mm:ss)
- to - до какого event_time выводить (формат yyyy-mm-dd hh:mm:ss)
По умолчанию выводит 500 последних событий (любых типов) за последние 30 дней в обратной сортировке.
Получение статистики по событиям за период
Получить временной ряд со сводными значениями числа событий за определенный период можно с помощью метода transactional.get_stat, который примет в качестве параметров следующие значения:
- period - период выборки, возможные значения ['1h','24h','7d','30d','custom']. По-умолчанию: 1h
- campaign_id - фильтр по дополнительному параметру campaign_id
Что получается в результате?
Массив числа событий SENT, OPENED, CLICKED, UNSUBSCRIBED, COMPLAINED, BOUNCED и суммарный объем траффика (в байтах) по временным слотам. В случае использования готовых периодов временные слоты группируемых событий такие:
- 1h – 5 минут
- 24h - 1 час
- 7d - 1 день
- 30d – 1 день
Если используется период со значением custom, то обязательны следующие дополнительные параметры:
- groupby - размер временного слота, возможные значения: ['hour','day','week','month']
- start_date - с какого event_time выводить (произвольный машиночитаемый формат, например, yyyy-mm-dd hh:mm:ss). Если не время не задано, то считается 00:00:00
- finish_date - до какого event_time выводить (произвольный машиночитаемый формат, например, yyyy-mm-dd hh:mm:ss). Если не время не задано, то считается 00:00:00
Проблемы? Вопросы?
Если вы столкнулись с проблемами или вам кажется что метод не работает? Пишите на support@dashamail.ru и вам быстро и квалифицированно ответят наши разработчики.
