class EMail::Client::Config

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.cr

Constructors

Class Method Summary

Instance Method Summary

Constructor Detail

def self.new(host : String, port : Int32 = EMail::DEFAULT_SMTP_PORT, *, helo_domain : String) #

Creates instance with minimam setting.

Notice: Since v0.7.0, helo_domain argument is required.


[View source]

Class Method Detail

def self.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.

Other optional arguments set value to the property that has the same name.

Notice: Since v0.7.0, helo_domain argument is required.


[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.


[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 : Time::Span | Nil #

CONNECT timeout for the socket.


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

CONNECT timeout for the socket.


[View source]
def dns_timeout : Time::Span | Nil #

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 log : Log | Nil #

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.


[View source]
def log=(log : Log | Nil) #

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.


[View source]
def on_failed : EMail::Client::OnFailedProc | Nil #

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 | Nil) #

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 port : Int32 #

Port number of SMTP server.


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

Port number of SMTP server.


[View source]
def read_timeout : Time::Span | Nil #

READ timeout for the socket.


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

READ timeout for the socket.


[View source]
def tls_context : OpenSSL::SSL::Context::Client #

OpenSSL context for the TLS connection

See OpenSSL::SSL::Context::Client.


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

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.


[View source]
def use_auth? #

Returns true when using SMTP AUTH.


[View source]
def use_smtps? #

Returns true when using SMTPS.


[View source]
def use_starttls? #

Returns true when using STARTTLS.


[View source]
def use_tls(tls_mode : TLSMode) #

Enables TLS function to encrypt the SMTP session.


[View source]
def write_timeout : Time::Span | Nil #

WRITE timeout for the socket.


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

WRITE timeout for the socket.


[View source]