Документация для разработчиков

Транзакционное API

методы для отправки отдельных писем и обработка ответов

Введение

Методы транзакционного API доступны всем клиентам сервиса на платных тарифных планах, которые настроили собственный домен отправки (DKIM&SPF) в разделе "Аккаунт"=>"Мои домены".


Во время действия триального тарифа возможно подключение данного API по запросу. Если вам необходим доступ - не стесняйтесь и пишите сразу же на support@dashamail.ru.

Как обращаться к API?

Работа с API осуществляется при помощи отправки HTTP-запросов (методы GET, POST) по адресу:

api.dashamail.com

Возможно использование протоколов HTTP либо HTTPS. Кодировка: UTF-8.

Авторизация производится либо с помощью параметра api_key, либо через параметры username и password. Для отправки писем используется метод transactional.send Пример запроса:

http://api.dashamail.com/?method=transactional.send&api_key=88854bb15344453a0193df0a4acbe793 &format=xml&to=test@mymail.ru&message=<p>test message=</p>&headers= a:2:{s:4:"From";s:22:""test" =<admin@mailerloop.ru>";s:7:"Subject";s:4:"test";}

Обязательные параметры запроса

  • api_key (username/password) ключ для авторизации (пара логин/пароль от сервиса)
  • method вызываемый метод апи. В данном случае это transactional.send
  • to email-адрес получателя
  • message html-код сообщения
  • headers сериализованный массив заголовков

Параметр api_key можно получить в разделе "Интеграции"=>"Транзакционные письма" в вашем Личном Кабинете.

Возвращаемые данные

Ответ может быть в одном из нескольких форматов. Для его задания используйте переменную format:

  • JSON (default)
  • JSONP
  • XML

Даша возвращает данные структурированные следующим образом:

  • <msg> сообщение о выполнении действия (в случае успеха принимает значение ОК) <err_code> - числовой код ошибки (0 - нет ошибок), <text> - текстовое сообщение, <type> - тип сообщения (message – нет ошибок, notice и error – ошибки)
  • <data> запрашиваемые данные в виде массива, если есть.

Прикладывание файлов

К каждому письму вы можете приложить сколько угодно файлов суммарным объемом до 5 Мб. Допускаются любые файлы, кроме *.exe и *.php. Необходимо избегать любых спецсимволов и знаков препинания (в том числе знаков процента) в именах файлов. Файлы отправляются стандартным образом в теле POST запроса при обращении к API.

Важно! Именем параметра при этом должен быть массив attachments. Например, при отправке запроса с помощью CURL, это будет выглядеть следующим образом:

$post['attachments[0]'] = '@index.log';
$post['attachments[1]'] = '@index1.log';

Даже если прикладываемый файл всего один, он должен передаваться в $post['attachments[0]'], а не в $post['attachments'].

Получение отчетов

Отчеты о различных событиях, которые происходят с отправляемыми письмами, реализованы в виде вебхуков (webhooks). В разделе "Интеграции"=>"Транзакционные письма" вы можете задать адреса скриптов, которые будут вызываться при наступлении определенных событий (возврат, жалоба на спам или невозможность доставки).

При наступлении соответствующего события на указанный адрес будет передан POST-запрос с информацией о событии.

  • Возврат (Bounce): $_POST['event'] значение 'bounced'.
  • Недоставка (Dropped messages): $_POST['event'] значение 'dropped'.
  • Жалоба на спам (Spam Complaints): $_POST['event'] значение 'complained'.

Дополнительно могут передаваться:

  • $_POST['email'] - адрес получателя
  • $_POST['code'] - код ошибки
  • $_POST['description'], $_POST['error'], $_POST['reason'] - описание и причины ошибки

Например, если возврат произошел после многократных попыток доставить, $_POST['reason'] имеет значение 'old', а если есть четкая причина возврата, то 'hardfail'. При этом сам текст ошибки будет содержаться в $_POST['description']. Обычно, коды ошибок, начинающиеся с 5, относятся к "жестким" возвратам (несуществующий или заблокированный ящик и т.п.), а начинающиеся с 4 - к "мягким" (временная невозможность доставки). В случае нажатия кнопки "это спам" чаще всего возвращается код 9.9.9.

Проблемы? Вопросы?

Если вы столкнулись с проблемами или вам кажется что метод не работает? Пишите на support@dashamail.ru и вам быстро и квалифицированно ответят наши разработчики.