Mailtrap

Официальный MCP-сервер Mailtrap

Официальный MCP-сервер для Mailtrap — платформы доставки электронной почты. Он подключает ваш аккаунт Mailtrap к Claude, Cursor, VS Code и другим MCP-совместимым ИИ-ассистентам.

Отправляйте транзакционные и массовые письма, безопасно тестируйте сообщения в Email Sandbox, управляйте шаблонами, контактами, доменами отправки и вебхуками, просматривайте журналы писем и статистику доставки, устраняйте проблемы с доставляемостью и управляйте ресурсами аккаунта — всё с помощью запросов на естественном языке.

Возможности

• Email API и SMTP — Отправка транзакционных и массовых писем, включая пакетные и шаблонные сообщения.
• Тестирование писем — Тестирование сообщений в Email Sandbox и проверка содержимого, заголовков, вложений, спам-оценок и совместимости с HTML-клиентами.
• Мониторинг доставки — Поиск в журналах писем, просмотр истории событий и анализ показателей доставки, отказов, открытий, кликов и спама.
• Инфраструктура электронной почты — Управление доменами отправки, DNS-верификацией, вебхуками и подавлениями.
• Контакты — Управление контактами, списками, пользовательскими полями и событиями, включая импорт и экспорт.
• Управление аккаунтом — Просмотр использования биллинга и управление доступом, разрешениями, API-токенами и субрасчетами.

Поддерживаемые MCP-клиенты

Работает с Claude Desktop, Claude Code, Cursor, VS Code и любым другим MCP-совместимым клиентом. Инструкции по настройке для каждого приведены ниже.

Предварительные требования

Перед использованием этого MCP-сервера вам необходимо:

1. Создать аккаунт Mailtrap
2. Подтвердить ваш домен
3. Получить API-токен в настройках API Mailtrap
4. Получить ваш Account ID в управлении аккаунтом Mailtrap

Требуемые переменные окружения:

• MAILTRAP_API_TOKEN — Требуется для всех функций
• MAILTRAP_ACCOUNT_ID — Требуется для шаблонов, статистики, журналов писем, просмотра списка/сообщений песочницы, доменов отправки и подавлений. Необязательна только для инструментов отправки (send-email, send-sandbox-email и инструментов batch-send-*), инструментов email-кампаний, инструментов информации о компании и инструментов отказа от отслеживания.

Необязательные (можно передавать как параметры инструментов):

• DEFAULT_FROM_EMAIL — Отправитель по умолчанию, когда from не указан для send-email, send-sandbox-email или инструментов batch-send-* (где он заполняет base.from). Позволяет переключать отправителя для каждого вызова через параметр from.
• MAILTRAP_SANDBOX_ID — ID песочницы по умолчанию для инструментов песочницы, когда sandbox_id не указан. Позволяет переключаться между песочницами для каждого вызова через параметр sandbox_id.
• MAILTRAP_TEST_INBOX_ID — ID тестового инбокса по умолчанию для инструментов песочницы, когда test_inbox_id не указан. Позволяет переключаться между инбоксами для каждого вызова через параметр test_inbox_id. Устаревший псевдоним для MAILTRAP_SANDBOX_ID, по-прежнему используется как запасной вариант.
• MAILTRAP_ORGANIZATION_ID — Требуется для инструментов организации (list-sub-accounts, create-sub-account).
• MAILTRAP_ORGANIZATION_API_TOKEN — API-токен с областью организации. Требуется для инструментов организации (отдельно от MAILTRAP_API_TOKEN).

Быстрая установка

Smithery CLI

Smithery — это установщик реестра и менеджер для MCP-серверов, который работает со всеми ИИ-клиентами.

npx @smithery/cli install mailtrap

Smithery автоматически обрабатывает конфигурацию клиента и предоставляет интерактивный процесс настройки. Это самый простой способ начать работу с MCP-серверами локально.

Настройка

Claude Desktop

Используйте MCPB для установки сервера Mailtrap. Эти файлы можно найти в Releases.
Скачайте файл .MCPB и откройте его. Если у вас установлен Claude Desktop — он откроет его и предложит настроить.

Claude Desktop или Cursor

Добавьте следующую конфигурацию:

{
  "mcpServers": {
    "mailtrap": {
      "command": "npx",
      "args": ["-y", "mcp-mailtrap"],
      "env": {
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "your_sender@example.com",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

Если вы используете asdf для управления Node.js, вы должны использовать абсолютный путь к исполняемому файлу (пример для Mac)

{
  "mcpServers": {
    "mailtrap": {
      "command": "/Users/<username>/.asdf/shims/npx",
      "args": ["-y", "mcp-mailtrap"],
      "env": {
        "PATH": "/Users/<username>/.asdf/shims:/usr/bin:/bin",
        "ASDF_DIR": "/opt/homebrew/opt/asdf/libexec",
        "ASDF_DATA_DIR": "/Users/<username>/.asdf",
        "ASDF_NODEJS_VERSION": "20.6.1",
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "your_sender@example.com",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

Расположение файла конфигурации Claude Desktop

Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Расположение файла конфигурации Cursor

Mac: ~/.cursor/mcp.json

Windows: %USERPROFILE%\.cursor\mcp.json

VS Code

Ручное изменение конфигурации

Выполните в палитре команд: Preferences: Open User Settings (JSON)

Затем в файле настроек добавьте следующую конфигурацию:

{
  "mcp": {
    "servers": {
      "mailtrap": {
        "command": "npx",
        "args": ["-y", "mcp-mailtrap"],
        "env": {
          "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
          "DEFAULT_FROM_EMAIL": "your_sender@example.com",
          "MAILTRAP_ACCOUNT_ID": "your_account_id",
          "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
        }
      }
    }
  }
}

[!TIP] Не забудьте перезапустить ваш MCP-сервер после изменения раздела "env".

MCP Bundle (MCPB)

Для простой установки в хостах, поддерживающих MCP Bundles, вы можете распространять файл пакета .mcpb.

# Build TypeScript and pack the MCPB bundle
npm run mcpb:pack

# Inspect bundle metadata
npm run mcpb:info

# Sign the bundle for distribution (optional)
npm run mcpb:sign

Это создаёт mailtrap-mcp.mcpb с использованием репозитория manifest.json и собранных артефактов в dist/.

Использование

После настройки вы можете попросить агента отправлять письма и управлять шаблонами, например:

Операции отправки писем:

• "Отправь письмо на john.doe@example.com с темой 'Встреча завтра' и дружеским напоминанием о нашей предстоящей встрече."
• "Напиши sarah@example.com об обновлении проекта и скопируй команду на team@example.com"
• "Отправь приветственный шаблон (uuid b81aabcd-1a1e-41cf-91b6-eca0254b3d96) на new@example.com с переменными { name: 'Alex' }"
• "Отправь письмо в песочницу на test@example.com с темой 'Тестовый шаблон', чтобы просмотреть, как выглядит наше приветственное письмо"

Журналы писем (отладка доставки):

• "Покажи мои недавние журналы отправленных писем"
• "Покажи журналы писем, отправленных на user@example.com"
• "Получи сообщение журнала для ID abc-123-uuid, чтобы проверить статус доставки"

Статистика отправки:

• "Получи статистику отправки за январь 2025"
• "Покажи показатели доставки по доменам за прошлый месяц"
• "Какая у меня статистика писем по категориям с 2025-01-01 по 2025-01-31?"

Операции с песочницей:

• "Получи все сообщения из моего инбокса песочницы"
• "Покажи первую страницу сообщений песочницы"
• "Найди сообщения, содержащие 'test', в моём инбоксе песочницы"
• "Покажи детали сообщения песочницы с ID 5159037506"

Операции с шаблонами:

• "Перечисли все шаблоны писем в моём аккаунте Mailtrap"
• "Создай новый шаблон письма под названием 'Приветственное письмо' с темой 'Добро пожаловать на нашу платформу!'"
• "Обнови шаблон с ID 12345, изменив тему на 'Обновлённое приветственное сообщение'"
• "Удали шаблон с ID 67890"

Домены отправки:

• "Перечисли мои домены отправки"
• "Получи домен отправки с ID 3938"
• "Создай домен отправки для example.com"
• "Включи отслеживание кликов для домена отправки 3938"
• "Удали домен отправки 3938"
• "Получи домен отправки 3938 с инструкциями по настройке DNS"
• "Покажи информацию о компании для домена отправки 3938"
• "Установи информацию о компании для домена 3938: Acme Inc, 123 Main St, San Francisco, US, 94105, https://acme.com"
• "Измени город в информации о компании для домена 3938 на New York"

Подавления:

• "Перечисли подавления для bounced@example.com"
• "Подави bounced@example.com в транзакционном потоке домена 3938"
• "Покажи все подавленные email-адреса"
• "Почему user@example.com не получает мои письма?"
• "Удали user@example.com из списка подавлений"

Отказы от отслеживания:

• "Прекрати отслеживать открытия и клики для privacy@example.com на домене 3938"
• "Перечисли всех, кто отказался от отслеживания"

Контакты и списки:

• "Добавь john.doe@example.com в мой список рассылки новостей"
• "Покажи все мои списки контактов"
• "Создай поле контакта под названием 'signup_source' для отслеживания источника контактов"
• "Обнови контакт john.doe@example.com, установив их план на 'pro'"
• "Импортируй контакты из этого CSV в мой список онбординга"
• "Экспортируй все контакты из моего списка рассылки новостей"
• "Запиши событие 'trial_started' для контакта john.doe@example.com"

Вебхуки:

• "Перечисли все вебхуки, настроенные в моём аккаунте"
• "Создай вебхук, указывающий на https://example.com/hooks/mailtrap, для событий отказов и спама"
• "Обнови вебхук 4821, чтобы он также отправлял события доставки"
• "Удали вебхук 4821"

Аккаунт и биллинг:

• "Каково моё текущее использование биллинга в этом месяце?"
• "Сколько писем у меня осталось в моём плане?"
• "Перечисли всех, у кого есть доступ к этому аккаунту Mailtrap"
• "Покажи ресурсы разрешений, доступные в моём аккаунте"

API-токены:

• "Перечисли все API-токены в моём аккаунте"
• "Создай новый API-токен для staging-окружения"
• "Сбрось API-токен с ID 1234"
• "Удали неиспользуемый API-токен 1234"

Организация и субрасчеты:

• "Перечисли все субрасчеты в моей организации"
• "Создай новый субрасчет для клиентского проекта 'Acme Corp'"

Доступные инструменты

send-email

Отправляет транзакционное письмо через Mailtrap. Поддерживает два взаимоисключающих режима — встроенное содержимое (subject + text/html) или на основе шаблона (template_uuid).

Параметры:

• from (необязательно): Отправитель как { email, name? } (простая строка email также принимается во время выполнения). Если не указан, используется DEFAULT_FROM_EMAIL.
• to (необязательно): Массив получателей как объекты { email, name? } (простые строки email или один не-массивный адрес также принимаются во время выполнения). Необязательно, если указан cc или bcc; по крайней мере один из to / cc / bcc должен содержать получателя.
• cc (необязательно): Массив получателей копии (CC) как объекты { email, name? } (простые строки email также принимаются во время выполнения).
• bcc (необязательно): Массив получателей скрытой копии (BCC) как объекты { email, name? } (простые строки email также принимаются во время выполнения).
• subject (условно): Тема письма. Требуется для встроенных отправок; должен быть опущен, когда установлен template_uuid.
• text (условно): Текст тела письма. Требуется (вместе с html или вместо него) для встроенных отправок; должен быть опущен, когда установлен template_uuid.
• html (условно): HTML-версия тела письма. Требуется (вместе с text или вместо него) для встроенных отправок; должен быть опущен, когда установлен template_uuid.
• category (необязательно): Категория письма для отслеживания и аналитики. Должна быть опущена, когда установлен template_uuid.
• template_uuid (необязательно): Использовать шаблон письма Mailtrap вместо встроенного содержимого. Когда установлен, subject / text / html / category должны быть опущены (согласно API Mailtrap).
• template_variables (необязательно): Объект переменных, подставляемых в шаблон, на который ссылается template_uuid. Разрешён только вместе с template_uuid.

batch-send-transactional-email

Отправляет пакет транзакционных писем одним вызовом API Mailtrap (поток отправки по умолчанию). Общие поля помещаются в base; переопределения для каждого получателя — в requests[]. Каждый запрос должен включать по крайней мере одного получателя через to, cc или bcc. Та же взаимоисключаемость встроенного содержимого и шаблона, что и в send-email — проверяется после объединения базовых данных с каждым запросом.

Параметры:

• base (необязательно): Объект с полями, общими для всего пакета.
  • from (необязательно): Отправитель в виде { email, name? } (простая строка с email также принимается во время выполнения). Если не указано, используется DEFAULT_FROM_EMAIL.
  • reply_to (необязательно): Адрес для ответа (Reply-to).
  • subject / text / html / category (необязательно, встроенный режим): Содержимое по умолчанию для каждого запроса.
  • template_uuid / template_variables (необязательно, режим шаблона): Шаблон по умолчанию + переменные. Взаимоисключающие со встроенными полями.
  • custom_variables (необязательно): Пользовательские переменные по умолчанию (со строковыми значениями).
  • headers (необязательно): Пользовательские заголовки по умолчанию.
• requests (обязательно): Непустой массив сообщений для каждого получателя. Каждая запись содержит:
  • to (необязательно): Массив получателей в виде объектов { email, name? } (простые строки с email или один адрес без массива также принимаются во время выполнения). Необязательно, если указаны cc или bcc; по крайней мере одно из полей to / cc / bcc должно содержать получателя.
  • cc, bcc, reply_to (необязательно).
  • Встроенные (subject/text/html/category) или шаблонные (template_uuid/template_variables) переопределения; любое пропущенное поле возвращается к соответствующему значению из base.
  • custom_variables, headers (необязательно).

batch-send-bulk-email

Отправляет пакет массовых писем через bulk-stream API Mailtrap. Та же структура base + requests[], правила валидации и правила встроенного/шаблонного режима, что и в batch-send-transactional-email — единственное отличие в том, что этот инструмент направляет вызов через bulk-эндпоинт вместо транзакционного. См. параметры выше.

list-email-logs

Выводит журналы отправленных писем (историю доставки) с необязательной пагинацией и фильтрами. Используйте для отладки проблем с доставкой прямо из IDE.

Параметры:

• search_after (необязательно): Курсор пагинации из поля next_page_cursor предыдущего ответа
• sent_after (необязательно): Дата/время в формате ISO 8601; только письма, отправленные после этого времени
• sent_before (необязательно): Дата/время в формате ISO 8601; только письма, отправленные до этого времени
• from_email (необязательно): Фильтр по email отправителя; используется с from_operator (по умолчанию: ci_equal)
• to_email (необязательно): Фильтр по email получателя; используется с to_operator (по умолчанию: ci_equal)
• status (необязательно): Фильтр по статусу доставки: delivered, not_delivered, enqueued, opted_out; используется с status_operator (по умолчанию: equal)
• subject (необязательно): Фильтр по теме письма; используется с subject_operator (по умолчанию: ci_contain). Используйте subject_operator: empty/not_empty для фильтрации по наличию темы.
• sending_domain_id (необязательно): Фильтр по ID домена отправки (число); используется с sending_domain_id_operator (по умолчанию: equal)
• sending_stream (необязательно): Фильтр по потоку: transactional или bulk; используется с sending_stream_operator (по умолчанию: equal)
• events (необязательно): Фильтр по типу(ам) события: delivery, open, click, bounce, spam, unsubscribe, soft_bounce, reject, suspension; используется с events_operator (include_event / not_include_event)
• clicks_count / opens_count (необязательно): Фильтр по количеству кликов/открытий; используется с *_operator: equal, greater_than, less_than
• client_ip / sending_ip (необязательно): Фильтр по IP; используется с *_operator: equal, not_equal, contain, not_contain
• email_service_provider_response (необязательно): Фильтр по тексту ответа провайдера; используется с *_operator (ci_contain и т.д.)
• email_service_provider (необязательно): Фильтр по провайдеру (точное совпадение); используется с *_operator: equal, not_equal
• recipient_mx (необязательно): Фильтр по MX получателя; используется с recipient_mx_operator (ci_contain и т.д.)
• category (необязательно): Фильтр по категории письма; используется с category_operator: equal, not_equal

Все параметры необязательны.

get-email-log-message

Получает одно сообщение из журнала писем по ID (UUID): читаемое резюме (от, кому, тема, время отправки, статус, категория, поток, вовлечённость, контекст доставки), затем подробную историю событий. При необходимости, с помощью include_content: true вы также можете загрузить и показать тело сообщения (HTML и обычный текст), когда Mailtrap предоставляет URL исходного сообщения.

Параметры:

• message_id (обязательно): UUID сообщения из журнала писем (из ответа об отправке или list-email-logs). Используйте list-email-logs для поиска ID сообщений.
• include_content (необязательно): Когда установлен true, загружает исходный EML (если доступен raw_message_url) и добавляет разобранные секции HTML и обычного текста, аналогично show-sandbox-email-message.

get-sending-stats

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

Параметры:

• start_date (обязательно): Начальная дата диапазона статистики (ГГГГ-ММ-ДД)
• end_date (обязательно): Конечная дата диапазона статистики (ГГГГ-ММ-ДД)
• breakdown (необязательно): Как разбить статистику: aggregated (по умолчанию), by_domain, by_category, by_email_service_provider или by_date
• sending_domain_ids (необязательно): Ограничить результаты этими ID доменов отправки (массив целых чисел)
• sending_streams (необязательно): Ограничить по transactional и/или bulk (массив строк)
• categories (необязательно): Ограничить этими категориями писем (массив строк)
• email_service_providers (необязательно): Ограничить этими провайдерами, например Google, Yahoo, Outlook (массив строк)

create-template

Создаёт новый шаблон письма в вашем аккаунте Mailtrap.

Параметры:

• name (обязательно): Название шаблона
• subject (обязательно): Тема письма
• html (или text обязательно): HTML-содержимое шаблона
• text (или html обязательно): Версия шаблона в виде обычного текста
• category (необязательно): Категория шаблона (по умолчанию "General")

list-templates

Выводит список всех шаблонов писем в вашем аккаунте Mailtrap.

Параметры:

• Параметры не требуются

get-template

Получает один шаблон письма по ID, включая тему, категорию и HTML/текстовое содержимое.

Параметры:

• template_id (обязательно): ID шаблона для получения

update-template

Обновляет существующий шаблон письма.

Параметры:

• template_id (обязательно): ID шаблона для обновления
• name (необязательно): Новое название шаблона
• subject (необязательно): Новая тема письма
• html (необязательно): Новое HTML-содержимое шаблона
• text (необязательно): Новая версия шаблона в виде обычного текста
• category (необязательно): Новая категория шаблона

[!NOTE] При вызове update-template для выполнения обновления необходимо указать хотя бы одно обновляемое поле (name, subject, html, text или category).

delete-template

Удаляет существующий шаблон письма.

Параметры:

• template_id (обязательно): ID шаблона для удаления

send-sandbox-email

Отправляет письмо в ваш тестовый inbox Mailtrap для целей разработки и тестирования. Это идеально подходит для тестирования шаблонов писем без отправки реальным получателям. Поддерживает те же два режима, что и send-email — встроенное содержимое или на основе шаблона (template_uuid).

Параметры:

• test_inbox_id (необязательно): ID тестового inbox Mailtrap. Обязателен, если не задан MAILTRAP_TEST_INBOX_ID; передавайте при каждом вызове для указания конкретного inbox.
• from (необязательно): Отправитель в виде { email, name? } (простая строка с email также принимается во время выполнения). Если не указано, используется DEFAULT_FROM_EMAIL.
• to (необязательно): Массив получателей в виде объектов { email, name? } (простые строки с email в массиве или строка с email, разделёнными запятыми, также принимаются во время выполнения). Необязательно, если указаны cc или bcc; по крайней мере одно из полей to / cc / bcc должно содержать получателя.
• cc (необязательно): Массив получателей копии (CC) в виде объектов { email, name? } (простые строки с email также принимаются во время выполнения).
• bcc (необязательно): Массив получателей скрытой копии (BCC) в виде объектов { email, name? } (простые строки с email также принимаются во время выполнения).
• subject (условно): Тема письма. Обязательна для встроенной отправки; должна быть опущена, когда задан template_uuid.
• text (условно): Текст письма. Обязателен (вместе с html или вместо него) для встроенной отправки; должен быть опущен, когда задан template_uuid.
• html (условно): HTML-версия тела письма. Обязательна (вместе с text или вместо него) для встроенной отправки; должна быть опущена, когда задан template_uuid.
• category (необязательно): Категория письма для отслеживания. Должна быть опущена, когда задан template_uuid.
• template_uuid (необязательно): Использовать шаблон письма Mailtrap вместо встроенного содержимого. Когда задан, subject / text / html / category должны быть опущены.
• template_variables (необязательно): Объект переменных, подставляемых в шаблон, на который ссылается template_uuid. Разрешён только вместе с template_uuid.

batch-send-sandbox-email

Отправляет пакет писем в ваш тестовый inbox Mailtrap одним вызовом API, без доставки реальным получателям. Та же структура base + requests[], правила валидации и правила встроенного/шаблонного режима, что и в batch-send-transactional-email — отличие в том, что этот инструмент направляет вызов через sandbox-эндпоинт для одного тестового inbox.

Параметры:

• sandbox_id (необязательно): ID sandbox (тестового inbox) Mailtrap. Обязателен, если не задан MAILTRAP_SANDBOX_ID; передавайте при каждом вызове для указания конкретного sandbox.
• base (необязательно), requests (обязательно): См. batch-send-transactional-email выше.

[!NOTE] Для sandbox-инструментов укажите test_inbox_id в вызове инструмента или задайте переменную окружения MAILTRAP_TEST_INBOX_ID. Вы можете переключаться между inbox при каждом вызове, передавая test_inbox_id. Инструменты, принимающие sandbox_id, сначала используют MAILTRAP_SANDBOX_ID.

get-sandbox-messages

Получает список сообщений из вашего тестового inbox Mailtrap. Полезно для проверки, какие письма были получены в вашем sandbox во время тестирования.

Параметры:

• page (необязательно): Номер страницы для пагинации (минимум: 1)
• last_id (необязательно): Пагинация с использованием ID последнего сообщения. Возвращает сообщения после указанного ID сообщения (минимум: 1)
• search (необязательно): Поисковый запрос для фильтрации сообщений

[!NOTE] Все параметры необязательны. Если ни один не указан, будет возвращена первая страница сообщений из inbox. Используйте page для традиционной пагинации, last_id для курсорной пагинации или search для фильтрации сообщений по содержимому.

show-sandbox-email-message

Показывает подробную информацию и содержимое конкретного письма из вашего тестового inbox Mailtrap, включая HTML и текстовое содержимое.

Параметры:

• message_id (обязательно): ID сообщения sandbox для получения

[!NOTE] Сначала используйте get-sandbox-messages, чтобы получить список сообщений и их ID, затем используйте этот инструмент для просмотра полного содержимого конкретного сообщения.

get-sandbox-project

Получает sandbox-проект по ID, включая его inbox и количество писем.

Параметры:

• project_id (обязательно): ID проекта для получения

update-sandbox-project

Переименовывает существующий sandbox-проект.

Параметры:

• project_id (обязательно): ID проекта для обновления
• name (обязательно): Новое название проекта (2–100 символов)

list-sandboxes

Выводит список всех sandbox, доступных для API-токена, во всех проектах.

Параметры:

• Параметры не требуются

mark-sandbox-as-read

Помечает все сообщения в sandbox как прочитанные.

Параметры:

• sandbox_id (обязательно): ID sandbox для выполнения действия

reset-sandbox-credentials

Reset the SMTP credentials for a sandbox. Returns the new username/password.

Parameters:

• sandbox_id (required): ID of the sandbox to act on

enable-sandbox-email-address

Enable the receive-by-email address for a sandbox (turns on the Mailtrap address that delivers messages to the sandbox via SMTP).

Parameters:

• sandbox_id (required): ID of the sandbox to act on

reset-sandbox-email-address

Generate a new receive-by-email address for a sandbox.

Parameters:

• sandbox_id (required): ID of the sandbox to act on

forward-sandbox-message

Forward a sandbox message to an external email address. Counts against your monthly forwarding quota.

Parameters:

• sandbox_id (optional): Sandbox ID. Falls back to MAILTRAP_SANDBOX_ID.
• message_id (required): ID of the sandbox message to forward
• email (required): Email address to forward the message to

update-sandbox-message

Mark a sandbox message as read or unread.

Parameters:

• sandbox_id (optional): Sandbox ID. Falls back to MAILTRAP_SANDBOX_ID.
• message_id (required): ID of the sandbox message to update
• is_read (required): true marks as read, false marks as unread

delete-sandbox-message

Delete a single sandbox message.

Parameters:

• sandbox_id (optional): Sandbox ID. Falls back to MAILTRAP_SANDBOX_ID.
• message_id (required): ID of the sandbox message to delete

get-sandbox-message-spam-score

Get the SpamAssassin spam report for a sandbox message (score, rules, full report). Standalone alternative to include_spam_report: true on show-sandbox-email-message.

Parameters:

• sandbox_id (optional): Sandbox ID. Falls back to MAILTRAP_SANDBOX_ID.
• message_id (required): ID of the sandbox message

get-sandbox-message-html-analysis

Get the HTML analysis report for a sandbox message (client compatibility scores, problematic elements). Standalone alternative to include_html_analysis: true on show-sandbox-email-message.

Parameters:

• sandbox_id (optional): Sandbox ID. Falls back to MAILTRAP_SANDBOX_ID.
• message_id (required): ID of the sandbox message

get-sandbox-message-headers

Get the parsed mail headers for a sandbox message.

Parameters:

• sandbox_id (optional): Sandbox ID. Falls back to MAILTRAP_SANDBOX_ID.
• message_id (required): ID of the sandbox message

get-sandbox-message-html

Get the rendered HTML body of a sandbox message.

Parameters:

• sandbox_id (optional): Sandbox ID. Falls back to MAILTRAP_SANDBOX_ID.
• message_id (required): ID of the sandbox message

get-sandbox-message-text

Get the plain-text body of a sandbox message.

Parameters:

• sandbox_id (optional): Sandbox ID. Falls back to MAILTRAP_SANDBOX_ID.
• message_id (required): ID of the sandbox message

get-sandbox-message-raw

Get the raw, MIME-formatted message (headers + body) for a sandbox message.

Parameters:

• sandbox_id (optional): Sandbox ID. Falls back to MAILTRAP_SANDBOX_ID.
• message_id (required): ID of the sandbox message

get-sandbox-message-eml

Get the message rendered as an EML file payload (suitable for attaching to a ticket or importing into another mail client).

Parameters:

• sandbox_id (optional): Sandbox ID. Falls back to MAILTRAP_SANDBOX_ID.
• message_id (required): ID of the sandbox message

get-sandbox-message-html-source

Get the unrendered HTML source of a sandbox message (HTML before any Mailtrap-side transformations like CID-link rewrites).

Parameters:

• sandbox_id (optional): Sandbox ID. Falls back to MAILTRAP_SANDBOX_ID.
• message_id (required): ID of the sandbox message

list-sandbox-attachments

List all attachments on a sandbox message (filename, content type, size, download path).

Parameters:

• sandbox_id (optional): Sandbox ID. Falls back to MAILTRAP_SANDBOX_ID.
• message_id (required): ID of the sandbox message

get-sandbox-attachment

Get metadata and download URL for a single attachment.

Parameters:

• sandbox_id (optional): Sandbox ID. Falls back to MAILTRAP_SANDBOX_ID.
• message_id (required): ID of the sandbox message that contains the attachment
• attachment_id (required): ID of the attachment to fetch

list-sending-domains

List sending domains and their DNS verification status.

Parameters:

• No parameters required

get-sending-domain

Get a sending domain by ID and its verification status (including DNS records). Optionally include DNS setup instructions by setting include_setup_instructions to true.

Parameters:

• sending_domain_id (required): Sending domain ID
• include_setup_instructions (optional): If true, append DNS setup instructions to the response. Default: false

create-sending-domain

Create a new sending domain. After creation, add DNS records to verify the domain (use get-sending-domain with include_setup_instructions: true to see the records).

Parameters:

• domain_name (required): Domain name (e.g. example.com)

update-sending-domain

Update a sending domain's tracking and inbound settings.

Parameters:

• sending_domain_id (required): Sending domain ID
• open_tracking_enabled (optional): Track opens on emails sent from this domain
• click_tracking_enabled (optional): Track clicks on links in emails sent from this domain
• tracking_opt_out_enabled (optional): Add the tracking opt-out link to tracked emails. Requires open or click tracking
• auto_unsubscribe_link_enabled (optional): Automatically add an unsubscribe link to emails
• inbound_enabled (optional): Allow the domain to be attached to an inbound inbox as a catch-all

At least one setting besides sending_domain_id must be provided.

delete-sending-domain

Delete a sending domain.

Parameters:

• sending_domain_id (required): Sending domain ID to delete

send-sending-domain-setup-instructions

Email DNS setup instructions for a sending domain to a given address. Useful for forwarding DNS records to a DevOps teammate.

Parameters:

• sending_domain_id (required): Sending domain ID
• email (required): Email address to send DNS setup instructions to

get-company-info

Get the company info of a sending domain, used for domain compliance verification.

Parameters:

• sending_domain_id (required): Sending domain ID

create-company-info

Set the company info of a sending domain, required for domain compliance verification.

Parameters:

• sending_domain_id (required): Sending domain ID
• name (required): Company or individual name
• address (required): Street address
• city (required): City
• country (required): Country
• zip_code (required): ZIP or postal code
• website_url (required): Company website URL
• phone (optional): Phone number
• privacy_policy_url (optional): URL of the privacy policy page
• terms_of_service_url (optional): URL of the terms of service page
• info_level (optional): business or individual

update-company-info

Update the company info of a sending domain.

Parameters:

• sending_domain_id (required): Sending domain ID
• Every field of create-company-info, all optional. At least one must be provided; fields left out are unchanged.

list-suppressions

List or search suppressions (hard bounces, spam complaints, unsubscriptions, manual imports). Returns up to 1000 results per call.

Parameters:

• email (optional): Email filter. Returns only suppressions matching this address.

create-suppression

Add an email address to the account's suppression list, so Mailtrap stops delivering to it.

Parameters:

• email (required): Email address to suppress
• domain_id (required): ID of the sending domain the suppression applies to
• sending_stream (required): transactional or bulk
• type (optional): hard bounce, spam complaint, unsubscription or manual import. Defaults to manual import

delete-suppression

Delete a suppression by ID. Mailtrap will resume delivery to this email unless it gets suppressed again.

Parameters:

• suppression_id (required): ID of the suppression to delete

list-tracking-opt-outs

List email addresses excluded from open and click tracking. Returns up to 1000 records per call.

Parameters:

• email (optional): Email filter. Returns only opt-outs matching this address
• start_time (optional): Only opt-outs created at or after this time (ISO 8601)
• end_time (optional): Only opt-outs created at or before this time (ISO 8601)
• last_id (optional): Pagination cursor — the last_id from the previous response

create-tracking-opt-out

Exclude an email address from open and click tracking for a sending domain.

Parameters:

• email (required): Email address to opt out of tracking
• domain_id (required): ID of the sending domain the opt-out applies to

delete-tracking-opt-out

Remove an email address from the tracking opt-out list, so open and click tracking applies to it again.

Parameters:

• tracking_opt_out_id (required): ID of the tracking opt-out to delete

list-webhooks

List all webhooks configured for the account. Returns the full webhook records as JSON.

Parameters:

• No parameters required

get-webhook

Get a single webhook by ID. Returns the full webhook record as JSON. Note: signing_secret is not returned here — it is only available in the response from create-webhook.

Parameters:

• webhook_id (required): ID of the webhook to fetch

create-webhook

Create a webhook. The response includes a signing_secret for verifying webhook payload signatures — this secret is returned only on creation, so store it now. If you lose it, recreate the webhook.

Parameters:

• url (required): URL Mailtrap will POST webhook events to
• webhook_type (required): "email_sending", "audit_log", or "inbound_receiving"
• active (optional, boolean): defaults to true
• payload_format (optional): "json" or "jsonlines". Defaults to "json"
• sending_stream (optional, email_sending only): "transactional" or "bulk"
• event_types (optional, email_sending only): array of delivery, soft_bounce, bounce, suspension, unsubscribe, open, spam_complaint, click, reject
• domain_id (optional, email_sending only): sending domain ID to scope this webhook to
• inbound_inbox_id (optional, inbound_receiving only): ID of the inbound inbox the webhook is linked to; omit to apply to all inboxes in the account

update-webhook

Update a webhook's mutable fields. webhook_type, sending_stream, and domain_id cannot be changed after creation — recreate the webhook if you need to change those.

Parameters:

• webhook_id (required): ID of the webhook to update
• url (optional): New webhook URL
• active (optional, boolean): Enable or disable the webhook
• payload_format (optional): "json" or "jsonlines"
• event_types (optional, email_sending only): array of delivery, soft_bounce, bounce, suspension, unsubscribe, open, spam_complaint, click, reject
• inbound_inbox_id (optional, inbound_receiving only): ID of the inbound inbox the webhook is linked to

delete-webhook

Permanently delete a webhook by ID. Returns the deleted webhook record.

Parameters:

• webhook_id (required): ID of the webhook to delete

get-contact

Получить контакт по ID или email. Возвращает полную запись контакта (членство в списках, статус, пользовательские поля).

Параметры:

• contact_identifier (обязательно): ID контакта или email-адрес

create-contact

Создать новый контакт.

Параметры:

• email (обязательно): Email-адрес
• fields (необязательно): Значения пользовательских полей, ключ — merge-тег (например, first_name). Значения: строка, число или логическое значение
• list_ids (необязательно): ID списков контактов для подписки этого контакта
• unsubscribed (необязательно, логическое): Создать контакт в статусе unsubscribed

update-contact

Обновить существующий контакт, найденный по ID или email. list_ids заменяет полный набор членств контакта; list_ids_included/list_ids_excluded добавляют/удаляют, не затрагивая остальное.

Параметры:

• contact_identifier (обязательно): ID контакта или email
• email (необязательно): Новый email-адрес
• fields (необязательно): Значения пользовательских полей, ключ — merge-тег
• list_ids (необязательно): Заменить набор членств на этот точный список
• list_ids_included (необязательно): ID списков для добавления (аддитивно)
• list_ids_excluded (необязательно): ID списков для удаления
• unsubscribed (необязательно, логическое): Установить в unsubscribed (true) или subscribed (false)

delete-contact

Безвозвратно удалить контакт по ID или email. Возвращает запись удалённого контакта, если API отвечает с ней; в противном случае возвращает подтверждающий ответ.

Параметры:

• contact_identifier (обязательно): ID контакта или email

create-contact-event

Записать событие контакта для контакта (по ID или email). Используется для запуска автоматизаций на основе списков контактов.

Параметры:

• contact_identifier (обязательно): ID контакта или email
• name (обязательно): Название события (соответствует триггерам автоматизаций)
• params (обязательно): Объект произвольных пар ключ/значение. Значения могут быть строкой, числом, логическим значением или null

list-contact-lists

Список всех списков контактов для аккаунта.

Параметры:

• search (необязательно): Фильтр списков контактов по имени (без учёта регистра), например, news

get-contact-list

Получить список контактов по ID.

Параметры:

• list_id (обязательно): ID списка контактов для получения

create-contact-list

Создать новый список контактов.

Параметры:

• name (обязательно): Название нового списка

update-contact-list

Переименовать существующий список контактов.

Параметры:

• list_id (обязательно): ID списка контактов
• name (обязательно): Новое название списка

delete-contact-list

Безвозвратно удалить список контактов по ID.

Параметры:

• list_id (обязательно): ID списка контактов для удаления

list-contact-fields

Список всех определений полей контактов для аккаунта.

Параметры:

• Параметры не требуются

get-contact-field

Получить определение поля контакта по ID.

Параметры:

• field_id (обязательно): ID поля контакта

create-contact-field

Создать новое определение поля контакта. merge_tag должен быть уникальным в пределах аккаунта и используется как имя плейсхолдера в переменных шаблона.

Параметры:

• name (обязательно): Отображаемое имя (например, "Имя")
• merge_tag (обязательно): Уникальное имя плейсхолдера (например, first_name)
• data_type (обязательно): Одно из text, number, boolean, date

update-contact-field

Обновить определение поля контакта. Можно изменить любую комбинацию name, merge_tag и data_type.

Параметры:

• field_id (обязательно): ID поля контакта
• name (необязательно): Новое отображаемое имя
• merge_tag (необязательно): Новый merge-тег (должен оставаться уникальным)
• data_type (необязательно): Одно из text, number, boolean, date

delete-contact-field

Безвозвратно удалить определение поля контакта по ID.

Параметры:

• field_id (обязательно): ID поля контакта для удаления

create-contact-import

Массовый импорт контактов. Возвращает запись задания импорта; проверяйте его статус с помощью get-contact-import.

Параметры:

• contacts (обязательно): Массив записей контактов. Каждая запись требует:
  • email (обязательно): Email-адрес контакта
  • fields (необязательно): Значения пользовательских полей, ключ — merge-тег (значения: строка или число)
  • list_ids_included (необязательно): ID списков для добавления контакта
  • list_ids_excluded (необязательно): ID списков для удаления контакта

get-contact-import

Получить статус задания импорта контактов (created/started/finished/failed) с количеством созданных/обновлённых/превысивших лимит.

Параметры:

• import_id (обязательно): ID задания импорта контактов

create-contact-export

Экспорт контактов, соответствующих набору фильтров, объединённых по И. Возвращает запись задания экспорта; проверяйте статус с помощью get-contact-export, чтобы получить URL загрузки, когда status станет finished.

Параметры:

• filters (обязательно): Массив объектов фильтров. Каждый имеет:
  • name (обязательно): Поле для фильтрации (list_id, subscription_status, email и т.д.)
  • operator (обязательно): Одно из equal, not_equal, contains, not_contains, is_empty, is_not_empty
  • value (обязательно): Значение для сравнения (строка, число, логическое значение или массив)

get-contact-export

Получить статус задания экспорта контактов. Когда status станет finished, поле url будет содержать ссылку для загрузки CSV.

Параметры:

• export_id (обязательно): ID задания экспорта контактов

list-email-campaigns

Список email-кампаний аккаунта, сначала новые, с постраничной навигацией по токенам страниц. Опционально фильтровать по имени с помощью search.

Параметры:

• token (необязательно): Номер страницы для получения (постраничная навигация по токенам). По умолчанию 1
• per_page (необязательно): Количество кампаний на странице. По умолчанию 50, максимум 100
• search (необязательно): Фильтр кампаний по имени (частичное совпадение без учёта регистра)

get-email-campaign

Получить email-кампанию по ID.

Параметры:

• email_campaign_id (обязательно): ID email-кампании

create-email-campaign

Создать новую email-кампанию. Кампания всегда создаётся в состоянии draft; планирование и запуск — отдельные инструменты (schedule-email-campaign, start-email-campaign).

Параметры:

• name (обязательно): Название кампании
• domain_id (обязательно): ID проверенного домена отправки, используемого для кампании, как возвращается конечными точками Sending Domains
• from_local_part (обязательно): Локальная часть (до @) адреса From
• template_attributes (обязательно): Встроенный email-шаблон. Имеет:
  • subject (обязательно): Тема письма (макс. 255 символов). Поддерживает merge-теги, например, Hi {{first_name}}
  • body_html (необязательно): HTML-тело (дизайн). Требуется перед планированием или запуском кампании. Включите ссылку отписки через якорь, чей href содержит плейсхолдер __unsubscribe_url__
  • body_text (необязательно): Альтернативная версия тела письма в виде простого текста
  • merge_tags (необязательно): Простые имена merge-тегов, на которые ссылаются в теме/теле, например, ["first_name"]
• from_display_name (необязательно): Отображаемое имя в заголовке From
• reply_to (необязательно): Части адреса Reply-To (display_name, local_part, domain)
• delivery_mode (необязательно): rapid (отправить как можно быстрее) или gradual (ограничить до delivery_options.emails_per_hour)
• delivery_options (необязательно): Параметры ограничения доставки (emails_per_hour)
• contact_list_ids (необязательно): ID списков контактов для отправки (рассматривается как полный набор включённых списков)
• contact_segment_ids (необязательно): ID сегментов контактов для отправки (рассматривается как полный набор включённых сегментов)

update-email-campaign

Обновить email-кампанию в состоянии draft. Изменяются только предоставленные поля; шаблон редактируется на месте. Кампании в любом другом состоянии обновить нельзя.

Параметры:

• email_campaign_id (обязательно): ID email-кампании для обновления
• Все остальные параметры необязательны и идентичны create-email-campaign (name, domain_id, from_local_part, from_display_name, reply_to, template_attributes, delivery_mode, delivery_options, contact_list_ids, contact_segment_ids)

delete-email-campaign

Удалить email-кампанию по ID. Можно удалить только кампанию в состоянии draft.

Параметры:

• email_campaign_id (обязательно): ID email-кампании для удаления

start-email-campaign

Начать отправку email-кампании в состоянии draft немедленно. Можно запустить только кампании в состоянии draft; шаблон должен иметь дизайн body_html, а аудитория и проверенный домен отправки должны быть заданы.

Параметры:

• email_campaign_id (обязательно): ID email-кампании для запуска

schedule-email-campaign

Запланировать email-кампанию в состоянии draft для начала отправки в будущее время. Можно запланировать только кампании в состоянии draft.

Параметры:

• email_campaign_id (обязательно): ID email-кампании для планирования
• datetime (обязательно): Когда отправить кампанию (ISO 8601). Должно быть в будущем и не более чем на 1 месяц вперёд

cancel-email-campaign

Отменить email-кампанию в состоянии scheduled, вернув её в draft. Можно отменить только кампании в состоянии scheduled.

Параметры:

• email_campaign_id (обязательно): ID email-кампании для отмены

terminate-email-campaign

Прекратить email-кампанию, которая в настоящее время отправляется (started, queued или paused), прерывая текущую отправку.

Параметры:

• email_campaign_id (обязательно): ID email-кампании для прекращения

reset-email-campaign

Сбросить email-кампанию в состоянии scheduled обратно в draft. Можно сбросить только кампании в состоянии scheduled.

Параметры:

• email_campaign_id (обязательно): ID email-кампании для сброса

get-email-campaign-stats

Получить агрегированную статистику производительности для email-кампании (количество и показатели доставок, открытий, кликов, отказов, жалоб на спам и отписок).

Параметры:

• email_campaign_id (обязательно): ID email-кампании
• start_date (необязательно): Начало окна агрегации (включительно), YYYY-MM-DD. По умолчанию — день последнего запуска кампании
• end_date (необязательно): Конец окна агрегации (включительно), YYYY-MM-DD. По умолчанию — текущая дата

list-accounts

Список аккаунтов Mailtrap, к которым имеет доступ текущий API-токен, с уровнями доступа каждого аккаунта.

Параметры:

• Параметры не требуются

get-billing-usage

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

Параметры:

• Параметры не требуются

list-account-accesses

Список доступов к аккаунту (пользователи, приглашения, API-токены) для аккаунта. Необязательные фильтры сужают результат до конкретных ресурсов. Требует прав администратора/владельца аккаунта.

Параметры:

• domain_uuids (необязательно): Фильтр по UUID доменов отправки (массив строк)
• inbox_ids (необязательно): Фильтр по ID песочниц-инбоксов (массив строк)
• project_ids (необязательно): Фильтр по ID песочниц-проектов (массив строк)

remove-account-access

Удалить доступ к аккаунту по ID. Для спецификаторов User это отзывает их права; для спецификаторов Invite или ApiToken это полностью удаляет спецификатор. Требует прав администратора/владельца.

Параметры:

• account_access_id (обязательно): ID записи доступа для удаления

get-permission-resources

Получить все ресурсы (инбоксы, проекты, домены, биллинг, аккаунт), к которым API-токен имеет административный доступ, сгруппированные по иерархии.

Параметры:

• Параметры не требуются

bulk-update-permissions

Массовое создание, обновление или удаление разрешений для одного доступа к аккаунту. Существующие пары (resource_type, resource_id) обновляются; новые создаются. Установите destroy: true в записи, чтобы удалить её.

Параметры:

• account_access_id (обязательно): ID целевого доступа к аккаунту
• permissions (обязательно): Массив записей разрешений. Каждая запись содержит:
  • resource_id (обязательно): ID ресурса (число или строка)
  • resource_type (обязательно): Одно из значений: account, project, inbox, domain, billing
  • access_level (необязательно): admin/100 или viewer/10
  • destroy (необязательно, логическое): Если true, удаляет это разрешение вместо создания/обновления

list-api-tokens

Список всех API-токенов для аккаунта.

Параметры:

• Параметры не требуются

create-api-token

Создание нового API-токена. Ответ включает секретное значение token — это единственный момент, когда возвращается полный токен, поэтому сохраните его немедленно. Если вы его потеряете, создайте токен заново.

Параметры:

• name (обязательно): Отображаемое имя для токена
• expires_at (необязательно): Срок действия токена в формате ISO 8601. Опустите для значения по умолчанию (1 год); передайте явное null для токена, который никогда не истекает. Прошедшие значения или значения более чем на 5 лет вперед отклоняются
• resources (необязательно): Массив разрешений на ресурсы для ограничения токена. Каждая запись содержит:
  • resource_type (обязательно): Одно из значений: account, project, inbox, domain, billing
  • resource_id (обязательно): ID ресурса
  • access_level (обязательно): 100 (администратор) или 10 (просмотрщик)

get-api-token

Получение API-токена по ID. Возвращает только метаданные — секретное значение токена не возвращается здесь (только из create-api-token / reset-api-token).

Параметры:

• api_token_id (обязательно): ID API-токена

reset-api-token

Сброс (ротация) API-токена по ID. Ответ включает новое секретное значение token — возвращается только при этом вызове, поэтому сохраните его немедленно. Предыдущий токен становится недействительным.

Параметры:

• api_token_id (обязательно): ID API-токена для сброса
• expires_at (необязательно): Срок действия нового токена в формате ISO 8601. Опустите для значения по умолчанию (1 год); передайте явное null для токена, который никогда не истекает. Прошедшие значения или значения более чем на 5 лет вперед отклоняются

delete-api-token

Безвозвратное удаление API-токена по ID. После удаления токен больше не может использоваться для аутентификации.

Параметры:

• api_token_id (обязательно): ID API-токена для удаления

list-sub-accounts

Список суб-аккаунтов в организации. Требует переменную окружения MAILTRAP_ORGANIZATION_ID и права управления суб-аккаунтами.

Параметры:

• Параметры не требуются

create-sub-account

Создание нового суб-аккаунта в организации. Требует переменную окружения MAILTRAP_ORGANIZATION_ID и права управления суб-аккаунтами.

Параметры:

• name (обязательно): Отображаемое имя для нового суб-аккаунта

list-inbound-folders

Список всех входящих папок в аккаунте. Возвращает форматированную сводку.

Параметры:

• Параметры не требуются

get-inbound-folder

Получение одной входящей папки по ID. Возвращает полную запись папки в формате JSON.

Параметры:

• folder_id (обязательно): ID входящей папки

create-inbound-folder

Создание новой входящей папки.

Параметры:

• name (обязательно): Имя папки

update-inbound-folder

Переименование входящей папки.

Параметры:

• folder_id (обязательно): ID входящей папки
• name (обязательно): Новое имя папки

delete-inbound-folder

Безвозвратное удаление входящей папки вместе со всеми её почтовыми ящиками.

Параметры:

• folder_id (обязательно): ID входящей папки

list-inbound-inboxes

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

Параметры:

• folder_id (обязательно): ID входящей папки

get-inbound-inbox

Получение одного входящего почтового ящика по ID. Возвращает полную запись почтового ящика в формате JSON.

Параметры:

• folder_id (обязательно): ID входящей папки
• inbox_id (обязательно): ID почтового ящика

create-inbound-inbox

Создание нового входящего почтового ящика в папке.

Параметры:

• folder_id (обязательно): ID входящей папки
• name (обязательно): Имя почтового ящика
• domain_id (необязательно): Привязка к пользовательскому домену отправки (catch-all почтовый ящик). Опустите для почтового ящика, размещённого на Mailtrap

update-inbound-inbox

Переименование входящего почтового ящика.

Параметры:

• folder_id (обязательно): ID входящей папки
• inbox_id (обязательно): ID почтового ящика
• name (обязательно): Новое имя почтового ящика

delete-inbound-inbox

Безвозвратное удаление входящего почтового ящика.

Параметры:

• folder_id (обязательно): ID входящей папки
• inbox_id (обязательно): ID почтового ящика

list-inbound-messages

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

Параметры:

• inbox_id (обязательно): ID почтового ящика
• last_id (необязательно): Курсор пагинации из предыдущего ответа last_id

get-inbound-message

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

Параметры:

• inbox_id (обязательно): ID почтового ящика
• message_id (обязательно): ID сообщения

delete-inbound-message

Безвозвратное удаление входящего сообщения.

Параметры:

• inbox_id (обязательно): ID почтового ящика
• message_id (обязательно): ID сообщения

reply-to-inbound-message

Ответ на входящее сообщение (отправляется исходному отправителю). Отправляет реальное письмо. Адреса принимают строку с email или { email, name? }.

Параметры:

• inbox_id (обязательно): ID почтового ящика
• message_id (обязательно): ID сообщения для ответа
• text / html (рекомендуется хотя бы одно): Тело ответа
• from (необязательно): Отправитель. Отклоняется для почтовых ящиков, размещённых на Mailtrap; обязателен для почтовых ящиков с пользовательским доменом
• cc / bcc / reply_to (необязательно): Дополнительные адреса
• category (необязательно): Категория сообщения
• attachments (необязательно): Массив { content (base64), filename, type?, disposition?, content_id? }
• headers / custom_variables (необязательно): Объекты со строковыми значениями

reply-all-to-inbound-message

Ответ на входящее сообщение с копированием других получателей исходного письма. Отправляет реальное письмо. Те же параметры, что и у reply-to-inbound-message.

Параметры:

• inbox_id (обязательно): ID почтового ящика
• message_id (обязательно): ID сообщения для ответа
• Плюс те же необязательные поля отправки, что и у reply-to-inbound-message

forward-inbound-message

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

Параметры:

• inbox_id (обязательно): ID почтового ящика
• message_id (обязательно): ID сообщения для пересылки
• to (обязательно): Как минимум один получатель (строка с email или { email, name? }, или массив)
• Плюс те же необязательные поля отправки, что и у reply-to-inbound-message

list-inbound-threads

Список цепочек переписки во входящем почтовом ящике (с курсорной пагинацией). Возвращает форматированную сводку с подсказкой о следующей странице, когда есть дополнительные результаты.

Параметры:

• inbox_id (обязательно): ID почтового ящика
• last_id (необязательно): Курсор пагинации из предыдущего ответа last_id

get-inbound-thread

Получение одной входящей цепочки с встроенными сообщениями (сначала старые). Возвращает полную запись цепочки в формате JSON.

Параметры:

• inbox_id (обязательно): ID почтового ящика
• thread_id (обязательно): ID цепочки

delete-inbound-thread

Безвозвратное удаление входящей цепочки.

Параметры:

• inbox_id (обязательно): ID почтового ящика
• thread_id (обязательно): ID цепочки

Разработка

1. Клонируйте репозиторий:

git clone https://github.com/mailtrap/mailtrap-mcp.git
cd mailtrap-mcp

2. Установите зависимости:

npm install

Настройка с Claude Desktop или Cursor

[!TIP] См. расположение файла конфигурации в разделе Setup.

Добавьте следующую конфигурацию:

{
  "mcpServers": {
    "mailtrap": {
      "command": "node",
      "args": ["/path/to/mailtrap-mcp/dist/index.js"],
      "env": {
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "your_sender@example.com",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

Если вы используете asdf для управления Node.js, используйте абсолютный путь к исполняемому файлу:

(пример для Mac)

{
  "mcpServers": {
    "mailtrap": {
      "command": "/Users/<username>/.asdf/shims/node",
      "args": ["/path/to/mailtrap-mcp/dist/index.js"],
      "env": {
        "PATH": "/Users/<username>/.asdf/shims:/usr/bin:/bin",
        "ASDF_DIR": "/opt/homebrew/opt/asdf/libexec",
        "ASDF_DATA_DIR": "/Users/<username>/.asdf",
        "ASDF_NODEJS_VERSION": "20.6.1",
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "your_sender@example.com",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

VS Code

[!TIP] См. расположение файла конфигурации в разделе Setup.

{
  "mcp": {
    "servers": {
      "mailtrap": {
        "command": "node",
        "args": ["/path/to/mailtrap-mcp/dist/index.js"],
        "env": {
          "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
          "DEFAULT_FROM_EMAIL": "your_sender@example.com",
          "MAILTRAP_ACCOUNT_ID": "your_account_id",
          "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
        }
      }
    }
  }
}

Тестирование

Запуск инструментов против реального Mailtrap

Есть два способа проверить инструмент end-to-end против реального аккаунта Mailtrap: браузерный интерфейс MCP Inspector для интерактивного исследования или его CLI-режим для разовых вызовов из оболочки.

Оба требуют предварительной сборки бандла:

npm run build

и экспорта MAILTRAP_API_TOKEN + MAILTRAP_ACCOUNT_ID в вашей оболочке (скрипт mcp:cli передаёт оба значения запущенному серверу).

Браузерный интерфейс

npm run dev

Inspector выводит URL вида http://localhost:6274. Откройте его, переключитесь на вкладку Tools, выберите инструмент (например, get-template), заполните параметры в JSON и нажмите Run. Ответ Mailtrap появится на панели ниже.

CLI

Для разовых вызовов без интерфейса используйте npm run mcp:cli. Передавайте флаги CLI Inspector после --, чтобы npm пересылал их без изменений:

# List all tools
npm run mcp:cli -- --method tools/list

# Call a tool — flags after the `--`
npm run mcp:cli -- \
  --method tools/call \
  --tool-name get-template \
  --tool-arg template_id=12345

# Multiple --tool-arg flags for tools with several params
npm run mcp:cli -- \
  --method tools/call \
  --tool-name send-sending-domain-setup-instructions \
  --tool-arg sending_domain_id=3938 \
  --tool-arg email=devops@example.com

Запуск сервера MCPB

# Run the MCPB server directly
node dist/mcpb-server.js

# Or use the provided binary
mailtrap-mcpb-server

[!TIP] Для разработки с MCP Inspector:

npm run dev:mcpb

Обработка ошибок

Этот сервер использует структурированную обработку ошибок в соответствии с соглашениями MCP:

• VALIDATION_ERROR: Ошибки валидации входных данных
• CONFIGURATION_ERROR: Отсутствующая или недействительная конфигурация
• EXECUTION_ERROR: Ошибки выполнения во время работы
• TIMEOUT: Таймаут операции (по умолчанию 30 секунд)

Ошибки содержат полезные сообщения и регистрируются в структурированном виде.

Безопасность

• Входные данные валидируются через схемы Zod
• Переменные окружения обрабатываются безопасно
• Защита от таймаутов операций (30 секунд)
• Конфиденциальные данные очищаются в выводе ошибок

Логирование

Структурированные JSON-логи с уровнями: INFO, WARN, ERROR, DEBUG.

Включите отладочное логирование, установив DEBUG=true.

# Example: enable debug logging
DEBUG=true node dist/mcpb-server.js

Важно: Сервер записывает логи в stderr, чтобы stdout оставался зарезервированным для JSON-RPC кадров. Это предотвращает ошибки парсинга JSON у хостов из-за перемешанных логов.

Пример анализа логов с использованием jq:

# Filter error logs
node dist/mcpb-server.js 2>&1 | jq 'select(.level == "error")'

# Filter debug logs
node dist/mcpb-server.js 2>&1 | jq 'select(.level == "debug")'

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

Частые проблемы:

1. Отсутствует API-токен: убедитесь, что MAILTRAP_API_TOKEN установлен
2. Sandbox не работает: укажите test_inbox_id в вызове инструмента или установите переменную окружения MAILTRAP_TEST_INBOX_ID
3. Ошибки таймаута: проверьте сетевое подключение и статус API Mailtrap
4. Ошибки валидации: убедитесь, что все обязательные поля заполнены

Вклад в проект

Отчёты об ошибках и pull request приветствуются на GitHub. Этот проект задуман как безопасное и гостеприимное пространство для сотрудничества, и участники обязаны соблюдать кодекс поведения.

Лицензия

Пакет доступен как open source на условиях лицензии MIT.

Кодекс поведения

Все, кто взаимодействует с кодовыми базами проекта Mailtrap, трекерами задач, чатами и списками рассылки, обязаны следовать кодексу поведения.