Перейти к содержанию

Quarkus

Инструкция для приложений на Quarkus 3.x (Java, JVM). Mailexam® подключается через расширение quarkus-mailer и API Mailer.

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

  • Аккаунт Mailexam® и проект с SMTP-учетными данными.
  • JDK 17+ и проект Quarkus (через code.quarkus.io или вручную).

Скопируйте из приветственного письма (или личного кабинета) для вашего проекта:

  • ВАШ_ЛОГИН — SMTP-логин (например, xxxxx);
  • ВАШ_ПАРОЛЬ — SMTP-пароль (уникальная пара к логину);
  • хост — ВАШ_ЛОГИН.mailexam.ru (совпадает с логином).

1. Зависимости

На code.quarkus.io выберите REST и Mailer, либо добавьте в build.gradle:

plugins {
    id 'java'
    id 'io.quarkus' version '3.20.1'
}

repositories {
    mavenCentral()
}

dependencies {
    implementation enforcedPlatform("${quarkusPlatformGroupId}:${quarkusPlatformArtifactId}:${quarkusPlatformVersion}")
    implementation 'io.quarkus:quarkus-rest'
    implementation 'io.quarkus:quarkus-mailer'
    implementation 'io.quarkus:quarkus-arc'
}

Добавьте в gradle.properties:

quarkusPlatformGroupId=io.quarkus.platform
quarkusPlatformArtifactId=quarkus-bom
quarkusPlatformVersion=3.20.1

Для Maven — те же расширения quarkus-rest и quarkus-mailer.

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

Файл .env для локальной разработки (не коммитьте пароли в git) или переменные в Run Configuration / CI:

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

SMTP-хост в конфигурации: ${MAILEXAM_LOGIN}.mailexam.ru.

Адрес отправителя

MAIL_FROM может быть любым тестовым адресом — письмо попадет в Mailexam®, а не реальному получателю.

Альтернативные порты

MAILEXAM_PORT=587

quarkus.mailer.start-tls=REQUIRED

MAILEXAM_PORT=2525

STARTTLS обязателен, как и для 587.

MAILEXAM_PORT=25

quarkus.mailer.start-tls=DISABLED

3. Конфигурация почты

src/main/resources/application.properties:

quarkus.http.host=${HTTP_HOST:127.0.0.1}
quarkus.http.port=${HTTP_PORT:8080}

mail.from=${MAIL_FROM:noreply@example.test}

quarkus.mailer.from=${mail.from}
quarkus.mailer.host=${MAILEXAM_LOGIN}.mailexam.ru
quarkus.mailer.port=${MAILEXAM_PORT:587}
quarkus.mailer.username=${MAILEXAM_LOGIN}
quarkus.mailer.password=${MAILEXAM_PASSWORD}
quarkus.mailer.start-tls=REQUIRED
quarkus.mailer.auth-methods=PLAIN

Для порта 25 переопределите quarkus.mailer.start-tls=DISABLED (см. таблицу выше).

4. Сервис отправки

package com.example.demo.mail;

import io.quarkus.mailer.Mail;
import io.quarkus.mailer.Mailer;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;
import org.eclipse.microprofile.config.inject.ConfigProperty;

@ApplicationScoped
public class MailService {

    private final Mailer mailer;
    private final String from;

    @Inject
    public MailService(Mailer mailer, @ConfigProperty(name = "mail.from") String from) {
        this.mailer = mailer;
        this.from = from;
    }

    public void sendTest(String to, String subject, String body) {
        mailer.send(Mail.withText(to, subject, body).setFrom(from));
    }
}

5. REST-эндпоинт

package com.example.demo.web;

import com.example.demo.mail.MailService;
import jakarta.inject.Inject;
import jakarta.ws.rs.Consumes;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;
import java.util.Map;

@Path("/mail")
public class MailController {

    @Inject
    MailService mailService;

    public record SendRequest(String to, String subject, String body) {
        public SendRequest {
            if (to == null || to.isBlank()) {
                to = "user@example.test";
            }
            if (subject == null || subject.isBlank()) {
                subject = "Quarkus + Mailexam";
            }
            if (body == null || body.isBlank()) {
                body = "Тест Mailexam из Quarkus";
            }
        }
    }

    @POST
    @Path("/test")
    @Consumes(MediaType.APPLICATION_JSON)
    @Produces(MediaType.APPLICATION_JSON)
    public Map<String, String> sendTest(SendRequest request) {
        mailService.sendTest(request.to(), request.subject(), request.body());
        return Map.of("status", "ok");
    }
}

Запуск и проверка:

./gradlew quarkusDev

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

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

6. Локальная разработка и CI

Среда Рекомендация
local переменные в IDE или .env + envfile plugin в Gradle
CI секреты MAILEXAM_LOGIN, MAILEXAM_PASSWORD в GitLab CI/CD Variables

Пример для .gitlab-ci.yml:

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

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

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

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

  • quarkus.mailer.host должен быть {логин}.mailexam.ru, username — тот же логин из письма.
  • Логин и пароль — пара из письма одного проекта.

Переменные не подставляются

  • Запускайте приложение с заданными MAILEXAM_LOGIN и MAILEXAM_PASSWORD; в IDE проверьте Environment в конфигурации Run.

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

  • Смотрите входящие того же проекта Mailexam®.
  • Включите логирование: quarkus.log.category."io.quarkus.mailer".level=DEBUG.

См. также