MailKTEmail for Kotlin, done carefully.

Coroutine-first IMAP and SMTP with hosted OAuth2 for Gmail and Outlook. Read, watch and send mail from your backend with explicit lifecycles, typed failures and no hidden persistence.

Get started

Quick start

GitHub

⏻

One lifecycle handle

Each account is a Mailbox with a StateFlow of its state, generation-safe automatic reconnects and an idempotent close().

Mailbox lifecycle

✉

Envelope-first reading

Filter on cheap metadata, inspect the MIME structure, then download only the parts you need. Rejected mail costs no content download.

Reading mail

↻

Live watching with catch-up

IMAP IDLE watchers resume from a checkpoint after restarts and reconnects and deliver at-least-once.

Watching

⇄

Conversations by real relations

Threads are built from Message-ID, In-Reply-To and References, merged across folders, never guessed from subjects.

Conversations

✓

Explicit send outcomes

ACCEPTED, FAILED or UNKNOWN. Submissions are never retried behind your back, not even across reconnects.

Sending

🔑

Hosted OAuth2, your storage

Gmail and Microsoft 365 authorization-code flows with PKCE. Tokens and checkpoints cross small interfaces you implement.

Authorization

A taste

kotlin

gmail.open(MailAddress("alice@gmail.com")).use { mailbox ->
    val inbox = checkNotNull(mailbox.folders.special(SpecialUse.INBOX)).path

    mailbox.messages.watchEnvelopes(inbox, MessageQuery(seen = false)).collect { watched ->
        val structure = mailbox.messages.structure(watched.envelope.location)
        structure.attachments.filter { it.isPdf }.forEach { part ->
            val pdf = mailbox.messages.download(part.ref, maxBytes = 10L * 1024 * 1024)
            store(pdf.content.toByteArray())
        }
        saveCheckpoint(watched.next) // only after your processing is durable
    }
}