Обзор SDK — DashaMail REST API v2

Шесть официальных библиотек — по одной на каждый популярный язык backend-разработки. Все построены поверх одной и той же спецификации, что и этот справочник, поэтому ресурсы и параметры называются одинаково независимо от языка. Ни одна не тянет внешних зависимостей: только стандартная библиотека языка плюс HTTP-клиент из его же экосистемы.

Языки #

Язык	Пакет	Требования	Репозиторий
PHP	`composer require dashamail/dashamail-php`	PHP 7.2+	dashamail-php
Python	`pip install dashamail-python`	Python 3.7+	dashamail-python
Node.js	`npm install @dashamail/node`	Node.js 12+	dashamail-node
Ruby	`gem install dashamail-ruby`	Ruby 2.5+	dashamail-ruby
.NET	`dotnet add package DashaMail`	.NET 6.0+	dashamail-dotnet
Java	`com.dashamail:dashamail-java` (Maven/Gradle)	Java 11+	dashamail-java

Пакеты dashamail-python (PyPI) и @dashamail/node (npm, скоуп вместо голого имени) называются так намеренно: короткое имя dashamail в обоих реестрах занято сторонним неофициальным клиентом. Импорт в Python при этом остаётся коротким — import dashamail.

Быстрый старт на каждом языке #

Тот же сценарий, что и в разделе Быстрый старт — создать базу, добавить подписчика, отправить транзакционное письмо, — но через SDK вместо сырых HTTP-запросов.

use DashaMail\DashaMail;

$dashamail = new DashaMail('YOUR_API_KEY');

$list = $dashamail->lists->create('Клиенты интернет-магазина');
$dashamail->lists->addMember($list['list_id'], 'ivan@example.com', [
    'merge_1' => 'Иван',
]);

$dashamail->transactional->send(
    'ivan@example.com',
    'noreply@yourdomain.ru',
    '<p>Спасибо за заказ!</p>',
    ['subject' => 'Заказ №1024 оплачен']
);

from dashamail import DashaMail

dashamail = DashaMail("YOUR_API_KEY")

created = dashamail.lists.create("Клиенты интернет-магазина")
dashamail.lists.add_member(created["list_id"], "ivan@example.com", merge_1="Иван")

dashamail.transactional.send(
    "ivan@example.com",
    "noreply@yourdomain.ru",
    "<p>Спасибо за заказ!</p>",
    subject="Заказ №1024 оплачен",
)

const DashaMail = require('@dashamail/node');

const dashamail = new DashaMail('YOUR_API_KEY');

const created = await dashamail.lists.create('Клиенты интернет-магазина');
await dashamail.lists.addMember(created.data.list_id, 'ivan@example.com', {
  merge_1: 'Иван',
});

await dashamail.transactional.send(
  'ivan@example.com',
  'noreply@yourdomain.ru',
  '<p>Спасибо за заказ!</p>',
  { subject: 'Заказ №1024 оплачен' }
);

require "dashamail"

dashamail = DashaMail.new("YOUR_API_KEY")

created = dashamail.lists.create("Клиенты интернет-магазина")
dashamail.lists.add_member(created["list_id"], "ivan@example.com", merge_1: "Иван")

dashamail.transactional.send_message(
  "ivan@example.com",
  "noreply@yourdomain.ru",
  "<p>Спасибо за заказ!</p>",
  subject: "Заказ №1024 оплачен"
)

using DashaMail;

var dashamail = new DashaMailClient("YOUR_API_KEY");

var created = await dashamail.Lists.CreateAsync("Клиенты интернет-магазина");
await dashamail.Lists.AddMemberAsync(created["list_id"], "ivan@example.com",
    new Dictionary<string, object> { { "merge_1", "Иван" } });

await dashamail.Transactional.SendAsync(
    "ivan@example.com", "noreply@yourdomain.ru", "<p>Спасибо за заказ!</p>",
    new Dictionary<string, object> { { "subject", "Заказ №1024 оплачен" } });

DashaMailClient dashamail = new DashaMailClient("YOUR_API_KEY");

DashaMailResponse created = dashamail.lists().create("Клиенты интернет-магазина");
dashamail.lists().addMember(created.get("list_id"), "ivan@example.com",
    Map.of("merge_1", "Иван"));

dashamail.transactional().send(
    "ivan@example.com", "noreply@yourdomain.ru", "<p>Спасибо за заказ!</p>",
    Map.of("subject", "Заказ №1024 оплачен"));

Что общего у всех шести #

Реализации разные, но идеи одни и те же — освоив одну библиотеку, легко читать код на другой.

Ресурсы по разделам API. Один клиент, а на нём — свойство или геттер на каждый раздел: lists, campaigns, transactional и так далее, один в один с разделами этого справочника.
Разбор конверта уже сделан. Методы возвращают сразу response.data, а не сырой JSON — конверт с msg и полем-обёрткой response разбирается внутри клиента.
Пагинация через has_more. У списочных методов результат несёт при себе признак «есть ещё» и применённый limit — так же, как в сыром API (см. Формат запросов и ответов), без отдельного подсчёта общего числа записей.
Ошибки — типизированные исключения. HTTP-статус ответа определяет класс исключения (401 → ошибка аутентификации, 429 → превышение лимита с временем ожидания и так далее) — код ошибки API из справочника кодов остаётся доступен внутри исключения на случай, если нужна ветка именно по нему.
Ни одной внешней зависимости. HTTP и JSON — из стандартной библиотеки языка (или, если в языке нет своего JSON, как в Java — из небольшого кода внутри самой библиотеки). Ничего лишнего не попадает транзитивно в ваш проект.

Изображения — не JSON #

Единственный эндпоинт со своей формой — POST /images/optimize (см. раздел Изображения). В каждом SDK у него отдельный набор методов: передать файл с диска или байты из памяти, получить обратно JSON с base64 либо сырые байты напрямую — подробности на странице конкретного языка.

Дальше #

PHP — DashaMail\DashaMail, Composer.
Python — dashamail.DashaMail, pip.
Node.js — @dashamail/node, npm, готовые типы TypeScript.
Ruby — класс DashaMail, RubyGems.
.NET — DashaMail.DashaMailClient, NuGet.
Java — com.dashamail.sdk.DashaMailClient, Maven/Gradle.

SDK для REST API v2

Языки #

Быстрый старт на каждом языке #

Что общего у всех шести #

Изображения — не JSON #

Дальше #