Skip to content

Ktor

Guide for applications built with Ktor (Kotlin, JVM). Mailexam connects as an SMTP server via Jakarta Mail.

What you need

  • A Mailexam account and a project with SMTP credentials.
  • JDK 17+ and Kotlin 1.9+.

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

Fragment of build.gradle.kts:

plugins {
    kotlin("jvm") version "2.0.0"
    kotlin("plugin.serialization") version "2.0.0"
    application
}

repositories {
    mavenCentral()
}

dependencies {
    implementation("io.ktor:ktor-server-core-jvm:3.0.0")
    implementation("io.ktor:ktor-server-netty-jvm:3.0.0")
    implementation("io.ktor:ktor-server-content-negotiation-jvm:3.0.0")
    implementation("io.ktor:ktor-serialization-kotlinx-json-jvm:3.0.0")
    implementation("com.sun.mail:jakarta.mail:2.0.1")
}

application {
    mainClass.set("ApplicationKt")
}

Create a project via the Ktor Project Generator or manually using the structure below.

2. Environment variables

Set variables before launch (or use .env via your IDE):

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

SMTP host: YOUR_LOGIN.mailexam.io.

Sender address

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

Alternative ports

MAILEXAM_PORT=587

mail.smtp.starttls.enable=true

MAILEXAM_PORT=2525

MAILEXAM_PORT=25

mail.smtp.starttls.enable=false

3. Sending mail

// src/main/kotlin/Mail.kt
import jakarta.mail.Authenticator
import jakarta.mail.Message
import jakarta.mail.PasswordAuthentication
import jakarta.mail.Session
import jakarta.mail.Transport
import jakarta.mail.internet.InternetAddress
import jakarta.mail.internet.MimeMessage
import java.util.Properties

object Mail {
    fun sendTest(to: String, subject: String, body: String) {
        val login = System.getenv("MAILEXAM_LOGIN")
            ?: error("MAILEXAM_LOGIN is not set")
        val password = System.getenv("MAILEXAM_PASSWORD")
            ?: error("MAILEXAM_PASSWORD is not set")
        val port = System.getenv("MAILEXAM_PORT")?.toInt() ?: 587
        val from = System.getenv("MAIL_FROM") ?: "noreply@example.test"

        val props = Properties().apply {
            put("mail.smtp.host", "$login.mailexam.io")
            put("mail.smtp.port", port.toString())
            put("mail.smtp.auth", "true")
            put("mail.smtp.starttls.enable", (port == 587 || port == 2525).toString())
        }

        val session = Session.getInstance(props, object : Authenticator() {
            override fun getPasswordAuthentication(): PasswordAuthentication =
                PasswordAuthentication(login, password)
        })

        val message = MimeMessage(session).apply {
            setFrom(InternetAddress(from))
            setRecipients(Message.RecipientType.TO, InternetAddress.parse(to))
            setSubject(subject, "UTF-8")
            setText(body, "UTF-8")
        }

        Transport.send(message)
    }
}

4. Ktor route

// src/main/kotlin/Application.kt
import io.ktor.serialization.kotlinx.json.*
import io.ktor.server.application.*
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.plugins.contentnegotiation.*
import io.ktor.server.request.*
import io.ktor.server.response.*
import io.ktor.server.routing.*
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext
import kotlinx.serialization.Serializable

@Serializable
data class SendRequest(
    val to: String = "user@example.test",
    val subject: String = "Ktor + Mailexam",
    val body: String = "Mailexam test from Ktor",
)

fun main() {
    embeddedServer(Netty, port = 8080, host = "127.0.0.1", module = Application::module)
        .start(wait = true)
}

fun Application.module() {
    install(ContentNegotiation) {
        json()
    }

    routing {
        post("/mail/test") {
            val payload = call.receive<SendRequest>()

            withContext(Dispatchers.IO) {
                Mail.sendTest(
                    to = payload.to,
                    subject = payload.subject,
                    body = payload.body,
                )
            }

            call.respond(mapOf("status" to "ok"))
        }
    }
}

Start and verify:

./gradlew run

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.

5. Local development and CI

Environment Recommendation
local environment variables in IDE Run Configuration
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.

6. Common issues

TLS or connection error

  • mail.smtp.host must be {login}.mailexam.io, login in PasswordAuthentication — from the email.
  • Login and password are a pair from the email for one project.

Event loop blocking

  • Call Transport.send inside withContext(Dispatchers.IO), as in the example.

Message not in the dashboard

  • View the inbox of the same Mailexam project.
  • Check Ktor logs when an exception is thrown from Mail.sendTest.

See also