#include <nawa/mail/SmtpMailer.h>

Public Types
enum class	TlsMode { NONE , SMTPS , TRY_STARTTLS , REQUIRE_STARTTLS }

Public Member Functions
virtual	~SmtpMailer ()

	SmtpMailer (std::string serverDomain="localhost", unsigned int serverPort=25, TlsMode serverTlsMode=TlsMode::NONE, bool verifyServerTlsCert=true, std::string authUsername="", std::string authPassword="", long connectionTimeout=10000)

void	setServer (std::string domain, unsigned int port=25, TlsMode tlsMode=TlsMode::NONE, bool verifyTlsCert=true)

void	setAuth (std::string username, std::string password)

void	setConnectionTimeout (long timeout)

void	enqueue (std::shared_ptr< Email > email, EmailAddress to, std::shared_ptr< EmailAddress > from, std::shared_ptr< ReplacementRules > replacementRules=std::shared_ptr< ReplacementRules >())

void	bulkEnqueue (std::shared_ptr< Email > email, std::vector< EmailAddress > recipients, std::shared_ptr< EmailAddress > from, std::shared_ptr< ReplacementRules > replacementRules=std::shared_ptr< ReplacementRules >())

void	clearQueue ()

void	processQueue () const

Detailed Description

Definition at line 33 of file SmtpMailer.h.

Member Enumeration Documentation

◆ TlsMode

enum class nawa::mail::SmtpMailer::TlsMode

strong

How TLS should be used when connecting to an SMTP server.

NONE: Use an unencrypted connection.
SMTPS: Use SMTPS (SMTP over TLS).
TRY_STARTTLS: Try to switch to a TLS connection by using the STARTTLS command, if that fails, use an unencrypted connection. This might be a security risk, better don't use it.
REQUIRE_STARTTLS: Use the STARTTLS command to establish an encrypted connection, abort if not possible.

Enumerator
NONE
SMTPS
TRY_STARTTLS
REQUIRE_STARTTLS

Definition at line 45 of file SmtpMailer.h.

Constructor & Destructor Documentation

◆ ~SmtpMailer()

virtual nawa::mail::SmtpMailer::~SmtpMailer ( )

virtual

◆ SmtpMailer()

mail::SmtpMailer::SmtpMailer	(	std::string	serverDomain = `"localhost"`,
		unsigned int	serverPort = `25`,
		SmtpMailer::TlsMode	serverTlsMode = `TlsMode::NONE`,
		bool	verifyServerTlsCert = `true`,
		std::string	authUsername = `""`,
		std::string	authPassword = `""`,
		long	connectionTimeout = `10000`
	)

explicit

Construct an SmtpMailer object and optionally set the connection and authentication properties. Constructing the object will not establish a connection to the SMTP server yet.

Parameters

serverDomain	Domain name or IP address of the SMTP server to use. IPv6 addresses have to be enclosed in brackets. This value will be used to assemble the SMTP(S) URL and will not be checked for validity.
serverPort	Port of the SMTP server.
serverTlsMode	How TLS should be used, see TlsMode struct.
verifyServerTlsCert	Whether to verify the validity of the SMTP server's TLS certificate, if TLS is used (highly recommended).
authUsername	Username for authentication.
authPassword	Password for authentication.
connectionTimeout	Timeout for SMTP connection attempts in milliseconds.

Definition at line 95 of file SmtpMailer.cpp.

Member Function Documentation

◆ setServer()

void mail::SmtpMailer::setServer	(	std::string	domain,
		unsigned int	port = `25`,
		SmtpMailer::TlsMode	tlsMode = `TlsMode::NONE`,
		bool	verifyTlsCert = `true`
	)

Set the connection properties. This will not establish a connection to the SMTP server yet.

Parameters

domain	Domain name or IP address of the SMTP server to use. IPv6 addresses have to be enclosed in brackets. This value will be used to assemble the SMTP(S) URL and will not be checked for validity.
port	Port of the SMTP server.
tlsMode	How TLS should be used, see TlsMode struct.
verifyTlsCert	Whether to verify the validity of the SMTP server's TLS certificate, if TLS is used (highly recommended).

Definition at line 102 of file SmtpMailer.cpp.

◆ setAuth()

void mail::SmtpMailer::setAuth	(	std::string	username,
		std::string	password
	)

Set the authentication parameters for the SMTP connection.

Parameters

username	Username for authentication.
password	Password for authentication.

Definition at line 109 of file SmtpMailer.cpp.

◆ setConnectionTimeout()

void mail::SmtpMailer::setConnectionTimeout ( long timeout )

Set the timeout for SMTP connection attempts.

Parameters

timeout Timeout for SMTP connection attempts in milliseconds.

Definition at line 114 of file SmtpMailer.cpp.

◆ enqueue()

void mail::SmtpMailer::enqueue	(	std::shared_ptr< Email >	email,
		EmailAddress	to,
		std::shared_ptr< EmailAddress >	from,
		std::shared_ptr< ReplacementRules >	replacementRules = `std::shared_ptr<ReplacementRules>()`
	)

Add an email to the sending queue. The email will be sent upon calling processQueue().

Parameters

email	The Email object representing the email to be enqueued. This function will expect a shared_ptr to the email object, this allows efficient memory management: If the same email shall be sent to a lot of recipients, the same shared_ptr object can be passed to all calls to enqueue(), which means that only the pointer will be copied, but the Email object has to be kept in memory only once. To personalize the emails, you can instead use the replacement rules - one rule set can be saved for each recipient. Please note that this function might modify your Email object (it will set the obligatory "Date" and "From" headers, if they are not there yet, as well as the "Message-ID" header, if possible).
to	The recipient of the email (envelope). Please note that this will not modify the headers of your email (as shown in the email app of the recipient), those have to be set inside of the Email object. This is the address the mail will be actually sent to.
from	The sender of the email (envelope, also known as the return-path). It should be an email address that the SMTP server "owns", i.e., has the permission to send emails from this address (the spam filter of the recipient normally uses this address to classify the email). This address should be set in all cases, except for those noted in RFC 5321, section 4.5.5. This function will take a shared_ptr, too, as the sender of mass emails is usually always the same, so you can reuse the same object for all recipients. While this address may be different from the one in the "From" header of the email (which is required), this function will set the "From" header from this address in case it doesn't exist in the email yet.
replacementRules	An optional set of replacement rules. It is a map with a string as key (the text to be replaced) and another string as value (the text to replace it with). This set is saved and evaluated for each recipient individually, so this is a relatively memory-efficient way to personalize emails.

Definition at line 118 of file SmtpMailer.cpp.

◆ bulkEnqueue()

void mail::SmtpMailer::bulkEnqueue	(	std::shared_ptr< Email >	email,
		std::vector< EmailAddress >	recipients,
		std::shared_ptr< EmailAddress >	from,
		std::shared_ptr< ReplacementRules >	replacementRules = `std::shared_ptr<ReplacementRules>()`
	)

This function will enqueue an email for a list of recipients. This improves efficiency, but it doesn't allow the application of replacement rules for each recipient individually. Replacement rules can still be used, but the replacements will be the same for all recipients (if you need personalization, you should call enqueue() for each recipient and pass individual rule sets; the email object can be the same nevertheless, thanks to the shared_ptr).

Parameters

email	The Email object (for comments, look at the docs for enqueue()).
recipients	The list of recipients as EmailAddress objects (envelope, see enqueue() docs).
from	The sender of the email (envelope, see enqueue() docs).
replacementRules	An optional set of replacement rules (see enqueue() docs). They will be applied to the email once and do not offer personalization to individual recipients.

Definition at line 124 of file SmtpMailer.cpp.

◆ clearQueue()

void mail::SmtpMailer::clearQueue ( )

Clear the email queue.

Definition at line 130 of file SmtpMailer.cpp.

◆ processQueue()

void mail::SmtpMailer::processQueue ( ) const

Process the queue, i.e., establish an SMTP connection and send all emails in the queue. This function will not modify (and therefore not clear) the queue. In case of errors, a nawa::Exception with error code 1 will be thrown.

Definition at line 134 of file SmtpMailer.cpp.

The documentation for this class was generated from the following files:

include/nawa/mail/SmtpMailer.h
src/mail/SmtpMailer.cpp

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ TlsMode

Constructor & Destructor Documentation

◆ ~SmtpMailer()

◆ SmtpMailer()

Member Function Documentation

◆ setServer()

◆ setAuth()

◆ setConnectionTimeout()

◆ enqueue()

◆ bulkEnqueue()

◆ clearQueue()

◆ processQueue()