MCP-сервер

Адрес и что внутри #

https://mcp.dashamail.ru/

Транспорт — Streamable HTTP, версия протокола 2025-06-18. Сервер отдаёт 71 инструмент по всем разделам API: адресные базы и подписчики, рассылки и отчёты, шаблоны, автоматизации, транзакционные письма, вебхуки, обработка входящих. Полный перечень с аргументами — в справочнике ниже.

Подключение #

Способов два — зависит от клиента.

Через OAuth: Claude.ai, Claude Desktop, ChatGPT

1. В настройках клиента добавьте MCP-сервер (custom connector) с адресом https://mcp.dashamail.ru/.
2. Клиент откроет вход в личный кабинет DashaMail — войдите, как обычно.
3. На экране согласия видно, какое приложение и какие права запрашивает. Нажмите «Разрешить».

После этого в кабинете (Аккаунт → API-ключи) появится ключ с именем «MCP · <приложение>» и бейджем OAuth. Он живёт 30 дней, приложение продлевает его само. Отозвали ключ — приложение отключилось, продлить его оно не сможет.

По API-ключу: Claude Code, Cursor, Codex и другие

Клиенты, которые позволяют задать заголовок запроса, подключаются обычным API-ключом из кабинета — без OAuth:

Authorization: Bearer YOUR_API_KEY

Claude Code:

claude mcp add --transport http dashamail https://mcp.dashamail.ru/ \
  --header "Authorization: Bearer YOUR_API_KEY"

Cursor и другие клиенты с настройкой в JSON:

{
  "mcpServers": {
    "dashamail": {
      "url": "https://mcp.dashamail.ru/",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Права #

Ключ, выданный через OAuth, несёт список прав: приложение запрашивает набор, пользователь на экране согласия оставляет из него столько, сколько считает нужным. Обычный ключ из кабинета по умолчанию без ограничений; права ему можно задать при выпуске или изменить позже кнопкой «Права» в разделе API-ключей — это касается и ключей приложений. Права иерархичны: send включает write, write включает read. Список и что каждое право открывает — в разделе «Ключи с ограниченными правами».

Сервер показывает ассистенту только те инструменты, на которые у ключа есть право, а API проверяет право ещё раз на каждом вызове: запрос вне прав получает 403 с code: 62.

Настройка через адрес #

Флаги сочетаются: ?toolset=core&readonly=1.

Как сервер обращается с данными #

• Черновик — отдельно, отправка — отдельно. campaigns_create всегда создаёт черновик; письма уходят только через campaigns_schedule или campaigns_send_now. Эти инструменты помечены как необратимые, и клиенты (Claude, Cursor) спрашивают подтверждение пользователя перед вызовом.
• Каждый инструмент помечен — читает, меняет, отправляет или удаляет (аннотации протокола readOnlyHint и destructiveHint). Ассистент видит это до вызова.
• Необратимых удалений почти нет. Удалить можно только черновик рассылки; удаление баз, подписчиков и доменов через MCP недоступно — для этого есть кабинет и API.
• Аргументы вне схемы отклоняются. Нельзя, например, подсунуть status=MODERATING в правку черновика и запустить рассылку в обход инструмента отправки.
• Вёрстка писем в списках вырезана, чтобы не раздувать контекст; за ней — campaigns_get с with_html. Ответ длиннее 200 КБ обрезается с подсказкой сузить запрос.
• Пустой результат — не ошибка: приходит как items: [].

Ошибки #

Справочник инструментов #

Имена — <раздел>_<действие>; клиент добавляет к ним префикс сервера сам. Аргументы — те же параметры, что у соответствующих методов REST API, только в удобном для ассистента виде: флаги — да/нет, дополнительные поля подписчика — объектом merge, вложенные структуры — объектами, а не JSON-строками.

• Аккаунт, отправители, домены 6
• Адресные базы и подписчики 22
• Рассылки 13
• Шаблоны 3
• Автоматизации 2
• Отчёты 9
• Транзакционные письма 4
• Вебхуки 6
• Обработка входящих 4
• Служебные 2

Аккаунт, отправители, домены #

account_get читает #

Баланс и лимиты аккаунта. Текущие лимиты аккаунта и число активных подписчиков. Самый дешёвый запрос — годится для проверки работоспособности ключа.

limit_members — максимум активных подписчиков по тарифу (0 — лимита нет: тариф поштучный, расход считается письмами), members — сколько их сейчас, limit_emails — остаток писем на поштучных тарифах, expiration_date — до какого числа оплачен месячный тариф.

Без аргументов.

senders_list читает #

Подтверждённые адреса отправителей. Список адресов, подтверждённых как обратные. Возвращается массивом строк, не более ста записей.

В from_email рассылки можно ставить только адрес из этого списка.

Без аргументов.

senders_add отправляет #

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

На адрес уходит письмо со ссылкой; отправителем он станет только после перехода по ней.

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

domains_list читает #

Домены отправки и их DNS-статус. Домены аккаунта и состояние их DNS-настроек. Значения берутся из последней проверки — чтобы обновить их, вызовите проверку DNS.

valid_spf и valid_dkim — прошла ли проверка DNS; double_spf — в зоне две SPF-записи, это ошибка.

domains_add меняет #

Добавить домен отправки. Регистрирует домен в аккаунте и возвращает DNS-записи, которые нужно прописать у регистратора. До того как записи появятся в DNS и пройдут проверку, отправка с этого домена не заработает.

Примечание. Кроме домена отправки можно добавить домен статистики — тогда ссылки отслеживания в письмах будут вести на ваш поддомен, а не на домен DashaMail. Оба параметра можно передать в одном запросе.

Возвращает DNS-записи, которые нужно прописать в зоне домена. После этого вызови domains_check.

domains_check читает #

Перепроверить DNS доменов. Запрашивает DNS и обновляет состояние доменов. Вызывайте после того, как прописали записи у регистратора — распространение изменений обычно занимает от нескольких минут до нескольких часов.

Адресные базы и подписчики #

lists_list читает #

Адресные базы. Возвращает все адресные базы аккаунта, от новых к старым, вместе со счётчиками подписчиков по состояниям.

Возвращает id, название, число подписчиков и описание дополнительных полей (merge_1 … merge_N) каждой базы.

lists_get читает #

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

lists_create меняет #

Создать адресную базу. Создаёт новую адресную базу.

Контактные данные (company, address, city и другие) попадают в подвал писем — этого требуют антиспам-политики. Если их не передать, подставятся данные из профиля аккаунта.

lists_update меняет #

Изменить адресную базу. Меняет реквизиты базы. Передавайте только те поля, которые нужно изменить — остальные останутся прежними. Состав дополнительных полей здесь не меняется, для этого есть отдельные эндпоинты.

fields_add меняет #

Добавить дополнительное поле базы. Добавляет в базу новое дополнительное поле. Оно займёт первый свободный номер merge_N.

fields_update меняет #

Изменить дополнительное поле базы. Меняет параметры существующего поля. Незаданные параметры сохраняют прежние значения. Тип поля изменить нельзя.

lists_unsubscribed читает #

Отписавшиеся подписчики. Подписчики, отписавшиеся от рассылок, с датой отписки. Полезно для синхронизации отписок с вашей CRM.

lists_complaints читает #

Пожаловавшиеся на спам. Подписчики, нажавшие «Это спам» в своём почтовом клиенте. Такие адреса исключаются из рассылок навсегда.

members_search читает #

Подписчики базы. Постранично возвращает подписчиков базы.

Примечание. Смещение задаётся параметром start, не offset. По умолчанию отдаётся 100 записей.

Постранично: start — смещение, limit — размер страницы. Точный поиск одного адреса — параметр email.

members_get читает #

Один подписчик. Возвращает записи подписчика по адресу.

Примечание. Поиск идёт по всем базам аккаунта, а не только по указанной в пути. Если адрес есть в нескольких базах, вернутся все записи — различайте их по полю list_id.

Возвращает member_id — он нужен для members_move и members_copy.

members_add меняет #

Добавить подписчика. Добавляет один адрес в базу. Для загрузки нескольких адресов используйте пакетное добавление, для файлов — импорт.

Перед добавлением адрес проверяется по вашему списку отписок, по чёрному списку аккаунта и по глобальному списку возвратов.

Если адрес уже есть в базе, без update=true запрос вернёт ошибку; с update=true — обновит поля. Дополнительные поля — объектом merge: {"merge_1": "Иван"}.

members_add_batch меняет #

Добавить подписчиков пачкой. Загружает несколько подписчиков одним запросом. Каждый элемент batch — такой же объект, как тело добавления одного подписчика.

Примечание. С параметром background запрос сразу возвращает управление, а загрузка идёт в фоне — так стоит поступать с пакетами в тысячи адресов.

members_update меняет #

Изменить подписчика. Обновляет дополнительные поля и состояние подписчика. Подписчик находится по паре «база + адрес» из пути, либо, если передан member_id — по нему.

members_unsubscribe меняет #

Отписать подписчика. Переводит подписчика в состояние unsubscribed и проставляет время отписки. Если адрес есть в нескольких базах, а list_id в пути указывает на конкретную — отписка затронет только её.

members_move меняет #

Перенести подписчика в другую базу. Переносит активного подписчика в другую базу. Запись меняет принадлежность, идентификатор сохраняется.

Перенос считается подпиской на целевую базу — привязанные к ней автоматизации с событием «добавление в базу» сработают.

members_copy меняет #

Скопировать подписчика в другую базу. Создаёт копию записи подписчика в другой базе. Исходная запись остаётся на месте; значения дополнительных полей копируются.

members_activity читает #

История событий подписчика. События подписчика: отправки, доставки, открытия, клики, возвраты, отписки — с привязкой к рассылкам.

members_status читает #

Текущий статус адреса. Быстрая проверка: в каком состоянии находится конкретный адрес в базе. Дешевле, чем выгружать подписчика целиком.

members_check_email читает #

Проверить адрес перед подпиской. Отвечает на вопрос «можно ли добавить этот адрес в базу». Проверяет его по чёрному списку аккаунта, по отпискам в этой базе, по глобальному списку возвратов, а также формат адреса и принадлежность к одноразовым почтовым сервисам.

Полезно вызывать перед добавлением подписчика: так вы заранее отсеете адреса, на которых POST всё равно завершится ошибкой, и не потратите на них попытку.

Примечание. Успешный ответ возвращает адрес в поле valid уже нормализованным — регистр и типичные опечатки в домене исправляются. Добавляйте в базу именно это значение.

Отказы приходят со статусами 409 и 422, но различать причины надёжнее по полю code: статус лишь делит их на «адрес в чёрном списке» и «адрес непригоден».

imports_start меняет #

Запустить импорт подписчиков из файла по URL. Ставит в очередь импорт из файла CSV, XLS, XLSX, TXT или ZIP. Файл либо скачивается по ссылке file, либо загружается как multipart-поле import-file.

Соответствие колонок файла и полей подписчика задаётся номерами колонок, начиная с нуля: email=0 означает, что адрес лежит в первой колонке, merge_1=2 — что первое дополнительное поле лежит в третьей.

Примечание. В одну базу можно поставить не больше пяти задач импорта одновременно. В режиме online импорт запрещён, если в аккаунте уже идёт другой импорт.

Импорт фоновый: результат смотри через imports_status.

imports_status читает #

Результат последнего импорта. Возвращает текстовый отчёт о последнем завершённом импорте в базу.

imports_history читает #

История импортов. Список задач импорта по базе с их состоянием и итогами.

Рассылки #

campaigns_list читает #

Рассылки. Возвращает рассылки аккаунта. Удалённые не показываются, если явно не запрошен статус DELETED.

Примечание. Здесь смещение задаётся параметром offset (в отличие от подписчиков, где используется start). По умолчанию возвращается 100 рассылок.

Вёрстка писем в списке не возвращается — за ней campaigns_get с with_html. Статусы: DRAFT черновик, SCHEDULE запланирована, MODERATING на модерации, SENT отправлена.

campaigns_get читает #

Одна рассылка. Возвращает рассылку целиком, включая HTML- и текстовую версии письма.

campaigns_create меняет #

Создать черновик рассылки. Создаёт черновик рассылки. Отправка не начинается — для этого нужно перевести рассылку в статус запуска.

Содержимое письма можно передать сразу в html, а можно наполнить позже.

Создаёт только черновик — письма не уходят. Запуск отдельными инструментами campaigns_schedule и campaigns_send_now. from_email должен быть из senders_list. В html обязательна ссылка отписки вида <a id="unsub_link" href="%ОТПИСАТЬСЯ%">Отписаться</a>, в plain_text — метка %ОТПИСАТЬСЯ%; без них запуск будет отклонён.

campaigns_update меняет #

Изменить черновик рассылки. Меняет только переданные поля рассылки. Изменять можно рассылки в статусах DRAFT, SCHEDULE, TRIGGER и TEMPLATE; уже отправляющуюся изменить нельзя. Запуск отправки — отдельными инструментами campaigns_schedule и campaigns_send_now.

campaigns_schedule отправляет #

Запланировать отправку рассылки. Запускает черновик по расписанию: рассылка уйдёт всей аудитории базы (с учётом сегмента) в delivery_time по московскому времени. Перед запуском API проверяет тему, отправителя, текст письма и ссылку отписки.

Отменить через API нельзя — только в кабинете.

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

campaigns_send_now отправляет #

Отправить рассылку сейчас. Запускает черновик немедленно: рассылка уходит всей аудитории базы (с учётом сегмента) сразу после модерации. Перед запуском API проверяет тему, отправителя, текст письма и ссылку отписки.

Отменить через API нельзя — только в кабинете.

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

campaigns_pause меняет #

Приостановить отправку. Приостанавливает идущую рассылку. Уже отправленные письма не отзываются.

campaigns_resume меняет #

Возобновить отправку. Продолжает рассылку, поставленную на паузу, с того места, где она остановилась.

campaigns_resend_unopened отправляет #

Переотправить неоткрывшим. Создаёт новую рассылку по тем получателям исходной, кто её не открыл. Обычный приём — повторить письмо через несколько дней с другой темой.

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

campaigns_copy меняет #

Скопировать рассылку. Создаёт копию рассылки вместе с вёрсткой. Копия отправленной или заблокированной рассылки всегда получает статус DRAFT.

Удобный способ сделать новую рассылку по образцу старой: копия создаётся черновиком.

folders_list читает #

Папки рассылок. Список папок, по которым разложены рассылки.

campaigns_move_to_folder меняет #

Переместить рассылку в папку. Перекладывает рассылку в указанную папку.

campaigns_delete удаляет #

Удалить черновик рассылки. Удаляет рассылку, только если она черновик или шаблон (статус DRAFT или TEMPLATE). Отправленные и запланированные рассылки не трогает. Действие необратимо. Перед вызовом получи явное подтверждение пользователя.

Шаблоны #

templates_list читает #

Сохранённые шаблоны аккаунта. Возвращает рассылки в статусе TEMPLATE — без вёрстки, только идентификатор, название и папку. Чтобы получить HTML, запросите рассылку через её эндпоинт.

templates_gallery читает #

Готовые шаблоны из галереи. Возвращает сохранённые HTML-шаблоны аккаунта вместе с вёрсткой, от новых к старым.

templates_create меняет #

Сохранить HTML-шаблон. Сохраняет вёрстку как HTML-шаблон.

В template можно передать либо саму вёрстку, либо число — идентификатор рассылки, чью вёрстку нужно сохранить.

Автоматизации #

automations_list читает #

Автоматизации. Возвращает автоматизации аккаунта вместе с настройками события и задержки.

automations_trigger отправляет #

Запустить автоматизацию для адреса. Отправляет письмо автоматизации конкретному подписчику, не дожидаясь события. Удобно для проверки вёрстки и для сценариев, где момент отправки решает ваша система.

Примечание. Предыдущая отправка этого письма тому же подписчику сбрасывается, поэтому повторный запуск сработает даже если письмо уже уходило.

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

Отчёты #

reports_summary читает #

Сводка по рассылке или по аккаунту. Главные показатели рассылки одним объектом. Отсюда стоит начинать: остальные отчёты нужны, когда требуется детализация.

Примечание. Параметр fast отдаёт заранее посчитанные значения — это заметно быстрее, но несовместимо с фильтром по времени.

Без campaign_id (или с 0) — сводка по всему аккаунту за период time_start…time_end; detailed=1 разбивает её по рассылкам. Метрики: sent отправлено, unique_opened уникальные открытия, opened все открытия, unique_clicked уникальные клики, unsubscribed, complained, hard/soft — возвраты. OR = unique_opened / sent, CTR = unique_clicked / sent, CTOR = unique_clicked / unique_opened. За период sent не возвращается.

reports_recipients читает #

Получатели по событию. Возвращает подписчиков, с которыми произошло указанное событие. Один и тот же формат для семи метрик: sent, delivered, opened, clicked, bounced, complained, unsubscribed.

metric: sent, delivered, opened, clicked, bounced, complained, unsubscribed. Постранично через start/limit.

reports_events читает #

Лента событий рассылки. Все события рассылки в одном потоке, с фильтрами по времени, типу и подписчику. Подходит для синхронизации событий с вашей аналитикой.

Примечание. По умолчанию берутся события за сегодня. Чтобы получить события за другой период, задайте time_start и time_end явно.

reports_links читает #

Клики по ссылкам. Сколько раз кликнули по каждой ссылке письма, от популярных к редким.

reports_link_clickers читает #

Кто кликнул по ссылке. Подписчики, кликнувшие по указанной ссылке, со временем клика. Выборка ограничена последним годом.

reports_bounces читает #

Возвраты по SMTP-кодам. Группировка возвратов по SMTP-кодам с расшифровкой. Помогает понять, дело в несуществующих адресах или в репутации отправителя.

reports_domains читает #

Статистика по почтовым доменам получателей. Доставляемость и вовлечённость в разрезе почтовых провайдеров. Проседание по одному домену обычно означает проблему с репутацией именно у него.

reports_geo читает #

География открытий. Распределение событий по регионам. Ключ — код региона, значение — количество событий.

reports_clients читает #

Устройства, браузеры и почтовые клиенты. Чем получатели читают письмо: браузеры, десктопные клиенты, мобильные устройства. Полезно перед изменением вёрстки.

Транзакционные письма #

transactional_send отправляет #

Отправить транзакционное письмо. Ставит письмо в очередь отправки и сразу возвращает его идентификатор. Фактическая доставка происходит асинхронно — следите за ней через проверку статуса или webhooks.

Нужны как минимум три вещи: получатель, отправитель (from_email либо заголовок From внутри headers) и текст письма (message либо plain_text).

Примечание. В to можно перечислить несколько адресов через запятую. Тогда каждому уйдёт отдельное письмо, а в message_id можно передать столько же идентификаторов, тоже через запятую.

Одно письмо одному или нескольким адресам (to через запятую). Домен from_email должен быть подтверждён (domains_list). message_id — свой идентификатор для идемпотентности и последующего transactional_get.

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

transactional_get читает #

Статус транзакционного письма. Возвращает текущий статус письма и historию его событий. Данные появляются через несколько секунд после отправки.

Примечание. Поиск по конкретному письму доступен за последние шесть месяцев. За более старыми данными обращайтесь к журналу.

Возвращает текущий статус и историю: 5 Sent, 3 Delivered, 7 Opened, 6 Clicked, 4 Bounced, 9 Complained, 8 Unsubscribed. Глубина — 6 месяцев.

transactional_log читает #

Журнал транзакционных писем. События транзакционных писем аккаунта с фильтрами. Основной инструмент для разбора инцидентов: «почему клиент не получил письмо».

Ошибка с code 34 означает, что в аккаунте не настроен домен транзакционной отправки (domains_list) — журнала нет, это не сбой.

transactional_stats читает #

Статистика транзакционных писем по периодам. Агрегированные показатели транзакционных писем за период, разложенные по временным интервалам. Годится для построения графиков доставляемости.

Примечание. Ширина интервала подбирается по периоду автоматически: пять минут для 1h, час для 24h, сутки для 7d и 30d.

Ошибка с code 34 означает, что в аккаунте не настроен домен транзакционной отправки — статистики нет, это не сбой.

Вебхуки #

webhooks_list читает #

Вебхуки массовых рассылок. Текущие адреса, на которые уходят события массовых рассылок — объект вида «событие → URL».

webhooks_set меняет #

Задать URL вебхука массовых рассылок. Задаёт адреса приёма событий. Ключ каждого параметра — имя события, значение — URL. Передавайте только те события, которые нужно изменить; пустая строка отключает событие.

Одно событие — один URL (https). Пустой url отключает событие. События: open, click, hard, spam, unsub, subscribe, confirm.

webhooks_delete удаляет #

Удалить вебхук массовых рассылок. Отключает приём событий указанного типа.

Внимание. Если event_name не распознан, удаляются настройки всех событий сразу. Проверяйте имя события перед вызовом.

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

webhooks_list_transactional читает #

Вебхуки транзакционных писем. Адреса приёма событий транзакционных писем. Набор событий отличается от массовых рассылок — здесь есть send, delivered и dropped.

webhooks_set_transactional меняет #

Задать URL вебхука транзакционных писем. Задаёт адреса приёма событий транзакционных писем. Формат тот же, что и для массовых рассылок: ключ — имя события, значение — URL.

Одно событие — один URL (https). Пустой url отключает событие. События: send, delivered, dropped, open, click, hard, spam, unsub.

webhooks_delete_transactional удаляет #

Удалить вебхук транзакционных писем. Отключает приём событий указанного типа для транзакционных писем.

Внимание. Как и для массовых рассылок: нераспознанное имя события приводит к удалению настроек всех событий.

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

Обработка входящих #

router_routes_list читает #

Маршруты входящей почты. Все маршруты аккаунта в порядке применения — по возрастанию priority.

Без аргументов.

router_messages_list читает #

Входящие письма Роутера. Письма, сохранённые действием store. Тело письма в список не входит — забирайте его поштучно.

router_messages_get читает #

Одно входящее письмо Роутера. Возвращает разобранное письмо: заголовки, текстовую и HTML-версии, перечень вложений.

router_deliveries_list читает #

Доставки Роутера. Попытки доставки писем на ваши webhook-адреса и адреса пересылки. Первое место, куда стоит смотреть, если письма до вашей системы не доходят.

Служебные #

whoami читает #

Кто я. Аккаунт, от имени которого работает подключение: идентификаторы, логин, права токена, а при праве account.read — тариф и баланс; плюс активный набор инструментов и режим «только чтение». Вызывай первым, если не знаешь, с каким аккаунтом работаешь.

Без аргументов.

get_dashboard_link читает #

Ссылка на страницу кабинета. Ссылка на страницу личного кабинета DashaMail — когда пользователю удобнее доделать руками: отчёт по рассылке, подписчики базы, поля базы, API-ключи.