class EMail::Client::Config

Overview

SMTP client settings.

# Set the SMTP server FQDN(or IP address) and port.
config = EMail::Client::Config.new("your.mx.example.com", 587)

# Set domain name for SMTP HELO/EHLO command.
# Default: "[#{IP address of client host}]"
config.helo_domain = "your.host.example.com"

# Set email client name.
# Default: "EMail_Client"
config.name = "your_app_name"

# Use TLS to send email
config.use_tls

# Set OpenSSL verification mode to skip certificate verification.
# Default: OpenSSL::SSL::VerifyMode::PEER
config.openssl_verify_mode = OpenSSL::SSL::VerifyMode::NONE

# Use SMTP AUTH for user authentication.
config.use_auth("id", "password")

# Use crystal default Logger object to output logs to STDOUT.
config.logger = Logger.new(STDOUT)

# Set SMTP error handler.
# Default: nil
config.on_failed = EMail::Client::OnFailedProc.new do |mail, command_history|
  puts mail.data
  puts ""
  puts command_history.join("\n")
end

# Set fatal error handler.
# Default: nil
config.on_fatal_error = EMail::Client::OnFatalErrorProc.new do |error|
  puts error
end

# Set connection timeout to 1 sec.
config.connect_timeout = 1

Debug log

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

config.logger.level = Logger::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.

Defined in:

email/client/config.cr

Constructors

Class Method Summary

Instance Method Summary

Constructor Detail

def self.new(host, port = EMail::DEFAULT_SMTP_PORT) #

[View source]

Class Method Detail

def self.create(host, port = EMail::DEFAULT_SMTP_PORT, *, client_name = nil, helo_domain = nil, on_failed : EMail::Client::OnFailedProc? = nil, on_fatal_error : EMail::Client::OnFatalErrorProc? = nil, openssl_verify_mode : OpenSSL::SSL::VerifyMode? = nil, use_tls : Bool? = nil, auth : Tuple(String, String)? = nil, logger : Logger? = nil, log_io : IO? = nil, log_level : Logger::Severity? = nil, log_progname : String? = nil, log_formatter : Logger::Formatter? = nil, dns_timeout : Int32? = nil, connect_timeout : Int32? = nil, read_timeout : Int32? = nil, write_timeout : Int32? = nil) #

Returns EMail::Client::Config object with given settings.

When other optional arguments are given, the property that has same name will be set.

NOTE: The #logger option and log_XXX options are exclusive.


[View source]

Instance Method Detail

def auth_id #

Returns authentication id when using SMTP AUTH.


[View source]
def auth_password #

Returns authentication password when using SMTP AUTH.


[View source]
def client_name : String #

Client name used in Message-Id header and log entry.


[View source]
def client_name=(new_name : String) #

Client name used in Message-ID header and log entry.

Only alphabets(a-z, A-Z), numbers(0-9), and underscore(_) are acceptable.


[View source]
def connect_timeout : Int32? #

CONNECT timeout for the socket.


[View source]
def connect_timeout=(sec : Int32) #

CONNECT timeout for the socket.


[View source]
def dns_timeout : Int32? #

DNS timeout for the socket.


[View source]
def dns_timeout=(sec : Int32) #

DNS timeout for the socket.


[View source]
def helo_domain : String? #

Domain name for SMTP HELO / EHLO command.


[View source]
def helo_domain=(new_domain : String) #

Domain name for SMTP HELO or EHLO command.

Only FQDN format is acceptable.


[View source]
def host : String #

SMTP server hostname or IP address.


[View source]
def host=(host : String) #

SMTP server hostname or IP address.


[View source]
def logger : Logger #

Logger object for logging SMTP session.


[View source]
def logger=(logger : Logger) #

Logger object for logging SMTP session.


[View source]
def on_failed : EMail::Client::OnFailedProc? #

Callback function to be called when the SMTP server returns 4XX or 5XX response.

This will be called with email message object that tried to send, and SMTP commands and responses history. In this function, you can do something to handle errors: e.g. "investigating the causes of the fail", "notifying you of the fail", and so on.Fatal error handler.


[View source]
def on_failed=(on_failed : EMail::Client::OnFailedProc?) #

Callback function to be called when the SMTP server returns 4XX or 5XX response.

This will be called with email message object that tried to send, and SMTP commands and responses history. In this function, you can do something to handle errors: e.g. "investigating the causes of the fail", "notifying you of the fail", and so on.Fatal error handler.


[View source]
def on_fatal_error : EMail::Client::OnFatalErrorProc? #

Callback function to be calld when an exception is raised during SMTP session.

It will be called with the raised Exception instance.


[View source]
def on_fatal_error=(on_fatal_error : EMail::Client::OnFatalErrorProc?) #

Callback function to be calld when an exception is raised during SMTP session.

It will be called with the raised Exception instance.


[View source]
def openssl_verify_mode : LibSSL::VerifyMode #

OpenSSL verification mode for the TLS connection.

See OpenSSL::SSL::VerifyMode. For Example set OpenSSL::SSL::VerifyMode::NONE to start tls connection with SMTP server which uses self-signed certificates.


[View source]
def openssl_verify_mode=(openssl_verify_mode) #

OpenSSL verification mode for the TLS connection.

See OpenSSL::SSL::VerifyMode. For Example set OpenSSL::SSL::VerifyMode::NONE to start tls connection with SMTP server which uses self-signed certificates.


[View source]
def port : Int32 #

Port number of SMTP server.


[View source]
def port=(port : Int32) #

Port number of SMTP server.


[View source]
def read_timeout : Int32? #

READ timeout for the socket.


[View source]
def read_timeout=(sec : Int32) #

READ timeout for the socket.


[View source]
def use_auth(id, password) #

Set the client to authenticate with SMTP AUTH command by using given id and password.

Only AUTH PLAIN and AUTH LOGIN commands are supported.

NOTE: SMTP authentication can be used only under TLS encryption.


[View source]
def use_auth? #

Returns true when using SMTP AUTH.


[View source]
def use_tls(tls_port : Int32? = nil) #

[View source]
def use_tls? : Bool #

Returns true when using TLS.


[View source]
def write_timeout : Int32? #

WRITE timeout for the socket.


[View source]
def write_timeout=(sec : Int32) #

WRITE timeout for the socket.


[View source]