Ktor + Mailexam

Минимальный пример Ktor, который отправляет тестовое письмо через SMTP Mailexam с помощью Jakarta Mail.

Основан на руководстве Mailexam для Ktor.

Что понадобится

• Аккаунт Mailexam и проект с SMTP-учётными данными.
• JDK 17+ и Gradle (wrapper включён).

Из приветственного письма или личного кабинета Mailexam:

Переменная	Описание
MAILEXAM_LOGIN	SMTP-логин (например, xxxxx)
MAILEXAM_PASSWORD	SMTP-пароль (пара к логину)
Хост	{MAILEXAM_LOGIN}.mailexam.ru (собирается в Mail.kt)

Быстрый старт (на хосте)

1. Экспортируйте учётные данные Mailexam (или скопируйте из примера):

cp .env.example .env
export $(grep -v '^#' .env | xargs)

2. Отредактируйте .env:

MAILEXAM_LOGIN=ВАШ_ЛОГИН
MAILEXAM_PASSWORD=ВАШ_ПАРОЛЬ
MAILEXAM_PORT=587
MAIL_FROM=noreply@example.test

3. Запустите сервер:

./gradlew run

Сервер слушает http://127.0.0.1:8080 по умолчанию.

4. Отправьте тестовое письмо:

curl -X POST http://127.0.0.1:8080/mail/test \
  -H 'Content-Type: application/json' \
  -d '{"to":"user@example.test","subject":"Тест","body":"Привет"}'

Письмо появится в личном кабинете Mailexam → ваш проект → входящие.

Переменные окружения

Переменная	Обязательна	По умолчанию	Описание
MAILEXAM_LOGIN	да	—	SMTP-логин; также используется для имени хоста
MAILEXAM_PASSWORD	да	—	SMTP-пароль
MAILEXAM_PORT	нет	587	SMTP-порт (587, 2525 или 25)
MAIL_FROM	нет	noreply@example.test	Адрес отправителя (любой тестовый адрес)
HTTP_HOST	нет	127.0.0.1	Адрес привязки HTTP
HTTP_PORT	нет	8080	Порт HTTP

Для портов 587 и 2525 включён STARTTLS (mail.smtp.starttls.enable=true). Для порта 25 — отключён.

Структура проекта

.
├── build.gradle.kts
├── src/main/kotlin/Mail.kt
├── src/main/kotlin/Application.kt   # POST /mail/test
├── .env.example
├── Dockerfile                       # только для локальной отладки
└── docker-compose.yml

Docker (отладка)

Docker предназначен для локальной отладки. Для повседневной разработки запускайте приложение на хосте через ./gradlew run (см. выше).

cp .env.example .env
# отредактируйте .env с учётными данными Mailexam

docker compose up --build

Затем вызовите тот же endpoint на проброшенном порту:

curl -X POST http://127.0.0.1:8080/mail/test \
  -H 'Content-Type: application/json' \
  -d '{"to":"user@example.test","subject":"Тест","body":"Привет"}'

Внутри контейнера сервер слушает 0.0.0.0:8080.

CI

Задайте эти секреты в окружении CI:

variables:
  MAILEXAM_LOGIN: $MAILEXAM_LOGIN
  MAILEXAM_PASSWORD: $MAILEXAM_PASSWORD
  MAILEXAM_PORT: "587"
  MAIL_FROM: "noreply@example.test"

После отправки письма в тесте проверьте доставку через API Mailexam.

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

Ошибка TLS или подключения

• Хост должен быть {login}.mailexam.ru, где {login} совпадает с MAILEXAM_LOGIN.
• Логин и пароль должны быть из одного проекта Mailexam.

Блокировка event loop

• Transport.send выполняется внутри withContext(Dispatchers.IO).

Письмо не в кабинете

• Откройте входящие того же проекта Mailexam.
• Проверьте логи Ktor, когда Mail.sendTest выбрасывает исключение.

См. также

• Руководство Mailexam для Ktor (wiki)
• Пример на Spring Boot — другой JVM-фреймворк с Jakarta Mail
• Пример на Quarkus — cloud-native JVM-фреймворк с quarkus-mailer
• Документация Ktor
• Документация API Mailexam

Лицензия

Apache 2.0