Транзакционное API
Отправка отдельных писем по событию: подтверждение заказа, сброс пароля, чек. Одно письмо — один запрос, с вложениями, подстановками и отслеживанием доставки.
Введение #
Методы доступны клиентам, которые настроили собственный домен отправки — прописали DKIM и SPF в разделе Аккаунт → Мои домены.
На бесплатном тарифном плане API отключён по умолчанию. Напишите в техподдержку, и его откроют для вашего аккаунта.
Если вашей системе нужно просто «отправить письмо» и она уже умеет это по SMTP — посмотрите SMTP-подключение: интеграция выйдет короче. Замены в шаблоне, вложения из библиотеки и работа с базами есть только здесь.
Как обращаться к API #
Запросы идут на api.dashamail.com методами GET и POST, кодировка — UTF-8. Авторизация одним параметром api_key: он лежит в разделе Интеграции → Транзакционные письма.
https://api.dashamail.com/?method=transactional.send&api_key=YOUR_API_KEY&to=ivan@example.com&...
Параметры передаются тремя способами на выбор: строкой запроса, полями POST или JSON в теле POST-запроса. Для писем с вложениями и заменами последний удобнее — в примерах ниже используется он.
Перебрать методы, ничего не программируя, можно в коллекциях Postman — там собраны и отправка, и отчёты.
Формат ответа #
Формат задаётся параметром format: JSON (по умолчанию), JSONP или XML. Структура всегда одна:
msg— как прошёл вызов:err_code(0 — без ошибок),textс сообщением иtypeсо значениемmessage,noticeилиerror.data— сами данные. У отправки этоtransaction_id.
Методы #
- POST Отправить письмо
- GET Проверить статус письма
- GET Лог событий
- GET Статистика за период
Отправить письмо #
POST
?method=transactional.send
Отправляет одно письмо. В message можно передать готовый HTML, а можно идентификатор рассылки или шаблона — тогда тело возьмётся оттуда.
Параметры принимаются и строкой запроса, и полями POST, и JSON в теле POST-запроса. Ниже — последнее: с вложениями и заменами так удобнее.
Адрес в from_email должен быть подтверждён в разделе Доставляемость → Подтверждённые отправители, иначе письмо не уйдёт.
Параметры
| Параметр | Тип | Описание |
|---|---|---|
to обязательный | string | Адрес получателя. Несколько — через запятую. Допустим формат с именем: Дарья Савицкая <dasha@dashamail.ru>. |
from_email обязательный | string | Адрес отправителя. Должен быть подтверждён в личном кабинете. |
subject обязательный | string | Тема письма. Необязательна, если в message передан идентификатор рассылки — тогда берётся её тема. Допускает теги динамического контента. |
message | string | HTML-код письма — либо идентификатор рассылки или шаблона, откуда его взять. |
plain_text | string | Текстовая версия. Если не передать, соберётся из HTML автоматически. |
from_name | string | Имя отправителя для заголовка «От кого». |
cc | string | Копия. Несколько адресов — через запятую, формат с именем допустим. |
bcc | string | Скрытая копия. Правила те же, что у cc. |
multi_to | integer | Показывать всех получателей из to в заголовке письма. По умолчанию они друг друга не видят. |
message_id | string | Ваш идентификатор письма — придёт обратно в вебхуке. При нескольких получателях перечисляются через запятую. |
delivery_time | timestamp | Когда доставить письмо. Без параметра уходит сразу. |
replace | JSON-строка | Замены в теле письма: ключ — что искать, значение — на что менять. При нескольких адресах в to можно передать объект, где ключи — адреса, а значения — свои наборы замен. |
template_data | JSON-строка | Данные для условных операторов {{ }}. Например, {"name":"Иван"}. См. динамический контент. |
attachments | JSON-массив | Вложения в base64: [{"name":"doc.pdf","filebody":"…"}]. Подробности — в разделе «Вложения». |
inline | JSON-массив | Картинки внутри письма, подставляемые через src="cid:…". У каждой — mime_type, filename, body (base64) и cid. |
domain | string | Домен для подписей DKIM и SPF. По умолчанию — первый в списке подтверждённых доменов отправки. |
stat_domain | string | Домен статистики — для подмены ссылок и пикселя открытий. По умолчанию первый в списке. |
campaign_id | string | Ваша метка для группировки статистики по транзакционным письмам. |
headers | JSON-строка | Произвольные заголовки письма: {"Reply-To":"reply@example.com"}. |
no_track_opens | integer | Не отслеживать открытия. |
no_track_clicks | integer | Не подменять ссылки на трекинговые. |
headers_unsub | integer | Не влияет на письмо. Заголовки List-Unsubscribe и List-Unsubscribe-Post со ссылкой отписки в один клик добавляются в каждое письмо, значение 0 их не отключает. Свой List-Unsubscribe, переданный в headers, заменяет наш. |
ignore_delivery_policy | integer | Игнорировать «Единую политику коммуникаций» аккаунта. |
ip | string | С какого выделенного IP отправлять. Работает, если адрес подключён на аккаунте. |
detailed_answer | integer | Со значением 1 ответ приходит в виде "email" => "message_id (transaction_id)". |
Что возвращается
transaction_id — по нему потом проверяется статус письма методом transactional.check.
curl -X POST 'https://api.dashamail.com/' \
-H 'Content-Type: application/json' \
-d '{
"method": "transactional.send",
"api_key": "YOUR_API_KEY",
"to": "ivan@example.com",
"from_email": "noreply@example.com",
"from_name": "Магазин",
"subject": "Заказ 128341 собран",
"message": "<p>Здравствуйте, %ИМЯ%! Ваш заказ ждёт в пункте выдачи.</p>",
"replace": "{\"%ИМЯ%\":\"Иван\"}"
}'
<?php
$ch = curl_init('https://api.dashamail.com/');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode([
'method' => 'transactional.send',
'api_key' => 'YOUR_API_KEY',
'to' => 'ivan@example.com',
'from_email' => 'noreply@example.com',
'from_name' => 'Магазин',
'subject' => 'Заказ 128341 собран',
'message' => '<p>Здравствуйте, %ИМЯ%! Ваш заказ ждёт в пункте выдачи.</p>',
'replace' => '{"%ИМЯ%":"Иван"}',
], JSON_UNESCAPED_UNICODE),
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);
if ($response['response']['msg']['err_code'] !== 0) {
throw new RuntimeException($response['response']['msg']['text']);
}
print_r($response['response']['data']);
import requests
response = requests.post(
'https://api.dashamail.com/',
json={
'method': 'transactional.send',
'api_key': 'YOUR_API_KEY',
'to': 'ivan@example.com',
'from_email': 'noreply@example.com',
'from_name': 'Магазин',
'subject': 'Заказ 128341 собран',
'message': '<p>Здравствуйте, %ИМЯ%! Ваш заказ ждёт в пункте выдачи.</p>',
'replace': '{"%ИМЯ%":"Иван"}',
},
)
payload = response.json()['response']
if payload['msg']['err_code'] != 0:
raise RuntimeError(payload['msg']['text'])
print(payload['data'])
const response = await fetch('https://api.dashamail.com/', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
"method": "transactional.send",
"api_key": "YOUR_API_KEY",
"to": "ivan@example.com",
"from_email": "noreply@example.com",
"from_name": "Магазин",
"subject": "Заказ 128341 собран",
"message": "<p>Здравствуйте, %ИМЯ%! Ваш заказ ждёт в пункте выдачи.</p>",
"replace": "{\"%ИМЯ%\":\"Иван\"}"
}),
});
const { response: payload } = await response.json();
if (payload.msg.err_code !== 0) throw new Error(payload.msg.text);
console.log(payload.data);
{
"response": {
"msg": {
"err_code": 0,
"text": "OK",
"type": "message"
},
"data": {
"transaction_id": "5f2c1a9e4b3d8c7a"
}
}
}
Проверить статус письма #
GET
?method=transactional.check
Показывает, что случилось с отправленным письмом. В data — последний активный статус, в log — вся история статусов.
Параметры
| Параметр | Тип | Описание |
|---|---|---|
transaction_id обязательный | string | Идентификатор, полученный при отправке. |
curl 'https://api.dashamail.com/?method=transactional.check&api_key=YOUR_API_KEY&transaction_id=5f2c1a9e4b3d8c7a'
<?php
$url = 'https://api.dashamail.com/?' . http_build_query([
'method' => 'transactional.check',
'api_key' => 'YOUR_API_KEY',
'transaction_id' => '5f2c1a9e4b3d8c7a',
]);
$response = json_decode(file_get_contents($url), true);
if ($response['response']['msg']['err_code'] !== 0) {
throw new RuntimeException($response['response']['msg']['text']);
}
print_r($response['response']['data']);
import requests
response = requests.get(
'https://api.dashamail.com/',
params={
'method': 'transactional.check',
'api_key': 'YOUR_API_KEY',
'transaction_id': '5f2c1a9e4b3d8c7a',
},
)
payload = response.json()['response']
if payload['msg']['err_code'] != 0:
raise RuntimeError(payload['msg']['text'])
print(payload['data'])
const params = new URLSearchParams({
"method": "transactional.check",
"api_key": "YOUR_API_KEY",
"transaction_id": "5f2c1a9e4b3d8c7a"
});
const response = await fetch(`https://api.dashamail.com/?${params}`);
const { response: payload } = await response.json();
if (payload.msg.err_code !== 0) throw new Error(payload.msg.text);
console.log(payload.data);
{
"response": {
"msg": {
"err_code": 0,
"text": "OK",
"type": "message"
},
"data": {
"status": "delivered",
"email": "ivan@example.com",
"event_time": "2026-08-27 12:04:11",
"log": [
{
"status": "sent",
"event_time": "2026-08-27 12:04:02"
},
{
"status": "delivered",
"event_time": "2026-08-27 12:04:11"
}
]
}
}
}
Лог событий #
GET
?method=transactional.get_log
События по транзакционным письмам: отправки, открытия, клики, возвраты, жалобы, отписки. Все параметры необязательные.
Без параметров отдаёт 500 последних событий любых типов за последние 30 дней, новые сверху.
Параметры
| Параметр | Тип | Описание |
|---|---|---|
event_type | string | Тип события. Несколько — через запятую. Допустимые значения: all, sent, opened, clicked, bounced, unsubscribed, complained |
emails | string | Адреса получателей через запятую. |
campaign_id | string | Фильтр по вашей метке кампании. |
url | string | Оставить только клики по конкретной ссылке. |
from | datetime | С какого времени события. Формат yyyy-mm-dd hh:mm:ss. |
to | datetime | До какого времени события. |
sort | stringпо умолчанию: desc | Порядок по времени события. Допустимые значения: desc, asc |
start | integerпо умолчанию: 0 | С какой позиции выводить. |
limit | integerпо умолчанию: 500 | Сколько событий вернуть. |
curl 'https://api.dashamail.com/?method=transactional.get_log&api_key=YOUR_API_KEY&event_type=bounced%2Ccomplained&limit=2'
<?php
$url = 'https://api.dashamail.com/?' . http_build_query([
'method' => 'transactional.get_log',
'api_key' => 'YOUR_API_KEY',
'event_type' => 'bounced,complained',
'limit' => '2',
]);
$response = json_decode(file_get_contents($url), true);
if ($response['response']['msg']['err_code'] !== 0) {
throw new RuntimeException($response['response']['msg']['text']);
}
print_r($response['response']['data']);
import requests
response = requests.get(
'https://api.dashamail.com/',
params={
'method': 'transactional.get_log',
'api_key': 'YOUR_API_KEY',
'event_type': 'bounced,complained',
'limit': '2',
},
)
payload = response.json()['response']
if payload['msg']['err_code'] != 0:
raise RuntimeError(payload['msg']['text'])
print(payload['data'])
const params = new URLSearchParams({
"method": "transactional.get_log",
"api_key": "YOUR_API_KEY",
"event_type": "bounced,complained",
"limit": "2"
});
const response = await fetch(`https://api.dashamail.com/?${params}`);
const { response: payload } = await response.json();
if (payload.msg.err_code !== 0) throw new Error(payload.msg.text);
console.log(payload.data);
{
"response": {
"msg": {
"err_code": 0,
"text": "OK",
"type": "message"
},
"data": [
{
"email": "ivan@example.com",
"event": "bounced",
"event_time": "2026-08-27 09:12:44",
"code": "5.1.1",
"description": "User unknown"
},
{
"email": "petr@example.com",
"event": "complained",
"event_time": "2026-08-27 10:31:02",
"code": "9.9.9"
}
]
}
}
Статистика за период #
GET
?method=transactional.get_stat
Временной ряд: сколько было отправок, открытий, кликов, отписок, жалоб и возвратов, плюс суммарный объём трафика в байтах.
У готовых периодов размер слота фиксирован: 1h — по пять минут, 24h — по часу, 7d и 30d — по дню.
Параметры
| Параметр | Тип | Описание |
|---|---|---|
period | stringпо умолчанию: 1h | Период выборки. Допустимые значения: 1h, 24h, 7d, 30d, custom |
campaign_id | string | Фильтр по вашей метке кампании. |
groupby | string | Размер слота. Обязателен при period=custom.Допустимые значения: hour, day, week, month |
start_date | datetime | Начало периода. Обязателен при period=custom. Если время не указано, берётся 00:00:00. |
finish_date | datetime | Конец периода. Обязателен при period=custom. |
curl 'https://api.dashamail.com/?method=transactional.get_stat&api_key=YOUR_API_KEY&period=24h'
<?php
$url = 'https://api.dashamail.com/?' . http_build_query([
'method' => 'transactional.get_stat',
'api_key' => 'YOUR_API_KEY',
'period' => '24h',
]);
$response = json_decode(file_get_contents($url), true);
if ($response['response']['msg']['err_code'] !== 0) {
throw new RuntimeException($response['response']['msg']['text']);
}
print_r($response['response']['data']);
import requests
response = requests.get(
'https://api.dashamail.com/',
params={
'method': 'transactional.get_stat',
'api_key': 'YOUR_API_KEY',
'period': '24h',
},
)
payload = response.json()['response']
if payload['msg']['err_code'] != 0:
raise RuntimeError(payload['msg']['text'])
print(payload['data'])
const params = new URLSearchParams({
"method": "transactional.get_stat",
"api_key": "YOUR_API_KEY",
"period": "24h"
});
const response = await fetch(`https://api.dashamail.com/?${params}`);
const { response: payload } = await response.json();
if (payload.msg.err_code !== 0) throw new Error(payload.msg.text);
console.log(payload.data);
{
"response": {
"msg": {
"err_code": 0,
"text": "OK",
"type": "message"
},
"data": [
{
"slot": "2026-08-27 10:00:00",
"SENT": 1204,
"OPENED": 631,
"CLICKED": 118,
"BOUNCED": 9,
"COMPLAINED": 0,
"UNSUBSCRIBED": 2,
"traffic": 18442112
},
{
"slot": "2026-08-27 11:00:00",
"SENT": 987,
"OPENED": 502,
"CLICKED": 96,
"BOUNCED": 4,
"COMPLAINED": 1,
"UNSUBSCRIBED": 1,
"traffic": 15102944
}
]
}
}
Замены в шаблоне #
Параметр replace подставляет значения в готовое тело письма. Ключ — что искать, значение — на что заменить. Передав {"%ИМЯ%":"Даша"}, вы замените все вхождения %ИМЯ% на Даша.
Когда в to несколько адресов, замены можно задать каждому свои — объектом, где ключи это адреса:
{
"ivan@example.com": { "%ИМЯ%": "Иван" },
"maria@example.com": { "%ИМЯ%": "Мария" }
}
Вложения #
К письму можно приложить сколько угодно файлов общим объёмом до 5 МБ. Годится любой формат, кроме .exe и .php.
В именах файлов не должно быть спецсимволов и знаков препинания — знак процента в том числе.
Через JSON вложения передаются массивом attachments с содержимым в base64:
"attachments": [
{ "name": "invoice.pdf", "filebody": "JVBERi0xLjQKJ..." }
]
Если же вы отправляете файлы обычной формой в теле POST-запроса, имя параметра должно быть массивом:
$post['attachments[0]'] = '@invoice.pdf';
$post['attachments[1]'] = '@act.pdf';
Даже когда файл один, он передаётся как attachments[0], а не attachments. Это частая причина «вложение не дошло».
Вебхуки #
Что происходит с письмами, сервис сообщает сам: в разделе Интеграции → Транзакционные письма задаются адреса, на которые прилетит POST-запрос при наступлении события.
Типы событий
event | Событие | Когда приходит |
|---|---|---|
delivered | Доставка | Принимающий сервер принял письмо. |
opened | Открытие | Загрузился пиксель отслеживания. |
clicked | Клик | Переход по ссылке из письма. |
bounced | Возврат | Письмо доставить не удалось. |
complained | Жалоба на спам | Получатель нажал «это спам». |
unsubscribed | Отписка | Только если в письме есть ссылка отписки с id или class="unsub_link". |
Что приходит в запросе
| Поле | Тип | Описание |
|---|---|---|
event | string | Тип события из таблицы выше. |
email | string | Адрес получателя. |
event_time | datetime | Время события. |
code | string | Код ошибки, если она была. |
description | string | Текст ошибки от принимающей стороны. Рядом могут прийти error и reason. |
custom_vars | JSON | Ваши переменные из заголовка X-Dashamail-Variables. |
secret | string | Подпись для проверки подлинности — см. ниже. |
Проверка подлинности
Поле secret считается так:
md5($_POST['email'] . $_POST['message_id'] . $webhook_key)
Ключ $webhook_key лежит в разделе Email-транспорт → Транзакционное API. Сверяйте — иначе вебхук может прислать кто угодно.
Как читать причину возврата
В reason приходит hardfail, когда причина названа явно, и old, когда письмо не удалось доставить после многих попыток. Сам текст ошибки — в description.
По code ориентироваться проще: коды на 5 — жёсткие возвраты (ящика нет, ящик заблокирован), на 4 — мягкие, временная невозможность доставки. Жалоба на спам обычно приходит с кодом 9.9.9.
Библиотеки #
| Язык | Библиотека | Автор |
|---|---|---|
| Ruby | dashamail-gem | Sergey Fedorov |
| Python | anymail-dashamail | Алексей Казаев |
| Go | dashamail-go | Андрей Красильников |
Написали свою библиотеку или очень хотите, чтобы она появилась — напишите на support@dashamail.ru. Мы всегда рады талантливым разработчикам.
Вопросы #
Метод ведёт себя не так, как здесь написано — пишите на support@dashamail.ru. Приложите transaction_id: с ним разбираться заметно быстрее.