class EMail::Client::Config
- EMail::Client::Config
- Reference
- Object
Overview
SMTP client setting object.
# Create config object with the SMTP server FQDN(or IP address), port number, and helo domain.
config = EMail::Client::Config.new("your.mx.example.com", 587, helo_domain: "your.host.example.com")
TLS settings
# Use SMTP over SSL/TLS
config.use_tls(TLSMode::SMTPS)
# Use STARTTLS command to send email
config.use_tls(TLSMode::STARTTLS)
# OpenSSL::SSL::Context::Client object for STARTTLS commands.
config.tls_context
# Disable TLS1.1 or lower protocols.
config.tls_context.add_options(OpenSSL::SSL::Options::NO_SSL_V2 | OpenSSL::SSL::Options::NO_SSL_V3 | OpenSSL::SSL::Options::NO_TLS_V1 | OpenSSL::SSL::Options::NO_TLS_V1_1)
# Set OpenSSL verification mode to skip certificate verification.
config.tls_context.verify_mode = OpenSSL::SSL::VerifyMode::NONE
SMTP authentication
config.use_auth("id", "password")
Logging
# Use the client specific(non-default) logger.
config.log = Log.for("your_log_source")
Error handling
# 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
Connection timeouts
config.connect_timeout = 1 # sec
config.read_timeout = 1 # sec
config.write_timeout = 1 # sec
config.dns_timeout = 1 # sec
Misc
# Set email client name, used in log entries and Message-ID headers.
# Default: "EMail_Client"
config.name = "your_app_name"
Defined in:
email/client/config.crConstructors
-
.new(host : String, port : Int32 = EMail::DEFAULT_SMTP_PORT, *, helo_domain : String)
Creates instance with minimam setting.
Class Method Summary
-
.create(host, port = EMail::DEFAULT_SMTP_PORT, *, client_name : String | Nil = nil, helo_domain : String, on_failed : EMail::Client::OnFailedProc | Nil = nil, on_fatal_error : EMail::Client::OnFatalErrorProc | Nil = nil, tls_verify_mode : OpenSSL::SSL::VerifyMode | Nil = nil, use_tls : TLSMode = TLSMode::NONE, auth : Tuple(String, String) | Nil = nil, log : Log | Nil = nil, dns_timeout : Int32 | Nil = nil, connect_timeout : Int32 | Nil = nil, read_timeout : Int32 | Nil = nil, write_timeout : Int32 | Nil = nil)
Returns
EMail::Client::Config
object with given settings.
Instance Method Summary
-
#auth_id
Returns authentication id when using SMTP AUTH.
-
#auth_password
Returns authentication password when using SMTP AUTH.
-
#client_name : String
Client name used in Message-Id header.
-
#client_name=(new_name : String)
Client name used in Message-ID header and log entry.
-
#connect_timeout : Time::Span | Nil
CONNECT timeout for the socket.
-
#connect_timeout=(sec : Int32)
CONNECT timeout for the socket.
-
#dns_timeout : Time::Span | Nil
DNS timeout for the socket.
-
#dns_timeout=(sec : Int32)
DNS timeout for the socket.
-
#helo_domain : String
Domain name for SMTP HELO / EHLO command.
-
#helo_domain=(new_domain : String)
Domain name for SMTP HELO or EHLO command.
-
#host : String
SMTP server hostname or IP address.
-
#host=(host : String)
SMTP server hostname or IP address.
-
#log : Log | Nil
Client specific(non-default) logger.
-
#log=(log : Log | Nil)
Client specific(non-default) logger.
-
#on_failed : EMail::Client::OnFailedProc | Nil
Callback function to be called when the SMTP server returns 4XX or 5XX response.
-
#on_failed=(on_failed : EMail::Client::OnFailedProc | Nil)
Callback function to be called when the SMTP server returns 4XX or 5XX response.
-
#on_fatal_error : EMail::Client::OnFatalErrorProc
Callback function to be calld when an exception is raised during SMTP session.
-
#on_fatal_error=(on_fatal_error : EMail::Client::OnFatalErrorProc)
Callback function to be calld when an exception is raised during SMTP session.
-
#port : Int32
Port number of SMTP server.
-
#port=(port : Int32)
Port number of SMTP server.
-
#read_timeout : Time::Span | Nil
READ timeout for the socket.
-
#read_timeout=(sec : Int32)
READ timeout for the socket.
-
#tls_context : OpenSSL::SSL::Context::Client
OpenSSL context for the TLS connection
-
#use_auth(id, password)
Sets the client to authenticate with SMTP AUTH command by using given id and password.
-
#use_auth?
Returns
true
when using SMTP AUTH. -
#use_smtps?
Returns
true
when using SMTPS. -
#use_starttls?
Returns
true
when using STARTTLS. -
#use_tls(tls_mode : TLSMode)
Enables TLS function to encrypt the SMTP session.
-
#write_timeout : Time::Span | Nil
WRITE timeout for the socket.
-
#write_timeout=(sec : Int32)
WRITE timeout for the socket.
Constructor Detail
Creates instance with minimam setting.
Notice: Since v0.7.0, helo_domain argument is required.
Class Method Detail
Returns EMail::Client::Config
object with given settings.
use_tls: tls_mode
->#use_tls(tls_mode)
auth: {"id", "password"}
->#use_auth("id", "password")
Other optional arguments set value to the property that has the same name.
Notice: Since v0.7.0, helo_domain argument is required.
Instance Method Detail
Client name used in Message-ID header and log entry.
Only alphabets(a
-z
, A
-Z
), numbers(0
-9
), and underscore(_
) are acceptable.
Domain name for SMTP HELO or EHLO command.
Only FQDN format is acceptable.
Client specific(non-default) logger.
Even without this, email clients can use the default logger of the EMail::Client type to output log entries.
See Log.
Client specific(non-default) logger.
Even without this, email clients can use the default logger of the EMail::Client type to output log entries.
See Log.
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.
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.
Callback function to be calld when an exception is raised during SMTP session.
It will be called with the raised Exception instance.
Callback function to be calld when an exception is raised during SMTP session.
It will be called with the raised Exception instance.
Sets 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.