Mailer API
A Mailer delivers emails. Kotlinmailer ships two implementations:
Mailer | Module | Protocol | Platforms |
|---|---|---|---|
|
| SMTP (RFC 5321) | JVM / Android, Node.js, macOS, iOS, Linux & Windows (no TLS) |
|
| JMAP (RFC 8620/21) | every Kotlin target with a Ktor client engine, incl. browsers |
Both implement the same interface, so the rest of your code does not care which one you use.
SMTP
Option | Default | Description |
|---|---|---|
|
|
|
| depends on security | The server port |
| none | Authenticate with |
| none | Authenticate with |
|
| The name sent with |
|
| Number of parallel connections |
|
| Keep connections open between emails |
|
| Fail if any recipient is rejected, otherwise deliver to the accepted ones |
|
| Allow sending credentials without TLS |
| 30 s, 5 min, 10 min | Timeouts as recommended by RFC 5321 |
The client supports the ESMTP extensions STARTTLS, AUTH, PIPELINING, SIZE, 8BITMIME, SMTPUTF8 and ENHANCEDSTATUSCODES. No connection is opened until the first email is sent; call mailer.testConnection() to check your configuration eagerly.
JMAP
JMAP is a modern HTTP based protocol supported by e.g. Fastmail and Stalwart. As it only needs HTTP, it also works in browsers.
If you only know the host, use JmapConfig.wellKnownSessionUrl("example.com").
The email is uploaded, imported into the Drafts mailbox and submitted, after which the server moves it to the Sent mailbox. The identity matching the From address is used; set identityId to choose a specific one.
In the browser
Browsers cannot open TCP connections, so SMTP is not available there, but JMAP works in Kotlin/JS and Kotlin/Wasm web apps. Add ktor-client-js and send as usual:
The JMAP server has to allow cross-origin (CORS) requests from your site; Fastmail does. Keep in mind that the credentials are visible to whoever uses the page, so only use tokens of the user that is signed in, never your own.
Send emails
send suspends until the server accepted the email and returns a SendReceipt.
Failures are thrown as MailException; for SMTP this is an SmtpException with the server's replyCode, enhancedStatusCode and isTransient, for JMAP a JmapException with the JMAP error type.
Default mailer
The default mailer is used if send() is called without a mailer.
Shut down
Close mailers to release their connections. smtpMailer and jmapMailer register their mailers at the MailerManager, so you can close all of them at once: