Quarkus¶

Guide for applications built with Quarkus 3.x (Java, JVM). Mailexam connects via the quarkus-mailer extension and the Mailer API.

What you need¶

A Mailexam account and a project with SMTP credentials.
JDK 17+ and a Quarkus project (via code.quarkus.io or manually).

Copy from the welcome email (or dashboard) for your project:

YOUR_LOGIN — SMTP login (for example, xxxxx);
YOUR_PASSWORD — SMTP password (a unique pair with the login);
host — YOUR_LOGIN.mailexam.io (matches the login).

1. Dependencies¶

On code.quarkus.io select REST and Mailer, or add to 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'
}

Add to gradle.properties:

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

For Maven — the same extensions quarkus-rest and quarkus-mailer.

2. Environment variables¶

.env file for local development (do not commit passwords to git) or variables in Run Configuration / CI:

MAILEXAM_LOGIN=YOUR_LOGIN
MAILEXAM_PASSWORD=YOUR_PASSWORD
MAILEXAM_PORT=587
MAIL_FROM=noreply@example.test

SMTP host in config: ${MAILEXAM_LOGIN}.mailexam.io.

Sender address

MAIL_FROM can be any test address — the message goes to Mailexam, not to a real recipient.

Alternative ports¶

587 + STARTTLS (recommended)252525 without TLS

MAILEXAM_PORT=587

quarkus.mailer.start-tls=REQUIRED

MAILEXAM_PORT=2525

STARTTLS required, same as for 587.

MAILEXAM_PORT=25

quarkus.mailer.start-tls=DISABLED

3. Mail configuration¶

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.io
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

For port 25 override quarkus.mailer.start-tls=DISABLED (see table above).

4. Sending service¶

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 endpoint¶

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 test from 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");
    }
}

Start and verify:

./gradlew quarkusDev

curl -X POST http://127.0.0.1:8080/mail/test \
  -H 'Content-Type: application/json' \
  -d '{"to":"user@example.test","subject":"Test","body":"Hello"}'

The message will appear in the Mailexam dashboard → your project → inbox.

6. Local development and CI¶

Environment	Recommendation
`local`	variables in IDE or `.env` + envfile plugin in Gradle
CI	secrets `MAILEXAM_LOGIN`, `MAILEXAM_PASSWORD` in GitLab CI/CD Variables

Example for .gitlab-ci.yml:

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

After an integration test, verify delivery via the Mailexam API.

7. Common issues¶

TLS or connection error

quarkus.mailer.host must be {login}.mailexam.io, username — the same login from the email.
Login and password are a pair from the email for one project.

Variables not substituted

Run the application with MAILEXAM_LOGIN and MAILEXAM_PASSWORD set; in the IDE check Environment in the Run configuration.

Message not in the dashboard

View the inbox of the same Mailexam project.
Enable logging: quarkus.log.category."io.quarkus.mailer".level=DEBUG.