Kotlin / Java

Requires JVM 11+. Both Kotlin (suspend functions) and Java (CompletableFuture) APIs are supported.

Installation

Add the dependency

implementation("com.keplars:keplars-kotlin:1.10.5")

implementation 'com.keplars:keplars-kotlin:1.10.5'

<dependency>
  <groupId>com.keplars</groupId>
  <artifactId>keplars-kotlin</artifactId>
  <version>1.10.5</version>
</dependency>

Set your API key

KEPLARS_API_KEY=kms_your_workspace_id.live_your_secret

Send your first email

import com.keplars.KeplarsClient
import com.keplars.models.SendEmailRequest

val client = KeplarsClient.create(System.getenv("KEPLARS_API_KEY"))

val response = client.emails.sendInstant(
    SendEmailRequest(
        to      = "[email protected]",
        from    = "[email protected]",
        subject = "Hello!",
        body    = "<h1>It works!</h1>",
        isHtml  = true,
    )
)

println(response.id)

import com.keplars.KeplarsClient;
import com.keplars.models.SendEmailRequest;

KeplarsClient client = KeplarsClient.create(System.getenv("KEPLARS_API_KEY"));

SendEmailRequest request = new SendEmailRequest.Builder()
    .to("[email protected]")
    .from("[email protected]")
    .subject("Hello!")
    .body("<h1>It works!</h1>")
    .isHtml(true)
    .build();

client.emails().sendInstantAsync(request)
    .thenAccept(response -> System.out.println(response.getId()));

Priority Levels

Method	Delivery	Use case
`sendInstant`	0–5 seconds	OTP, 2FA, password reset
`sendHigh`	0–30 seconds	Transactional confirmations
`sendAsync` / `send`	0–5 minutes	Welcome emails, notifications
`sendBulk`	Background	Newsletters, campaigns

client.emails.sendInstant(request)
client.emails.sendHigh(request)
client.emails.sendAsync(request)
client.emails.sendBulk(request)

Using Templates

val response = client.emails.sendInstant(
    SendEmailRequest(
        to         = "[email protected]",
        from       = "[email protected]",
        templateId = "your-template-id",
        params     = mapOf(
            "user_name"         to "Jane",
            "verification_code" to "123456",
        ),
    )
)

Error Handling

import com.keplars.exceptions.AuthenticationException
import com.keplars.exceptions.RateLimitException

try {
    val response = client.emails.sendInstant(request)
} catch (e: AuthenticationException) {
    println("Invalid API key")
} catch (e: RateLimitException) {
    println("Rate limit hit, retry after: ${e.retryAfter}")
}

Admin API

Need to manage contacts, audiences, automations, or domains? Use an admin key - same client, different key suffix:

val client = KeplarsClient.create("kms_xxx.adm_xxx")

client.contacts.add(AddContactRequest(email = "[email protected]", name = "Jane"))
client.audiences.create(CreateAudienceRequest(name = "Newsletter"))
client.automations.enroll("auto_id", "[email protected]")
client.domains.verify("domain_id")

See the full Admin API reference.

Next Steps

Admin API - Contacts, audiences, automations, domains
Send Emails - API reference
Email Templates - Build reusable templates
Schedule Emails - Delayed delivery

Kotlin / Java

On this page