crystal-email
forked from arcage/crystal-emailEMail for Crystal
Note: This is a fork of arcage/crystal-email
. I have made one small change: added an override_message_id
parameter to send
, which prevents it from overriding a previously set message_id
. I needed this feature to get this shard to work correctly with an application that uses notmuch as a mail store.
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
orAUTH LOGIN
when using TLS. - send multiple emails concurrently by using multiple smtp connections.
You can not:
- use ESMTP features except those mentioned above.
Installation
First, add the dependency to your shard.yml
:
dependencies:
email:
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.
Usage
To send a minimal email message:
NOTE: Since v0.7.0, EMail::Client::Config object require helo_domain
argument at initializing.
require "email"
# Create email message
email = EMail::Message.new
email.from "your_addr@example.com"
email.to "to@example.com"
email.subject "Subject of the mail"
email.message <<-EOM
Message body of the mail.
--
Your Signature
EOM
# Set SMTP client configuration
config = EMail::Client::Config.new("your.mx.example.com", 25, helo_domain: "your.host.example.com")
# Create SMTP client object
client = EMail::Client.new(config)
client.start do
# In this block, default receiver is client
send(email)
end
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 your.mx.example.com:25
2018/01/25 20:35:10 [e_mail.client/12347] INFO [EMail_Client] Successfully sent a message from <your_addr@example.com> to 1 recipient(s)
2018/01/25 20:35:10 [e_mail.client/12347] INFO [EMail_Client] Close TCP session to your.mx.example.com:25
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 = ["a@example.com", "b@example.com", "c@example.com", "d@example.com"]
# Set SMTP client configuration
config = EMail::Client::Config.new("your.mx.example.com", 25, helo_domain: "your.host.example.com")
# Create concurrent sender object
sender = EMail::ConcurrentSender.new(config)
# 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 = EMail::Message.new
mail.from "your_addr@example.com"
mail.to rcpt_to
mail.subject "Concurrent email sending"
mail.message "message to #{rcpt_to}"
# Enqueue the email to sender
enqueue mail
end
end
See EMail::ConcurrentSender for more details.
Logging
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.
Owner
- arcage ʕ·ᴥ·ʔAKJ - creator, maintainer
Contributors
Thank you for valuable contributions.
crystal-email
- 0
- 0
- 0
- 1
- 0
- 8 months ago
- February 7, 2024
MIT License
Thu, 21 Nov 2024 01:15:51 GMT