Shard Detail

email v0.6.3

Simple e-mail sending library
crystal smtp email

Install & Use

Add the following code to your project's shard.yml under:

dependencies to use in production
- OR -
development_dependencies to use in development

  github: arcage/crystal-email


EMail for Crystal

Build Status

Simple email sending library for the Crystal programming language.

You can:

  • construct an email with a plain text message, a HTML message and/or some attachment files.
  • include resources(e.g. images) used in the HTML message.
  • set multiple recipients to the email.
  • use multibyte characters(only UTF-8) in the email.
  • send the email by using local or remote SMTP server.
  • use TLS connection by SMTP orver SSL/TLS(new) or STARTTLS command.
  • use SMTP-AUTH by AUTH PLAIN or AUTH LOGIN when using TLS.
  • send multiple emails concurrently by using multiple smtp connections.

You can not:

  • use ESMTP features except those mentioned above.


First, add the dependency to your shard.yml:

    github: arcage/crystal-email

Then, run shards install

Library requirement

When using STARTTLS or SMTPS, this shard require libssl and libcrypto for TLS handling.

You may have to install those libraries to your system.


To send a minimal email message:

require "email"

# Create email message
email =
email.from    ""      ""
email.subject "Subject of the mail"
email.message <<-EOM
  Message body of the mail.

  Your Signature

# Set SMTP client configuration
config ="", 25)

# Create SMTP client object
client =

client.start do
  # In this block, default receiver is client

This code will output log entries to STDOUT as follows:

2018/01/25 20:35:09 [e_mail.client/12347] INFO [EMail_Client] Start TCP session to
2018/01/25 20:35:10 [e_mail.client/12347] INFO [EMail_Client] Successfully sent a message from <> to 1 recipient(s)
2018/01/25 20:35:10 [e_mail.client/12347] INFO [EMail_Client] Close TCP session to

Client configs

You can set some connection settings to EMail::Client::Config object.

That can make SMTP connection to use TLS / SMTP AUTH, or output more detailed log message.

See EMail::Client::Config for more details.

Email message

You can set more email headers to EMail::Message object.

And, you can also send emails including attachment files, HTML message, and/or resource files related message body(e.g. image file for HTML message).

See EMail::Message for more details.

Concurrent sending

Note: this feature supports the concurrent(not parallel) sending with only one thread.

By using EMail::ConcurrentSender object, you can concurrently send multiple messages by multiple connections.

rcpt_list = ["", "", "", ""]

# Set SMTP client configuration
config ="", 25)

# Create concurrent sender object
sender =

# Sending emails with concurrently 3 connections.
sender.number_of_connections = 3

# Sending max 10 emails by 1 connection.
sender.messages_per_connection = 10

# Start email sending.
sender.start do
  # In this block, default receiver is sender
  rcpts_list.each do |rcpt_to|
    # Create email message
    mail =
    mail.from "" rcpt_to
    mail.subject "Concurrent email sending"
    mail.message "message to #{rcpt_to}"
    # Enqueue the email to sender
    enqueue mail

See EMail::ConcurrentSender for more details.


The v0.34.0 of Crystal language has drastic changes in the logging functions. To fit it, the v0.5.0 of this shard also changes the logging behaviour.

You can use two kinds of logger(Log type object), the default logger and the client specific logger.

The default logger is declered on the EMail::Client type. It can be got by EMail::Client.log, and change its behavior by EMail::Client.log_***= methods.

On the other hand, the client specific logger will be set to EMail::Client instance itself by EMail::Client::Config setting. With this, you can use your own logger for the EMail::Client object.

If the EMail::Client object has the client specific logger, the client use it to output the log entries. Otherwise, the client use the default logger.

See EMail::Client and EMail::Client::Config for more details.

Debug log

When you set the log level to Log::Severity::Debug, you can see all of the SMTP commands and the resposes in the log entries.

EMail::Client.log_level = Log::Severity::Debug

Debug log are very useful to check how SMTP session works.

But, in the case of using SMTP AUTH, the debug log includes Base64 encoded user ID and passowrd. You should remenber that anyone can decode the authentication information from the debug log. And, you should use that very carefully.


  • arcage ʕ·ᴥ·ʔAKJ - creator, maintainer


Thank you for valuable contributions.