Keplers Mail Service

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.

On this page