Get Started with Kotlinmailer

Prerequisites

Before starting this tutorial, you should have the following prerequisites:

The latest Gradle distribution.
A Java Development Kit, version 8 or later.
An integrated development environment (IDE) such as IntelliJ IDEA or Visual Studio Code.

Create a new project

First, you will need a basic Kotlin project setup to build upon. You can download a preinitialized project or follow the steps below to generate a new project with Gradle.

In a terminal window, navigate to the destination where you want to create your project and run the following commands to create a new folder and change directory into it:
mkdir kotlinmailer-app cd kotlinmailer-app
Run the gradle init task to initialize a new Gradle project:
gradle init
When prompted, select the following options:
- 1: Application project type.
- 2: Kotlin implementation language.
For the other questions, press enter to use the default values. The output will look like the following:
Select type of build to generate: 1: Application 2: Library 3: Gradle plugin 4: Basic (build structure only) Enter selection (default: Application) [1..4] Select implementation language: 1: Java 2: Kotlin 3: Groovy 4: Scala 5: C++ 6: Swift Enter selection (default: Java) [1..6] 2 Enter target Java version (min: 7, default: 21): Project name (default: exposed-kotlin-app): Select application structure: 1: Single application project 2: Application and library project Enter selection (default: Single application project) [1..2] Select build script DSL: 1: Kotlin 2: Groovy Enter selection (default: Kotlin) [1..2] Select test framework: 1: kotlin.test 2: JUnit Jupiter Enter selection (default: kotlin.test) [1..2] Generate build using new APIs and behavior (some features may change in the next minor release)? (default: no) [yes, no] > Task :init To learn more about Gradle by exploring our Samples at https://docs.gradle.org/8.8/samples/sample_building_kotlin_applications.html BUILD SUCCESSFUL in 28s 1 actionable task: 1 executed
Once the project has been initialized, open the project folder in your IDE. To open the project, use the following command:
idea .
code .

Add dependencies

Before you start using Kotlinmailer, you need to provide dependencies to your project.

Navigate to the gradle/libs.versions.toml file and define the Kotlinmailer version and libraries:
[versions] //... kotlinmailer = "1.1.21" [libraries] //... kotlinmailer-core = { module = "at.quickme.kotlinmailer", name = "core", version.ref = "kotlinmailer" }
- The core module provides the foundational components and abstractions needed to work with databases in a type-safe manner and includes the DSL API.
- The html module provides the HTML DSL API to create emails with kotlinx.html.
Navigate to the app/build.gradle.kts file and add the Exposed and H2 database modules into the dependencies block:
dependencies { //... implementation(libs.kotlinmailer.core) // Optional implementation(libs.kotlinmailer.html) //... }
Last but not least, load the Gradle changes in your IDE:
In IntelliJ IDEA, click the notification Gradle icon () on the right side of the editor to load Gradle changes.
In Visual Studio Code, open the terminal and execute:
./gradlew
This is documentation is based on this stack overflow post and has not been tested by the Kotlinmailer team.

Configure an SMTP Server

For Kotlinmailer to send emails, you need to configure an SMTP server connection.

Navigate to app/src/main/kotlin/org/example/ and open the App.kt file.
Replace the contents of the App.kt file with the following implementation:
package org.example import at.quickme.kotlinmailer.delivery.mailerBuilder fun main() { val mailer = mailerBuilder( host = "smtp.example.com", port = 25, username = "john.doe@example.com", password = "secure-password" ) }
Remember to replace the SMTP server values with your actual SMTP server connection details.
The mailerBuilder() function creates an instance of a class that represents the SMTP server connection.
Note that invoking mailerBuilder() only configures the connection settings, but it doesn't immediately establish a connection with the SMTP server. The actual connection will be established later when an email is sent.
With this, you've added Kotlinmailer to your Kotlin project and configured a SMTP server connection. You're now ready to send your first email.

Send a simple text email

Let us add the app’s functionality by sending an email.

In the same App.kt file, add the following code to your implementation:
package org.example import at.quickme.kotlinmailer.delivery.mailerBuilder fun main() { val mailer = mailerBuilder( host = "smtp.example.com", port = 25, username = "john.doe@example.com", password = "secure-password" ) val sender = InternetAddress("John Doe <john.doe@example.com>") emailBuilder { from(sender) to("alice.doe@exmaple.com") withSubject("Let's get married 💍") withPlainText("My dear Alice, I love you! Will you marry me?") }.send(mailer) }
Remember to replace the recipient email addresses with an actual email address, so that you confirm that the email has been sent.
Here's the breakdown:
The InternetAddress() function creates an instance of the InternetAddress class, which represents the sender's email identity. The first part `John Doe` is the sender's name, and the second part consists of the sender's email address.
val sender = InternetAddress("John Doe <john.doe@example.com>")
Spoofing the sender's email using this may be blocked by some SMTP servers. To avoid this, be sure to use an email address assigned to your SMTP user account.
The emailBuilder function creates an instance of the Email class, which represents the email to be sent. The emailBuilder function is a DSL function that allows you to build an email using a set of functions. As you can see, we set parameters such as recipient, subject and body text for the email.
emailBuilder { from(sender) to("alice.doe@exmaple.com") withSubject("Let's get married 💍") withPlainText("My dear Alice, I love you! Will you marry me?") }
The send() function finalises the process and sends the email using the previously configured SMTP connection.
You should now see in the recipents email inbox that your email with the subject "Let's get married 💍" has been successfully sent.

Next steps

Great job! You've now implemented a simple console application that uses Kotlinmailer to send simple text emails. Now that you’ve covered the basics, you're ready to explore what else you can do with Kotlinmailer.