toyokumo / tarayo

:love_letter: SMTP client library for Clojure. That’s it.

tarayo

SMTP client library for Clojure. That’s it.

Table of Contents

• Why tarayo?
• Usage
  • Connection SMTP server
  • Sending mails
  • Use for Gmail API
• Stubbing
• License

Why tarayo?

Tarayo is heavily inspired by drewr/postal.

• Only targets SMTP

  • Provide only one feature.

  • Use drewr/postal for sendmail.

• Explicit connection

  • Handle the connection manually.

• Well tested

"Tarayo" is a tree name called "Tree of post office" in Japan.

Usage

(require '[tarayo.core :as tarayo])
;; => nil

Connection SMTP server

tarayo.core/connect is a function to connect SMTP server.
You need to call tarayo.core/close function before quitting, or use with-open macro.

(type (tarayo/connect {:host "localhost" :port 25}))
;; => tarayo.core.SMTPConnection

Other examples are follows:

SSL connection

(tarayo/connect {:host "localhost" :port 465 :ssl.enable true})

TLS connection

(tarayo/connect {:host "localhost" :port 587 :starttls.enable true})

Connection with user authentication

(tarayo/connect {:host "localhost" :port 25 :user "USERNAME" :password "PASSWORD"})

Sending mails

Text mail

(with-open [conn (tarayo/connect {:host "localhost" :port 25})]
  (tarayo/send! conn {:from "[email protected]"
                      :to "[email protected]"
                      :subject "hello"
                      :body "world"}))
;; => {:result :success, :code 250, :message "250 OK\n"}

HTML mail

(with-open [conn (tarayo/connect {:host "localhost" :port 25})]
  (tarayo/send! conn {:from "[email protected]"
                      :to "[email protected]"
                      :subject "hello"
                      :content-type "text/html"
                      :body "<h1>world</h1>"}))
;; => {:result :success, :code 250, :message "250 OK\n"}

Reply to

(with-open [conn (tarayo/connect {:host "localhost" :port 25})]
  (tarayo/send! conn {:from "[email protected]"
                      :to "[email protected]"
                      :reply-to "[email protected]"
                      :subject "hello"
                      :body "world"}))
;; => {:result :success, :code 250, :message "250 OK\n"}

Attachment file

(require '[clojure.java.io :as io])
;; => nil

(with-open [conn (tarayo/connect {:host "localhost" :port 25})]
  (tarayo/send! conn {:from "[email protected]"
                      :to "[email protected]"
                      :subject "hello"
                      ;; Default multipart type is "mixed"
                      :body [;; string content will be handled as "text message" while others are handled as "attachment file"
                             {:content "world"}
                             ;; If you don't specify `:content-type`, tarayo will detect it using Apache Tika automatically.
                             {:content (io/file "test/resources/file")}
                             ;; Of cource, you can specify `:content-type` manually.
                             {:content (io/file "test/resources/image.png") :content-type "image/png"}
                             ;; You could also use byte array for `:content`.
                             {:content (java.nio.file.Files/readAllBytes (.toPath (io/file "test/resources/image.png")))
                              ;; In this case, `:content-type` and `:filename` must be specified.
                              :content-type "image/png" :filename "new.png"}]}))
;; => {:result :success, :code 250, :message "250 OK\n"}

Multipart/alternative

(with-open [conn (tarayo/connect {:host "localhost" :port 25})]
  (tarayo/send! conn {:from "[email protected]"
                      :to "[email protected]"
                      :subject "hello"
                      :multipart "alternative"
                      :body [{:content-type "text/plain" :content "world"}
                             {:content-type "text/html" :content "<h1>wold</h1>"}]}))
;; => {:result :success, :code 250, :message "250 OK\n"}

Inline image (Multipart/related)

(require '[clojure.java.io :as io]
         '[tarayo.mail.mime.id :as mime-id])
;; => nil

(with-open [conn (tarayo/connect {:host "localhost" :port 25})]
  (let [content-id (mime-id/get-random)]
    (tarayo/send! conn {:from "[email protected]"
                        :to "[email protected]"
                        :subject "hello"
                        :multipart "related"
                        :body [{:content (str "<img src=\"cid:" content-id "\" /> world") :content-type "text/html"}
                               ;; containing id will be handled as "inline attachment file"
                               {:content (io/file "test/resources/image.png") :id content-id}]})))
;; => {:result :success, :code 250, :message "250 OK\n"}

Use for Gmail API

Like above, tarayo only supports SMTP, but you can also use for generating parameter to call Gmail API.

https://developers.google.com/gmail/api/v1/reference/users/messages/send

The entire email message in an RFC 2822 formatted and base64url encoded string. Returned in messages.get and drafts.get responses when the format=RAW parameter is supplied.

To generate this parameter, you can use tarayo.mail.mime.

(require '[tarayo.mail.mime :as mime]
         '[tarayo.mail.session :as session])
;; => nil

(defn- mime-message->raw-string [^jakarta.mail.internet.MimeMessage mime-msg]
  (let [buf (java.io.ByteArrayOutputStream.)]
    (.writeTo mime-msg buf)
    (org.apache.commons.codec.binary.Base64/encodeBase64URLSafeString (.toByteArray buf))))
;; => any?

(let [msg {:from "[email protected]"
           :to "[email protected]"
           :subject "hello"
           :body "world"}
      mime-msg (mime/make-message (session/make-session) msg)]
  (mime-message->raw-string mime-msg))
;; => string?

Stubbing

Example using shrubbery.

(require '[shrubbery.core :as shrubbery])
;; => nil

(let [conn (shrubbery/stub
            tarayo/ISMTPConnection
            {:send! "ok"
             :connected? true
             :close true})]
  (tarayo/send! conn "foo"))
;; => "ok"

License

Copyright 2020-2023 Toyokumo,Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

tarayo's Issues

mime-id/get-random should not put ID in angle brackets

The inline image example from the README
(let [content-id (mime-id/get-random)] (tarayo/send! conn { ... {:content (io/file "test/resources/image.png") :id content-id}]})))

does not work:

(mime-id/get-random) generates an ID with angle brackets (e.g. <[email protected]>),
but when generating the message, the content ID is again put into angle brackets here:
https://github.com/toyokumo/tarayo/blame/master/src/tarayo/mail/mime/multipart/body.clj#L88=

This results in the following invalid HTML img tag and the img not being displayed (at least in Thunderbird):

`------=_Part_2_1478985609.1649756558122
Content-Type: text/html; charset=utf-8
Content-Transfer-Encoding: 7bit

world
------=_Part_2_1478985609.1649756558122
Content-Type: image/png
Content-Transfer-Encoding: base64
Content-Disposition: inline; filename=logo.png
Content-ID: <[email protected]>`

Also the content id now contains double angle brackets.

To fix this issue, either the ID should not be out into angle brackets or the Content-ID is inserted without putting it into angle brackets. I would prefer the first option to keep backwards compatibilty and also not to have the implicit assumption, that all supplied content ids will be put into angle brackets.

Attachment file name is not encoded

There is a problem for the file name with UTF-8

Support `reply-to`

(send! conn {:from "[email protected]"
             :to "[email protected]"
             ;; HERE
             :reply-to "[email protected]"
             :subject "hello" :body "world"})

Failed to construct UA

version part is empty.

User-Agent: tarayo/
charset: UTF-8

All session properties should be converted to strings

According to https://jakarta.ee/specifications/mail/1.6/apidocs/com/sun/mail/smtp/package-summary.html,

The properties are always set as strings; the Type column describes how the string is interpreted. For example, use

   props.put("mail.smtp.port", "888");

to set the mail.smtp.port property, which is of type int.

Currently tarayo converts only booleans AFAICT.

It also would be nice to expose some convenience timeout properties...

Creating custom message id throws ClassCastException

I'm having trouble trying to use :message-id-fn as it always throw an ClassCastException. How can I use it correctly?

Trying to use a string:

(tarayo/send! conn {... :message-id-fn "[email protected]"})

java.lang.ClassCastException: class java.lang.String cannot be cast to class clojure.lang.IFn (java.lang.String is in module java.base of loader 'bootstrap'; clojure.lang.IFn is in unnamed module of 
loader 'app')

Trying to use a function

(tarayo/send! conn {... :message-id-fn (constantly "[email protected]") })

java.lang.ClassCastException: class clojure.core$constantly$fn__5689 cannot be cast to class java.lang.String (clojure.core$constantly$fn__5689 is in unnamed module of loader 'app'; java.lang.String 
is in module java.base of loader 'bootstrap')

Attach file to email without having a file on disk

Hi,

I would like to be able to add an attachment of a string/byte array/stream without having to write it to disc first. Possibly adding a key of :filename to the part which is used in place of the filename lookup?