Переход с API 1.0 — DashaMail REST API v2

Возможности и имена параметров в v2 те же, что в старом API вида ?method=lists.get. Меняются адресация, HTTP-методы и форма ответа.

Что изменилось #

Что	API 1.0	API v2
Адресация	`?method=lists.get`	`GET /v2/lists`
HTTP-методы	Всё через `GET` или `POST`	`GET`, `POST`, `PUT`, `DELETE` по смыслу операции
Ключ	`?api_key=` либо `username` + `password`	Заголовок `Authorization: Bearer`; `?api_key=` тоже работает. Вход по логину и паролю убран
Код ответа	Всегда `200`, ошибка внутри `msg`	HTTP-статус отражает результат: `201`, `204`, `4xx`, `5xx`
Ответ при ошибке	`{"response":{"msg":{"err_code":5,…}}}`	`{"error":{"code":5,"message":"…"}}`
Ответ при успехе	`{"response":{"msg":…,"data":…}}`	Без изменений — тот же конверт
Формат вывода	`format=json\|xml\|jsonp`	Только JSON, параметр `format` не поддерживается
Кодировка	Параметр `charset`	Всегда UTF-8

Успешный ответ не изменился: полезная нагрузка по-прежнему лежит в response.data. Если разбор ответа у вас уже написан, переписывать его не нужно — достаточно добавить проверку HTTP-статуса и ветку для error.

Параметры #

Имена параметров совпадают со старым API. Разница в том, что часть из них теперь берётся из URL: /lists/128341/members — это list_id=128341 для метода lists.get_members. Все остальные параметры передаются в теле запроса и попадают в тот же обработчик без изменений.

Практическое следствие: если какого-то фильтра нет в таблице параметров эндпоинта, но он был в старом API — просто передайте его в теле, он будет учтён.

Таблица соответствия #

Метод 1.0	Эндпоинт v2
`lists.get`	`GET /lists`, `GET /lists/{list_id}`
`lists.add`	`POST /lists`
`lists.update`	`PUT /lists/{list_id}`
`lists.delete`	`DELETE /lists/{list_id}`
`lists.get_members`	`GET /lists/{list_id}/members`
`lists.add_member`	`POST /lists/{list_id}/members`
`lists.add_member_batch`	`POST /lists/{list_id}/members/batch`
`lists.upload`	`POST /lists/{list_id}/members/import`
`lists.get_import_result`	`GET /lists/{list_id}/members/import`
`lists.get_member`	`GET /lists/{list_id}/members/{email}`
`lists.update_member`	`PUT /lists/{list_id}/members/{email}`
`lists.delete_member`	`DELETE /lists/{list_id}/members/{email}`
`lists.unsubscribe_member`	`POST /lists/{list_id}/members/{email}/unsubscribe`
`lists.move_member`	`POST /lists/{list_id}/members/{email}/move`
`lists.copy_member`	`POST /lists/{list_id}/members/{email}/copy`
`lists.member_activity`	`GET /lists/{list_id}/members/{email}/activity`
`lists.clean_list`	`POST /lists/{list_id}/clean`
`lists.get_unsubscribed`	`GET /lists/{list_id}/unsubscribed`
`lists.get_complaints`	`GET /lists/{list_id}/complaints`
`lists.get_import_history`	`GET /lists/{list_id}/import-history`
`lists.last_status`	`GET /lists/{list_id}/last-status`
`lists.add_merge`	`POST /lists/{list_id}/fields`
`lists.update_merge`	`PUT /lists/{list_id}/fields/{merge_id}`
`lists.delete_merge`	`DELETE /lists/{list_id}/fields/{merge_id}`
`campaigns.get`	`GET /campaigns`, `GET /campaigns/{campaign_id}`
`campaigns.create`	`POST /campaigns`
`campaigns.update`	`PUT /campaigns/{campaign_id}`
`campaigns.delete`	`DELETE /campaigns/{campaign_id}`
`campaigns.copy`	`POST /campaigns/{campaign_id}/copy`
`campaigns.pause`	`POST /campaigns/{campaign_id}/pause`
`campaigns.restart_paused`	`POST /campaigns/{campaign_id}/resume`
`campaigns.resend_unopened`	`POST /campaigns/{campaign_id}/resend`
`campaigns.attach`	`POST /campaigns/{campaign_id}/attachments`
`campaigns.get_attachments`	`GET /campaigns/{campaign_id}/attachments`
`campaigns.delete_attachment`	`DELETE /campaigns/{campaign_id}/attachments/{id}`
`campaigns.get_folders`	`GET /campaigns/folders`
`campaigns.move_to_folder`	`POST /campaigns/{campaign_id}/move`
`campaigns.get_automations`	`GET /automations`
`campaigns.create_auto`	`POST /automations`
`campaigns.update_auto`	`PUT /automations/{campaign_id}`
`campaigns.delete_automation`	`DELETE /automations/{campaign_id}`
`campaigns.force_auto`	`POST /automations/{campaign_id}/trigger`
`campaigns.copy_automation`	`POST /automations/{campaign_id}/copy`
`campaigns.get_templates`	`GET /templates`
`campaigns.get_saved_templates`	`GET /templates/saved`
`campaigns.add_template`	`POST /templates`
`campaigns.delete_template`	`DELETE /templates/{id}`
`reports.summary` и другие	`GET /reports/{campaign_id}/{метрика}`
`account.get_balance`	`GET /account/balance`
`account.get_confirmed`	`GET /account/senders`
`account.confirm_from_email`	`POST /account/senders/confirm`
`account.get_domains`	`GET /account/domains`
`account.add_domain`	`POST /account/domains`
`account.check_domains`	`GET /account/domains/check`
`account.delete_domain`	`DELETE /account/domains/{domain}`
`account.get_webhooks`	`GET /account/webhooks`
`account.add_webhooks`	`POST /account/webhooks`
`account.delete_webhooks`	`DELETE /account/webhooks/{event_name}`

Пример переписывания #

Было

curl 'https://api.dashamail.com/?method=lists.add_member&api_key=KEY\
&list_id=128341&email=ivan@example.com&merge_1=%D0%98%D0%B2%D0%B0%D0%BD'

Стало

curl -X POST 'https://api.dashamail.com/v2/lists/128341/members' \
  -H 'Authorization: Bearer KEY' \
  -H 'Content-Type: application/json' \
  -d '{"email": "ivan@example.com", "merge_1": "Иван"}'

Поддержка старого API #

API 1.0 продолжает работать — переход на v2 не обязателен и не имеет срока. Обе версии обращаются к одной и той же логике, поэтому их можно использовать одновременно, в том числе с одним ключом.