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

Транзакционное 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 ?method=transactional.send

Отправляет одно письмо. В message можно передать готовый HTML, а можно идентификатор рассылки или шаблона — тогда тело возьмётся оттуда.

Параметры принимаются и строкой запроса, и полями POST, и JSON в теле POST-запроса. Ниже — последнее: с вложениями и заменами так удобнее.

Адрес в from_email должен быть подтверждён в разделе Доставляемость → Подтверждённые отправители, иначе письмо не уйдёт.

Параметры

ПараметрТипОписание
to обязательныйstringАдрес получателя. Несколько — через запятую. Допустим формат с именем: Дарья Савицкая <dasha@dashamail.ru>.
from_email обязательныйstringАдрес отправителя. Должен быть подтверждён в личном кабинете.
subject обязательныйstringТема письма. Необязательна, если в message передан идентификатор рассылки — тогда берётся её тема. Допускает теги динамического контента.
messagestringHTML-код письма — либо идентификатор рассылки или шаблона, откуда его взять.
plain_textstringТекстовая версия. Если не передать, соберётся из HTML автоматически.
from_namestringИмя отправителя для заголовка «От кого».
ccstringКопия. Несколько адресов — через запятую, формат с именем допустим.
bccstringСкрытая копия. Правила те же, что у cc.
multi_tointegerПоказывать всех получателей из to в заголовке письма. По умолчанию они друг друга не видят.
message_idstringВаш идентификатор письма — придёт обратно в вебхуке. При нескольких получателях перечисляются через запятую.
delivery_timetimestampКогда доставить письмо. Без параметра уходит сразу.
replaceJSON-строкаЗамены в теле письма: ключ — что искать, значение — на что менять. При нескольких адресах в to можно передать объект, где ключи — адреса, а значения — свои наборы замен.
template_dataJSON-строкаДанные для условных операторов {{ }}. Например, {"name":"Иван"}. См. динамический контент.
attachmentsJSON-массивВложения в base64: [{"name":"doc.pdf","filebody":"…"}]. Подробности — в разделе «Вложения».
inlineJSON-массивКартинки внутри письма, подставляемые через src="cid:…". У каждой — mime_type, filename, body (base64) и cid.
domainstringДомен для подписей DKIM и SPF. По умолчанию — первый в списке подтверждённых доменов отправки.
stat_domainstringДомен статистики — для подмены ссылок и пикселя открытий. По умолчанию первый в списке.
campaign_idstringВаша метка для группировки статистики по транзакционным письмам.
headersJSON-строкаПроизвольные заголовки письма: {"Reply-To":"reply@example.com"}.
no_track_opensintegerНе отслеживать открытия.
no_track_clicksintegerНе подменять ссылки на трекинговые.
headers_unsubintegerНе влияет на письмо. Заголовки List-Unsubscribe и List-Unsubscribe-Post со ссылкой отписки в один клик добавляются в каждое письмо, значение 0 их не отключает. Свой List-Unsubscribe, переданный в headers, заменяет наш.
ignore_delivery_policyintegerИгнорировать «Единую политику коммуникаций» аккаунта.
ipstringС какого выделенного IP отправлять. Работает, если адрес подключён на аккаунте.
detailed_answerintegerСо значением 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);
Ответ err_code 0
{
  "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);
Ответ err_code 0
{
  "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_typestringТип события. Несколько — через запятую.
Допустимые значения: all, sent, opened, clicked, bounced, unsubscribed, complained
emailsstringАдреса получателей через запятую.
campaign_idstringФильтр по вашей метке кампании.
urlstringОставить только клики по конкретной ссылке.
fromdatetimeС какого времени события. Формат yyyy-mm-dd hh:mm:ss.
todatetimeДо какого времени события.
sortstringпо умолчанию: descПорядок по времени события.
Допустимые значения: desc, asc
startintegerпо умолчанию: 0С какой позиции выводить.
limitintegerпо умолчанию: 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);
Ответ err_code 0
{
  "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 — по дню.

Параметры

ПараметрТипОписание
periodstringпо умолчанию: 1hПериод выборки.
Допустимые значения: 1h, 24h, 7d, 30d, custom
campaign_idstringФильтр по вашей метке кампании.
groupbystringРазмер слота. Обязателен при period=custom.
Допустимые значения: hour, day, week, month
start_datedatetimeНачало периода. Обязателен при period=custom. Если время не указано, берётся 00:00:00.
finish_datedatetimeКонец периода. Обязателен при 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);
Ответ err_code 0
{
  "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".

Что приходит в запросе

ПолеТипОписание
eventstringТип события из таблицы выше.
emailstringАдрес получателя.
event_timedatetimeВремя события.
codestringКод ошибки, если она была.
descriptionstringТекст ошибки от принимающей стороны. Рядом могут прийти error и reason.
custom_varsJSONВаши переменные из заголовка X-Dashamail-Variables.
secretstringПодпись для проверки подлинности — см. ниже.

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

Поле secret считается так:

md5($_POST['email'] . $_POST['message_id'] . $webhook_key)

Ключ $webhook_key лежит в разделе Email-транспорт → Транзакционное API. Сверяйте — иначе вебхук может прислать кто угодно.

Как читать причину возврата

В reason приходит hardfail, когда причина названа явно, и old, когда письмо не удалось доставить после многих попыток. Сам текст ошибки — в description.

По code ориентироваться проще: коды на 5 — жёсткие возвраты (ящика нет, ящик заблокирован), на 4 — мягкие, временная невозможность доставки. Жалоба на спам обычно приходит с кодом 9.9.9.

Библиотеки #

Написали свою библиотеку или очень хотите, чтобы она появилась — напишите на support@dashamail.ru. Мы всегда рады талантливым разработчикам.

Вопросы #

Метод ведёт себя не так, как здесь написано — пишите на support@dashamail.ru. Приложите transaction_id: с ним разбираться заметно быстрее.

DashaMail хранит и защищает ваши данные на территории Российской Федерации

Подробнее...