the class that's used to communicate with an SMTP server and supports optional TLS/SSL encryption More...

#include <SmtpClient.qm.dox.h>

Public Member Methods
	clearStats ()
	Clears performance statistics. More...

nothing	clearWarningQueue ()
	Removes any warning Queue object from the Socket. More...

	connect ()
	Connect to the server with the connection parameters set in the constructor() More...

	constructor (string host, softint port, code log, code dbglog)
	creates the SmtpClient object More...

	constructor (string url, code log, code dbglog)
	creates the SmtpClient object More...

	destructor ()
	disconnects if connected and destroys the object More...

	disconnect ()
	disconnect from the server More...

	forceDisconnect ()
	force disconnect of socket without error More...

date	getConnectTimeoutDate ()
	returns the connect timeout as a relative time value

int	getConnectTimeoutMs ()
	returns the connect timeout as an integer giving milliseconds

hash< auto >	getInfo ()
	Returns info about the connection. More...

date	getReadTimeoutDate ()
	returns the read timeout as a relative time value

int	getReadTimeoutMs ()
	returns the read timeout as an integer giving milliseconds

string	getTarget ()
	Returns the connection target string. More...

hash< auto >	getUsageInfo ()
	Returns performance statistics for the socket. More...

bool	isConnected ()
	return connection status

hash< auto >	sendMessage (MailMessage::Message message)
	send a Message to the server More...

	setConnectTimeout (timeout to)
	sets the connect timeout

	setDebugLogClosure (*code log)
	Set debug log closure.

	setEventQueue ()
	Removes any Queue object. More...

	setEventQueue (Qore::Thread::Queue queue, auto arg, *bool with_data)
	Sets a Queue object to receive socket events. More...

	setInfoLogClosure (*code log)
	Set info log closure.

	setReadTimeout (timeout to)
	sets the read timeout

	setUserPass (string n_user, string n_pass)
	sets the username and password for authenticated connections More...

nothing	setWarningQueue (int warning_ms, int warning_bs, Queue queue, auto arg, timeout min_ms=1s)
	Sets a Queue object to receive socket warnings. More...

bool	ssl ()
	returns the SSL connection flag

	ssl (bool n_ssl)
	sets the SSL connection flag More...

bool	test ()
	returns the test mode flag

	test (bool ns)
	sets or disables test mode; no connections are made in test mode

bool	tls ()
	returns the TLS/SSL flag

	tls (bool n_tls)
	sets the TLS/SSL flag More...

Public Attributes
const	EsmtpPort = 587
	default ESMTP port

const	Protocols
	procotol config

const	SmtpPort = 25
	default SMTP port

const	SmtpsPort = 465
	default SMTPS port More...

Detailed Description

the class that's used to communicate with an SMTP server and supports optional TLS/SSL encryption

This class uses a Mutex lock in each SmtpClient object to ensure thread serialization to the underlying socket and its internal configuration, so it is safe to access in a multithreaded context.

Member Function Documentation

◆ clearStats()

SmtpClient::SmtpClient::clearStats ( )

Clears performance statistics.

Example:: smtp.clearStats();

Since: SmtpClient 1.3

See also: getUsageInfo()

◆ clearWarningQueue()

nothing SmtpClient::SmtpClient::clearWarningQueue ( )

Removes any warning Queue object from the Socket.

Example:: smtp.clearWarningQueue();

See also: setWarningQueue()

Since: SmtpClient 1.3

◆ connect()

SmtpClient::SmtpClient::connect ( )

Connect to the server with the connection parameters set in the constructor()

Note

For possible exceptions, see Qore's Socket::connect() method
This method is subject to thread serialization

◆ constructor() [1/2]

SmtpClient::SmtpClient::constructor	(	string	host,
		softint	port,
		*code	log,
		*code	dbglog
	)

creates the SmtpClient object

Parameters

host	the hostname of the SMTP server (use `"[hostname]"` to explicitly specify an ipv6 connection)
port	the port number of the SMTP server
log	a closure or call reference for log messages; a single string argument will be passed to this code for logging
dbglog	a closure for debugging/technical log messages; a single string argument will be passed to this code for logging

◆ constructor() [2/2]

SmtpClient::SmtpClient::constructor	(	string	url,
		*code	log,
		*code	dbglog
	)

creates the SmtpClient object

Example:: SmtpClient smtp("smtptls://[email protected]:[email protected]", \log(), \log());

Parameters

url	the URL of the SMTP server (use `"[hostname]"` or `"[address]"` for ipv6 connections); if no protocol (scheme) and no port is given for non-UNIX sockets, then SmtpPort is used as the default port number. This argument is parsed with parse_url(); see smtpclient_protocols for a description of the handling of the protocol (scheme) component of the URL including default ports per protocol (scheme). If an unknown protocol (scheme) is given then a `SMTP-UNKNOWN-PROTOCOL` exception is raised
log	an optional closure or call reference for log messages; a single string argument will be passed to this code for logging
dbglog	an optional closure or call reference for debugging/technical log messages; a single string argument will be passed to this code for logging

Exceptions

PARSE-URL-ERROR	the url argument could not be parsed with parse_url()
SMTPCLIENT-UNKNOWN-PROTOCOL	the protocol (scheme) given is unknown or unsupported
SMTPCLIENT-INVALID-AUTHENTICATION	partial authentication credentials passed; the username or password is missing

◆ destructor()

SmtpClient::SmtpClient::destructor ( )

disconnects if connected and destroys the object

if any exceptions occur during the disconnection, they are sent to the debug log closure/call reference

◆ disconnect()

SmtpClient::SmtpClient::disconnect ( )

disconnect from the server

Note: This method is subject to thread serialization

◆ forceDisconnect()

SmtpClient::SmtpClient::forceDisconnect ( )

force disconnect of socket without error

Note: This method is subject to thread serialization

◆ getInfo()

hash< auto > SmtpClient::SmtpClient::getInfo ( )

Returns info about the connection.

Returns

info about the connection with the following keys:

target: the connection target (host:port)
tls: the tls flag
ssl: the ssl flag
user: any username for the connection
pass: any password for the connection

◆ getTarget()

string SmtpClient::SmtpClient::getTarget ( )

Returns the connection target string.

Since: SmtpClient 1.7

◆ getUsageInfo()

hash< auto > SmtpClient::SmtpClient::getUsageInfo ( )

Returns performance statistics for the socket.

Example:: hash<auto> h = smtp.getUsageInfo();

Returns

a hash with the following keys:

"bytes_sent": an integer giving the total amount of bytes sent
"bytes_recv": an integer giving the total amount of bytes received
"us_sent": an integer giving the total number of microseconds spent sending data
"us_recv": an integer giving the total number of microseconds spent receiving data
"arg": (only if warning values have been set with SmtpClient::setWarningQueue()) the optional argument for warning hashes
"timeout": (only if warning values have been set with SmtpClient::setWarningQueue()) the warning timeout in microseconds
"min_throughput": (only if warning values have been set with SmtpClient::setWarningQueue()) the minimum warning throughput in bytes/sec

Since: SmtpClient 1.3

See also: clearStats()

◆ sendMessage()

hash< auto > SmtpClient::SmtpClient::sendMessage ( MailMessage::Message message )

send a Message to the server

Parameters

message the Message to send

Returns

a hash of data returned by the SMTP server (the return structure hashes described below are made up of the following keys: "code": the return code, "desc": the string description):

HELO or EHLO: a hash of the reply received from the HELO or EHLO command
RCPT: hash keyed by email address with hash return structures values for the RCPT TO command
MSGID: return structure after the send; generally contains message id
QUIT: the server response of the disconnect command

Note: This method is subject to thread serialization

Exceptions

MESSAGE-ERROR the message is incomplete and cannot be sent

◆ setEventQueue() [1/2]

SmtpClient::SmtpClient::setEventQueue ( )

Removes any Queue object.

After this call, socket events are no longer added to any currently-set Queue

Example:: smtp.setEventQueue();

See also: I/O Event Handling for more information

Since: SmtpClient 1.8

◆ setEventQueue() [2/2]

SmtpClient::SmtpClient::setEventQueue	(	Qore::Thread::Queue	queue,
		auto	arg,
		*bool	with_data
	)

Sets a Queue object to receive socket events.

Example:: smtp.setEventQueue(queue);

Parameters

queue	the Queue object to receive socket events; note that the Queue passed cannot have any maximum size set or a QUEUE-ERROR will be thrown
arg	an argument that will be included in each event hash in the arg key
with_data	if True, then the actual raw data transferred / received is also included in the events

Exceptions

QUEUE-ERROR the Queue passed has a maximum size set

See also: I/O Event Handling for more information

Since: SmtpClient 1.8

◆ setUserPass()

SmtpClient::SmtpClient::setUserPass	(	string	n_user,
		string	n_pass
	)

sets the username and password for authenticated connections

Parameters

n_user	the username to set for authentication
n_pass	the password to set for authentication

Note

Currently this class only knows how to do AUTH PLAIN authentication
This method is subject to thread serialization

◆ setWarningQueue()

nothing SmtpClient::SmtpClient::setWarningQueue	(	int	warning_ms,
		int	warning_bs,
		Queue	queue,
		auto	arg,
		timeout	min_ms = `1s`
	)

Sets a Queue object to receive socket warnings.

Example:: smtp.setWarningQueue(5000, 5000, queue, "socket-1");

Parameters

warning_ms	the threshold in milliseconds for individual socket actions (send, receive, connect), if exceeded, a socket warning is placed on the warning queue with the following keys: `"type"`: a string with the constant value `"SOCKET-OPERATION-WARNING"` `"operation"`: a string giving the operation that caused the warning (ex: `"connect"`) `"us"`: an integer giving the number of microseconds for the operation `"timeout"`: an integer giving the warning threshold in microseconds `"arg"`: if any `"arg"` argument is passed to the SmtpClient::setWarningQueue() method, it will be included in the warning hash here
warning_bs	value in bytes per second; if any call has performance below this threshold, a socket warning is placed on the warning queue with the following keys: `"type"`: a string with the constant value `"SOCKET-THROUGHPUT-WARNING"` `"dir"`: either `"send"` or `"recv"` depending on the direction of the data flow `"bytes"`: the amount of bytes sent `"us"`: an integer giving the number of microseconds for the operation `"bytes_sec"`: a float giving the transfer speed in bytes per second `"threshold"`: an integer giving the warning threshold in bytes per second `"arg"`: if any `"arg"` argument is passed to the SmtpClient::setWarningQueue() method, it will be included in the warning hash here
queue	the Queue object to receive warning events
arg	an optional argument to be placed in the `"arg"` key in each warning hash (could be used to identify the socket for example)
min_ms	the minimum transfer time with a resolution of milliseconds for a transfer to be eligible for triggering a warning; transfers that take less than this period of time are not eligible for raising a warning

Exceptions

QUEUE-ERROR	the Queue passed has a maximum size set
SOCKET-SETWARNINGQUEUE-ERROR	at least one of warning_ms and warning_bs must be > 0

See also: clearWarningQueue()

Since: SmtpClient 1.3

◆ ssl()

SmtpClient::SmtpClient::ssl ( bool n_ssl )

sets the SSL connection flag

Parameters

n_ssl if True then connections to the SMTP server will immediately try to negotiate transport layer TSL/SSL security; will also in this case turn off the TLS/SSL "STARTTLS" application layer security flag

◆ tls()

SmtpClient::SmtpClient::tls ( bool n_tls )

sets the TLS/SSL flag

Parameters

n_tls if True then use TLS/SSL; if the TLS/SSL flag is set then the client will issue a "STARTTLS" command after connecting and negotiate a secure TLS/SSL connection to the server; will also in this case turn off the SSL connection flag

Member Data Documentation

◆ SmtpsPort

const SmtpClient::SmtpClient::SmtpsPort = 465

default SMTPS port

note that this port is currently assigned to source-specific multicast audio/video (http://www.iana.org/assignments/port-numbers); it's use as a port for secure SMTP listeners (where security is enforced at the transport layer because the server immediately negotiates a TLS/SSL connection before the application protocol communication starts) is deprecated

Public Member Methods

Public Attributes

Detailed Description

Member Function Documentation

◆ clearStats()

◆ clearWarningQueue()

◆ connect()

◆ constructor() [1/2]

◆ constructor() [2/2]

◆ destructor()

◆ disconnect()

◆ forceDisconnect()

◆ getInfo()

◆ getTarget()

◆ getUsageInfo()

◆ sendMessage()

◆ setEventQueue() [1/2]

◆ setEventQueue() [2/2]

◆ setUserPass()

◆ setWarningQueue()

◆ ssl()

◆ tls()

Member Data Documentation

◆ SmtpsPort