Интерфейс командной строки (CLI)

mailexam-cli — официальная утилита командной строки для REST API Mailexam^®. Подходит для локальной отладки, QA и CI/CD: не нужно писать скрипты на Python или Node.js и копировать длинные curl-цепочки.

Типичный сценарий: приложение отправляет письмо по SMTP, а в pipeline одна команда ждёт доставку и проверяет содержимое:

mailexam email assert --subject "Проверка CI" --contains "Привет"

Когда использовать CLI

• CI/CD — команды wait и assert с понятными exit codes.
• Быстрая проверка — список проектов, ящиков и писем из терминала.
• REST API напрямую — если нужна полная гибкость (создание проектов, кастомная логика), см. REST API и Swagger UI.

Установка

go installСборка из исходниковПроверка

Требуется Go 1.22+:

go install github.com/mailexam/mailexam-cli/cmd/mailexam@latest

Бинарник появится в $GOPATH/bin или $HOME/go/bin. Убедитесь, что каталог в PATH.

git clone https://github.com/mailexam/mailexam-cli.git
cd mailexam-cli
go build -o mailexam ./cmd/mailexam
sudo mv mailexam /usr/local/bin/   # опционально

mailexam version
mailexam --help

Настройка

API-токен берётся в личном кабинете. Это не SMTP-пароль: токен только для REST API (см. REST API — авторизация).

Переменная	Описание
MAILEXAM_API_TOKEN	API-токен (обязательно)
MAILEXAM_API_BASE	Базовый URL (по умолчанию https://mailexam.ru/api/v1)
MAILEXAM_PROJECT_UUID	UUID проекта по умолчанию
MAILEXAM_INBOX_UUID	UUID ящика по умолчанию

Те же значения можно передать флагами: --token, --base, --project, --inbox.

Региональные домены

Регион	MAILEXAM_API_BASE
Россия	https://mailexam.ru/api/v1
Китай	https://mailexam.cn/api/v1
Международный	https://mailexam.io/api/v1

Пример для локальной работы:

export MAILEXAM_API_TOKEN="ваш_токен"
export MAILEXAM_PROJECT_UUID="536a47df-5aad-44d0-8163-a39bb55abe0b"
export MAILEXAM_API_BASE="https://mailexam.ru/api/v1"

Секреты в CI/CD

Не храните токен в репозитории. Добавьте MAILEXAM_API_TOKEN в секреты GitLab CI, GitHub Actions или другого pipeline.

Сценарий в CI/CD

sequenceDiagram
    participant App as Приложение
    participant SMTP as SMTP Mailexam
    participant CLI as mailexam CLI
    participant API as REST API

    App->>SMTP: sendMail()
    Note over SMTP: Письмо в sandbox
    CLI->>API: polling GET /email
    API-->>CLI: письмо найдено
    CLI->>CLI: assert subject, body
    Note over CLI: exit 0 или 1

1. Приложение отправляет письмо через SMTP (см. примеры интеграции).
2. В pipeline вызывается mailexam email wait или mailexam email assert.
3. CLI опрашивает API каждые 2 секунды (по умолчанию) до таймаута.

Справочник команд

Глобальные флаги доступны для всех команд: --token, --base, --project, --inbox.

Проекты

Команда	Описание
mailexam project list	Список проектов
mailexam project get UUID	Информация о проекте

Флаг --json выводит ответ API в формате JSON.

mailexam project list
mailexam project list --json
mailexam project get 536a47df-5aad-44d0-8163-a39bb55abe0b

UUID проекта можно узнать через project list или в личном кабинете.

Почтовые ящики

Команда	Описание
mailexam inbox list	Список ящиков (нужен --project или MAILEXAM_PROJECT_UUID)
mailexam inbox get UUID	Информация о ящике

mailexam inbox list --project $MAILEXAM_PROJECT_UUID
mailexam inbox get deab7974-a252-4412-9169-b965116b63cf

Письма

Команда	Описание
mailexam email list	Список писем в ящике
mailexam email get UUID	Полное письмо
mailexam email wait	Ждать письмо по фильтру
mailexam email assert	Ждать и проверить содержимое
mailexam email delete UUID	Удалить письмо

Для email list, wait и assert достаточно MAILEXAM_PROJECT_UUID: CLI возьмёт ящик по умолчанию или первый в списке. Ящик можно указать явно через --inbox или MAILEXAM_INBOX_UUID.

Список и просмотр

mailexam email list
mailexam email list --json

mailexam email get e2f9a506-d766-4935-be11-c413384de020
mailexam email get e2f9a506-d766-4935-be11-c413384de020 --format text
mailexam email get e2f9a506-d766-4935-be11-c413384de020 --format html
mailexam email get e2f9a506-d766-4935-be11-c413384de020 --format uuid

Форматы --format: json (по умолчанию), text, html, raw, uuid.

Ожидание письма (wait)

Обязателен хотя бы один фильтр: --subject, --to или --from.

mailexam email wait --subject "Проверка CI"
mailexam email wait --subject "Проверка CI" --subject-exact
mailexam email wait --to "user@example.com" --timeout 60 --interval 3
mailexam email wait --subject "Код" --format text

Флаг	По умолчанию	Описание
--subject	—	Подстрока в теме
--subject-exact	false	Точное совпадение темы
--to	—	Подстрока в поле «Кому»
--from	—	Подстрока в поле «От»
--timeout	30	Таймаут в секундах
--interval	2	Интервал опроса в секундах
--format	json	Формат вывода найденного письма

Проверка в тестах (assert)

Главная команда для pipeline: при успехе печатает OK и завершается с кодом 0.

mailexam email assert --subject "Проверка CI" --contains "Привет"
mailexam email assert --subject "Код" --contains "123456" --contains "действителен"
mailexam email assert --subject "Отчёт" --matches 'total:\s+\d+'
mailexam email assert --subject "Файл" --require-attachments
mailexam email assert --subject "Файл" --attachment-count 2

Флаг	Описание
--contains	Текст должен встречаться в теле (можно указать несколько раз)
--matches	Тело должно соответствовать регулярному выражению
--require-attachments	У письма должны быть вложения
--attachment-count	Точное число вложений

Проверка тела идёт по текстовой части; если её нет — по HTML.

Вложения

mailexam email get EMAIL_UUID --format json   # узнать cid вложений
mailexam email attachment download EMAIL_UUID --cid ATTACHMENT_CID -o report.pdf
mailexam email attachment download EMAIL_UUID --cid ATTACHMENT_CID -o -  # в stdout

Примеры для CI/CD

GitLab CI

integration_test:
  stage: test
  image: golang:1.22
  variables:
    MAILEXAM_API_BASE: "https://mailexam.ru/api/v1"
    MAILEXAM_PROJECT_UUID: "536a47df-5aad-44d0-8163-a39bb55abe0b"
  before_script:
    - go install github.com/mailexam/mailexam-cli/cmd/mailexam@latest
  script:
    - npm run send-test-email
    - mailexam email assert --subject "Проверка CI" --contains "Привет"
  # MAILEXAM_API_TOKEN — в CI/CD Variables (masked)

GitHub Actions

- name: Install mailexam CLI
  run: go install github.com/mailexam/mailexam-cli/cmd/mailexam@latest

- name: Send test email
  run: npm run send-test-email

- name: Assert email delivered
  env:
    MAILEXAM_API_TOKEN: ${{ secrets.MAILEXAM_API_TOKEN }}
    MAILEXAM_API_BASE: https://mailexam.ru/api/v1
    MAILEXAM_PROJECT_UUID: 536a47df-5aad-44d0-8163-a39bb55abe0b
  run: mailexam email assert --subject "Проверка CI" --contains "Привет"

SMTP-логин и пароль (MAILEXAM_LOGIN, MAILEXAM_PASSWORD) используются приложением для отправки; API-токен — только для CLI.

Коды завершения

Код	Значение
0	Успех
1	Ошибка или проверка assert не прошла
2	Ошибка авторизации (HTTP 403)
3	Таймаут ожидания письма

В GitLab CI и GitHub Actions pipeline падает при любом ненулевом коде — дополнительная обёртка не нужна.

Типичные проблемы

api token is required

• Задайте MAILEXAM_API_TOKEN или флаг --token.

Exit code 2 (403)

• Токен скопирован не полностью или принадлежит другому аккаунту. См. REST API — типичные проблемы.

Exit code 3 (timeout)

• Письмо ещё не дошло — увеличьте --timeout.
• Письмо попало в другой проект — сверьте SMTP-логин с MAILEXAM_PROJECT_UUID.
• Тема не совпадает — проверьте точное значение или уберите --subject-exact.

project or inbox is required

• Укажите MAILEXAM_PROJECT_UUID или --project. Для явного ящика — --inbox.

См. также

• Исходный код mailexam-cli на GitHub
• REST API
• Swagger UI
• Примеры интеграции SMTP
• Переход с Mailtrap
• Поддержка: support@mailexam.ru