Kotlin
Kotlin integration examples for Keplers Mail Service
Send emails using Kotlin with Keplers Mail Service REST API.
Installation
Add to your build.gradle.kts:
dependencies {
implementation("com.squareup.okhttp3:okhttp:4.12.0")
implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.0")
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3")
}Basic Setup
# .env
KEPLERS_API_KEY=kms_your_api_key.live_...REST API Integration
Basic Client
import kotlinx.coroutines.*
import kotlinx.serialization.*
import kotlinx.serialization.json.*
import okhttp3.*
import okhttp3.MediaType.Companion.toMediaType
import okhttp3.RequestBody.Companion.toRequestBody
@Serializable
data class EmailRequest(
val to: List<String>,
val subject: String,
val body: String,
@SerialName("is_html") val isHtml: Boolean = false
)
@Serializable
data class EmailResponse(
val success: Boolean,
val data: JsonElement,
val message: String? = null
)
class KeplersEmailClient(
private val apiKey: String,
private val baseUrl: String = "https://api.keplars.com"
) {
private val client = OkHttpClient()
private val json = Json { ignoreUnknownKeys = true }
suspend fun sendEmail(emailData: EmailRequest): Result<EmailResponse> {
return makeRequest("/api/v1/send-email/queue", emailData)
}
suspend fun sendInstantEmail(emailData: EmailRequest): Result<EmailResponse> {
return makeRequest("/api/v1/send-email/instant", emailData)
}
private suspend fun makeRequest(endpoint: String, emailData: EmailRequest): Result<EmailResponse> =
withContext(Dispatchers.IO) {
try {
val requestBody = json.encodeToString(emailData)
.toRequestBody("application/json".toMediaType())
val request = Request.Builder()
.url("$baseUrl$endpoint")
.post(requestBody)
.addHeader("Authorization", "Bearer $apiKey")
.addHeader("Content-Type", "application/json")
.build()
val response = client.newCall(request).execute()
if (response.isSuccessful) {
val responseBody = response.body?.string() ?: ""
val emailResponse = json.decodeFromString<EmailResponse>(responseBody)
Result.success(emailResponse)
} else {
Result.failure(Exception("HTTP ${response.code}: ${response.message}"))
}
} catch (e: Exception) {
Result.failure(e)
}
}
}Usage Examples
fun main() = runBlocking {
val client = KeplersEmailClient(System.getenv("KEPLERS_API_KEY") ?: "")
sendWelcomeEmail(client, "[email protected]", "John")
sendVerificationEmail(client, "[email protected]", "123456")
}
suspend fun sendWelcomeEmail(client: KeplersEmailClient, userEmail: String, userName: String) {
val emailData = EmailRequest(
to = listOf(userEmail),
subject = "Welcome $userName!",
body = "<h1>Welcome $userName!</h1><p>Thank you for joining our platform.</p>",
isHtml = true
)
client.sendEmail(emailData).fold(
onSuccess = { response ->
println("Email sent: $response")
},
onFailure = { error ->
println("Failed to send email: ${error.message}")
}
)
}
suspend fun sendVerificationEmail(client: KeplersEmailClient, userEmail: String, code: String) {
val emailData = EmailRequest(
to = listOf(userEmail),
subject = "Verify Your Email",
body = "Your verification code: $code",
isHtml = false
)
client.sendInstantEmail(emailData).fold(
onSuccess = { response ->
println("Verification email sent: $response")
},
onFailure = { error ->
println("Failed to send verification email: ${error.message}")
}
)
}Android Integration
class EmailService(private val context: Context) {
private val client = KeplersEmailClient(BuildConfig.KEPLERS_API_KEY)
suspend fun sendWelcomeEmail(email: String, name: String): Boolean {
val emailData = EmailRequest(
to = listOf(email),
subject = "Welcome $name!",
body = "<h1>Welcome $name!</h1>",
isHtml = true
)
return client.sendEmail(emailData).isSuccess
}
}
class AuthViewModel(private val emailService: EmailService) : ViewModel() {
fun sendWelcomeEmail(email: String, name: String) {
viewModelScope.launch {
try {
val success = emailService.sendWelcomeEmail(email, name)
// Handle success/failure
} catch (e: Exception) {
// Handle error
}
}
}
}Spring Boot Integration
@RestController
@RequestMapping("/api/emails")
class EmailController(private val emailService: EmailService) {
@PostMapping("/send")
suspend fun sendEmail(@RequestBody request: SendEmailRequest): ResponseEntity<ApiResponse> {
return try {
val success = emailService.sendWelcomeEmail(request.email, request.name)
if (success) {
ResponseEntity.ok(ApiResponse(true, "Email sent successfully"))
} else {
ResponseEntity.status(500).body(ApiResponse(false, "Failed to send email"))
}
} catch (e: Exception) {
ResponseEntity.status(500).body(ApiResponse(false, "Error: ${e.message}"))
}
}
}
data class SendEmailRequest(val email: String, val name: String)
data class ApiResponse(val success: Boolean, val message: String)
@Service
class EmailService {
private val client = KeplersEmailClient(System.getenv("KEPLERS_API_KEY") ?: "")
suspend fun sendWelcomeEmail(email: String, name: String): Boolean {
val emailData = EmailRequest(
to = listOf(email),
subject = "Welcome $name!",
body = "<h1>Welcome $name!</h1>",
isHtml = true
)
return client.sendEmail(emailData).isSuccess
}
}SMTP Integration
SMTP Installation
dependencies {
implementation("javax.mail:javax.mail-api:1.6.2")
implementation("com.sun.mail:javax.mail:1.6.2")
}SMTP Client
import kotlinx.coroutines.*
import java.util.*
import javax.mail.*
import javax.mail.internet.*
class KeplersEmailSMTPClient(
private val username: String,
private val password: String
) {
suspend fun sendEmail(emailData: EmailRequest): Result<Unit> = withContext(Dispatchers.IO) {
try {
val props = Properties().apply {
put("mail.smtp.host", "smtp.keplars.com")
put("mail.smtp.port", "587")
put("mail.smtp.auth", "true")
put("mail.smtp.starttls.enable", "true")
}
val session = Session.getInstance(props, object : Authenticator() {
override fun getPasswordAuthentication(): PasswordAuthentication {
return PasswordAuthentication(username, password)
}
})
val message = MimeMessage(session).apply {
setFrom(InternetAddress("[email protected]"))
setRecipients(Message.RecipientType.TO, InternetAddress.parse(emailData.to.first()))
subject = emailData.subject
if (emailData.isHtml) {
setContent(emailData.body, "text/html; charset=utf-8")
} else {
setText(emailData.body)
}
}
Transport.send(message)
Result.success(Unit)
} catch (e: Exception) {
Result.failure(e)
}
}
}SMTP Usage
fun main() = runBlocking {
val smtpClient = KeplersEmailSMTPClient(
username = System.getenv("KEPLERS_SMTP_USERNAME") ?: "",
password = System.getenv("KEPLERS_SMTP_PASSWORD") ?: ""
)
sendEmailViaSMTP(smtpClient, "[email protected]", "Test Email", "<p>Hello World!</p>")
}
suspend fun sendEmailViaSMTP(
smtpClient: KeplersEmailSMTPClient,
userEmail: String,
subject: String,
body: String
) {
val emailData = EmailRequest(
to = listOf(userEmail),
subject = subject,
body = body,
isHtml = true
)
smtpClient.sendEmail(emailData).fold(
onSuccess = {
println("SMTP email sent successfully")
},
onFailure = { error ->
println("SMTP send failed: ${error.message}")
}
)
}Choose REST API for advanced features or SMTP for traditional email client integration.