Data Structures
struct	M_net_smtp_callbacks

Typedefs
typedef struct M_net_smtp	M_net_smtp_t

typedef void(*	M_net_smtp_connect_cb) (const char address, M_uint16 port, void thunk)

typedef M_uint64(*	M_net_smtp_connect_fail_cb) (const char address, M_uint16 port, M_net_error_t net_err, const char error, void *thunk)

typedef void(*	M_net_smtp_disconnect_cb) (const char address, M_uint16 port, void thunk)

typedef M_uint64(*	M_net_smtp_process_fail_cb) (const char command, int result_code, const char proc_stdout, const char proc_stderror, void thunk)

typedef M_uint64(*	M_net_smtp_processing_halted_cb) (M_bool no_endpoints, void *thunk)

typedef void(*	M_net_smtp_sent_cb) (const M_hash_dict_t headers, void thunk)

typedef M_bool(*	M_net_smtp_send_failed_cb) (const M_hash_dict_t headers, const char error, size_t attempt_num, M_bool can_requeue, void *thunk)

typedef void(*	M_net_smtp_reschedule_cb) (const char msg, M_uint64 wait_sec, void thunk)

typedef M_bool(*	M_net_smtp_iocreate_cb) (M_io_t io, char error, size_t errlen, void *thunk)

Enumerations
enum	M_net_smtp_status_t { M_NET_SMTP_STATUS_IDLE = 0 , M_NET_SMTP_STATUS_PROCESSING , M_NET_SMTP_STATUS_STOPPED , M_NET_SMTP_STATUS_NOENDPOINTS , M_NET_SMTP_STATUS_STOPPING }

enum	M_net_smtp_load_balance_t { M_NET_SMTP_LOAD_BALANCE_FAILOVER = 0 , M_NET_SMTP_LOAD_BALANCE_ROUNDROBIN }

Functions
M_net_smtp_t *	M_net_smtp_create (M_event_t el, const struct M_net_smtp_callbacks cbs, void *thunk)

void	M_net_smtp_destroy (M_net_smtp_t *sp)

void	M_net_smtp_pause (M_net_smtp_t *sp)

M_bool	M_net_smtp_resume (M_net_smtp_t *sp)

M_net_smtp_status_t	M_net_smtp_status (const M_net_smtp_t *sp)

void	M_net_smtp_setup_tcp (M_net_smtp_t sp, M_dns_t dns, M_tls_clientctx_t *ctx)

void	M_net_smtp_setup_tcp_timeouts (M_net_smtp_t *sp, M_uint64 connect_ms, M_uint64 stall_ms, M_uint64 idle_ms)

M_bool	M_net_smtp_add_endpoint_tcp (M_net_smtp_t sp, const char address, M_uint16 port, M_bool connect_tls, const char username, const char password, size_t max_conns)

M_bool	M_net_smtp_add_endpoint_process (M_net_smtp_t sp, const char command, const M_list_str_t args, const M_hash_dict_t env, M_uint64 timeout_ms, size_t max_processes)

M_bool	M_net_smtp_load_balance (M_net_smtp_t *sp, M_net_smtp_load_balance_t mode)

void	M_net_smtp_set_num_attempts (M_net_smtp_t *sp, size_t num)

void	M_net_smtp_set_stall_retries (M_net_smtp_t *sp, size_t num)

M_list_str_t *	M_net_smtp_dump_queue (M_net_smtp_t *sp)

M_bool	M_net_smtp_queue_smtp (M_net_smtp_t sp, const M_email_t e)

M_bool	M_net_smtp_queue_message (M_net_smtp_t sp, const char e)

M_bool	M_net_smtp_use_external_queue (M_net_smtp_t sp, char (*get_cb)(void))

void	M_net_smtp_external_queue_have_messages (M_net_smtp_t *sp)

Detailed Description

SMTP mailer

Defaults to 3 send attempts.

Will start running processing queued messages soon as an endpoint is added.

Data Structure Documentation

◆ M_net_smtp_callbacks

struct M_net_smtp_callbacks

Structure of callbacks to inform and control operating behavior.

Data Fields
M_net_smtp_connect_cb	connect_cb
M_net_smtp_connect_fail_cb	connect_fail_cb
M_net_smtp_disconnect_cb	disconnect_cb
M_net_smtp_process_fail_cb	process_fail_cb
M_net_smtp_processing_halted_cb	processing_halted_cb
M_net_smtp_sent_cb	sent_cb
M_net_smtp_send_failed_cb	send_failed_cb
M_net_smtp_reschedule_cb	reschedule_cb
M_net_smtp_iocreate_cb	iocreate_cb

Typedef Documentation

◆ M_net_smtp_t

typedef struct M_net_smtp M_net_smtp_t

◆ M_net_smtp_connect_cb

typedef void(* M_net_smtp_connect_cb) (const char *address, M_uint16 port, void *thunk)

Callback when connected.

Only used by TCP endpoints.

Parameters

[in]	address	Address of the server. This is the same address passed to M_net_smtp_add_endpoint_tcp.
[in]	port	Port connected to. This is the same port passed to M_net_smtp_add_endpoint_tcp.
[in]	thunk	Thunk parameter provided during create.

◆ M_net_smtp_connect_fail_cb

typedef M_uint64(* M_net_smtp_connect_fail_cb) (const char *address, M_uint16 port, M_net_error_t net_err, const char *error, void *thunk)

Callback when a connection to a server fails.

Only used by TCP endpoints.

Parameters

[in]	address	Address of the server. This is the same address passed to M_net_smtp_add_endpoint_tcp.
[in]	port	Port connected to. This is the same port passed to M_net_smtp_add_endpoint_tcp.
[in]	net_err	Indicates where there was a network problem of some type or if the network operation succeeded.
[in]	error	Error message.
[in]	thunk	Thunk parameter provided during create.

Returns: 0 if the endpoint should be be removed from the pool. Otherwise number of seconds to wait before retrying the server later.

◆ M_net_smtp_disconnect_cb

typedef void(* M_net_smtp_disconnect_cb) (const char *address, M_uint16 port, void *thunk)

Callback when the connection to the server disconnects.

Only used by TCP endpoints.

This does not represent an error. Server connections will be establish and disconnected periodically as part of normal processing.

Parameters

[in]	address	Address of the server. This is the same address passed to M_net_smtp_add_endpoint_tcp.
[in]	port	Port connected to. This is the same port passed to M_net_smtp_add_endpoint_tcp.
[in]	thunk	Thunk parameter provided during create.

◆ M_net_smtp_process_fail_cb

typedef M_uint64(* M_net_smtp_process_fail_cb) (const char *command, int result_code, const char *proc_stdout, const char *proc_stderror, void *thunk)

Callback when a process endpoint fails.

Only used by process endpoints.

Parameters

[in]	command	Command executed. Same as passed to M_net_smtp_add_endpoint_process.
[in]	result_code	Exit code of the process.
[in]	proc_stdout	Output of the process.
[in]	proc_stderror	Error output of the process.
[in]	thunk	Thunk parameter provided during create.

Returns: 0 if the endpoint should be be removed from the pool. Otherwise the number of seconds to wait before retrying the server later.

◆ M_net_smtp_processing_halted_cb

typedef M_uint64(* M_net_smtp_processing_halted_cb) (M_bool no_endpoints, void *thunk)

Callback when all endpoints have failed.

Parameters

[in]	no_endpoints	M_TRUE if processing was halted due to no endpoints configured.
[in]	thunk	Thunk parameter provided during create.

Returns: The number of seconds to wait before retrying to process. Use 0 to stop automatic reconnect attempts. When 0, M_net_smtp_resume must be called to restart processing. The return value is ignored if no endpoints are configured.

◆ M_net_smtp_sent_cb

typedef void(* M_net_smtp_sent_cb) (const M_hash_dict_t *headers, void *thunk)

Callback when a message was sent successfully.

Parameters

[in]	headers	Message headers provided as metadata to identify the message that was sent.
[in]	thunk	Thunk parameter provided during create.

◆ M_net_smtp_send_failed_cb

typedef M_bool(* M_net_smtp_send_failed_cb) (const M_hash_dict_t *headers, const char *error, size_t attempt_num, M_bool can_requeue, void *thunk)

Callback when sending a message failed.

Parameters

[in]	headers	Message headers provided as metadata to identify the message that failed.
[in]	error	Error message.
[in]	attempt_num	Current attempt number to send this message. Will be 0 when using an external queue. Otherwise, >= 1.
[in]	can_requeue	M_TRUE when the message can be requed to try again. Will be M_FALSE if the message has reached the maximum send attempts when using the internal queue. Or when an external queue is in use.
[in]	thunk	Thunk parameter provided during create.

Returns: M_TRUE to requeue the message. Ignored if using an external queue.

◆ M_net_smtp_reschedule_cb

typedef void(* M_net_smtp_reschedule_cb) (const char *msg, M_uint64 wait_sec, void *thunk)

Callback when a message needs to be requeued.

Only called when an external queue is used. Will be called when a message that was dequeued failed to send.

Parameters

[in]	msg	Raw email message.
[in]	wait_sec	Number of seconds the queue should hold the message before attempting to allow the message to resend. Typically set due to gray listing.
[in]	thunk	Thunk parameter provided during create.

◆ M_net_smtp_iocreate_cb

typedef M_bool(* M_net_smtp_iocreate_cb) (M_io_t *io, char *error, size_t errlen, void *thunk)

Callback to set additional I/O layers on the internal network request I/O object.

The primary use for this callback is to add tracing or bandwidth shaping. TLS should not be added here because it is handled internally.

Due to connections being in a dynamic pool, the callback may be called multiple times.

Parameters

[in]	io	The base I/O object to add layers on top of.
[in]	error	Error buffer to set a textual error message when returning a failure response.
[in]	errlen	Size of error buffer.
[in]	thunk	Thunk parameter provided during create.

Returns: M_TRUE on success. M_FALSE if setting up the I/O object failed and the operation should abort.

Enumeration Type Documentation

◆ M_net_smtp_status_t

enum M_net_smtp_status_t

Current processing status.

Enumerator
M_NET_SMTP_STATUS_IDLE	Currently up and able to process.
M_NET_SMTP_STATUS_PROCESSING	Currently processing.
M_NET_SMTP_STATUS_STOPPED	Not processing.
M_NET_SMTP_STATUS_NOENDPOINTS	Not processing due to no endpoints configured.
M_NET_SMTP_STATUS_STOPPING	In the process of stopping. Messages will not continue to be sent but current messages that are processing will process until finished.

◆ M_net_smtp_load_balance_t

enum M_net_smtp_load_balance_t

Pool operation mode.

Enumerator
M_NET_SMTP_LOAD_BALANCE_FAILOVER	Only one endpoint should be used and others should be used when the current endpoint has a failure.
M_NET_SMTP_LOAD_BALANCE_ROUNDROBIN	Connections should rotate across all endpoints.

Function Documentation

◆ M_net_smtp_create()

M_net_smtp_t * M_net_smtp_create	(	M_event_t *	el,
		const struct M_net_smtp_callbacks *	cbs,
		void *	thunk
	)

Create an SMTP pool.

Parameters

[in]	el	Event loop to operate on.
[in]	cbs	Callbacks for getting information about state and controlling behavior.
[in]	thunk	Optional thunk passed to callbacks.

Returns: SMTP network object.

◆ M_net_smtp_destroy()

void M_net_smtp_destroy ( M_net_smtp_t * sp )

Destroy an SMTP pool.

Parameters

[in] sp SMTP pool.

◆ M_net_smtp_pause()

void M_net_smtp_pause ( M_net_smtp_t * sp )

Pause processing.

Parameters

[in] sp SMTP pool.

◆ M_net_smtp_resume()

M_bool M_net_smtp_resume ( M_net_smtp_t * sp )

Resume processing.

Parameters

[in] sp SMTP pool.

Returns: M_TRUE if resumed. Otherwise M_FALSE. Can return M_FALSE for conditions, such as, no end points.

◆ M_net_smtp_status()

M_net_smtp_status_t M_net_smtp_status ( const M_net_smtp_t * sp )

Get the status of the SMTP pool.

Parameters

[in] sp SMTP pool.

Returns: Status.

◆ M_net_smtp_setup_tcp()

void M_net_smtp_setup_tcp	(	M_net_smtp_t *	sp,
		M_dns_t *	dns,
		M_tls_clientctx_t *	ctx
	)

Setup parameters for TCP endpoints.

This must be called before any TCP end points can be added.

It is highly recommend a TLS client context be provided even It is possible for the server to request a TLS connection due to START TLS. It is also required if a TLS only connection endpoint is configured.

Parameters

[in]	sp	SMTP pool.
[in]	dns	DNS object. Must be valid for the duration of this object's life.
[in]	ctx	The TLS client context. The context does not have to persist after being set here.

◆ M_net_smtp_setup_tcp_timeouts()

void M_net_smtp_setup_tcp_timeouts	(	M_net_smtp_t *	sp,
		M_uint64	connect_ms,
		M_uint64	stall_ms,
		M_uint64	idle_ms
	)

Setup timeout parameters for TCP endpoints.

Parameters

[in]	sp	SMTP pool.
[in]	connect_ms	Connect timeout in milliseconds. Will trigger when a connection has not been established within this time.
[in]	stall_ms	Stall timeout in milliseconds. Will trigger when the time between read and write events has been exceeded. This helps prevent a server from causing a denial of service by sending 1 byte at a time with a large internal between each one.
[in]	idle_ms	Overall time the connection can be idle before being closed. 0 will cause the connection to be closed after a single message.

◆ M_net_smtp_add_endpoint_tcp()

M_bool M_net_smtp_add_endpoint_tcp	(	M_net_smtp_t *	sp,
		const char *	address,
		M_uint16	port,
		M_bool	connect_tls,
		const char *	username,
		const char *	password,
		size_t	max_conns
	)

Add a TCP endpoint.

Parameters

[in]	sp	SMTP pool.
[in]	address	Address of server.
[in]	port	Port to connect on. If 0 will use port 25.
[in]	connect_tls	Server requires a TLS connection and the connection.
[in]	username	Authentication username.
[in]	password	Authentication password.
[in]	max_conns	Maximum connections to this server that should be opened. Scales up to max based on the number of messages queued.

Returns: M_TRUE if the end point was added. Otherwise M_FALSE. Will always return M_FALSE if M_net_smtp_setup_tcp was not called and provided with DNS or if M_net_smtp_setup_tcp was called without a TLS context and connect_tls is set.

◆ M_net_smtp_add_endpoint_process()

M_bool M_net_smtp_add_endpoint_process	(	M_net_smtp_t *	sp,
		const char *	command,
		const M_list_str_t *	args,
		const M_hash_dict_t *	env,
		M_uint64	timeout_ms,
		size_t	max_processes
	)

Add a process endpoint.

Parameters

[in]	sp	SMTP pool.
[in]	command	Command to send message using. Must accept message as STDIN.
[in]	args	Optional. List of arguments to pass to command.
[in]	env	Optional. List of environment variables to pass on to process. Use NULL to pass current environment through.
[in]	timeout_ms	Optional. Maximum execution time of the process before it is forcibly terminated. Use 0 for infinite.
[in]	max_processes	Optional. Maximum number of processes to open simultaneously. Default is 1.

Returns: M_TRUE if the endpoint was added. Otherwise, M_FALSE.

◆ M_net_smtp_load_balance()

M_bool M_net_smtp_load_balance	(	M_net_smtp_t *	sp,
		M_net_smtp_load_balance_t	mode
	)

Set how the pool should handle multiple endpoints.

Parameters

[in]	sp	SMTP pool.
[in]	mode	Load balancing method that should be used.

◆ M_net_smtp_set_num_attempts()

void M_net_smtp_set_num_attempts	(	M_net_smtp_t *	sp,
		size_t	num
	)

Number of resend attempts allowed per message.

Only applies to internal queue processing.

Parameters

[in]	sp	SMTP pool.
[in]	num	Number of send attempts per message.

◆ M_net_smtp_set_stall_retries()

void M_net_smtp_set_stall_retries	(	M_net_smtp_t *	sp,
		size_t	num
	)

Number of consecutive stall timeouts allowed per endpoint.

Parameters

[in]	sp	SMTP pool.
[in]	num	Number of stall retries per endpoint. Can be 0 to fail endpoint on first stall.

◆ M_net_smtp_dump_queue()

M_list_str_t * M_net_smtp_dump_queue ( M_net_smtp_t * sp )

Remove all queued messages from the queue.

Parameters

[in] sp SMTP pool.

It is recommended to call M_net_smtp_pause and wait until the status is stopped before calling this function.

Returns: List of messages that were queued. Will not include messages that are currently processing.

◆ M_net_smtp_queue_smtp()

M_bool M_net_smtp_queue_smtp	(	M_net_smtp_t *	sp,
		const M_email_t *	e
	)

Add an email object to the queue.

Parameters

[in]	sp	SMTP pool.
[in]	e	Email message.

Returns: M_TRUE if the message was added. Otherwise, M_FALSE.

◆ M_net_smtp_queue_message()

M_bool M_net_smtp_queue_message	(	M_net_smtp_t *	sp,
		const char *	e
	)

Add an email message as a string to the queue.

Parameters

[in]	sp	SMTP pool.
[in]	e	Message.

Returns: M_TRUE if the message was added. Otherwise, M_FALSE.

◆ M_net_smtp_use_external_queue()

M_bool M_net_smtp_use_external_queue	(	M_net_smtp_t *	sp,
		char ()(void)	get_cb
	)

Tell the pool to use an external queue.

Can only be called when the queue is empty. Once an external queue is setup, the internal queue cannot be used.

Parameters

[in]	sp	SMTP pool.
[in]	get_cb	Callback used by the pool to get messages from the queue. Callback should return NULL if no messages are available.

Returns: M_TRUE if the external queue was set.

◆ M_net_smtp_external_queue_have_messages()

void M_net_smtp_external_queue_have_messages ( M_net_smtp_t * sp )

Tell the pool messages are available in the external queue.

The pool will run though messages in the queue until no more messages are available However, the pool does not know when messages have been added to the external queue. It is up to the queue manager to inform the pool messages are available to process. It is recommended this be called after one or more messages are added.

Parameters

[in] sp SMTP pool.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Data Structure Documentation

◆ M_net_smtp_callbacks

Typedef Documentation

◆ M_net_smtp_t

◆ M_net_smtp_connect_cb

◆ M_net_smtp_connect_fail_cb

◆ M_net_smtp_disconnect_cb

◆ M_net_smtp_process_fail_cb

◆ M_net_smtp_processing_halted_cb

◆ M_net_smtp_sent_cb

◆ M_net_smtp_send_failed_cb

◆ M_net_smtp_reschedule_cb

◆ M_net_smtp_iocreate_cb

Enumeration Type Documentation

◆ M_net_smtp_status_t

◆ M_net_smtp_load_balance_t

Function Documentation

◆ M_net_smtp_create()

◆ M_net_smtp_destroy()

◆ M_net_smtp_pause()

◆ M_net_smtp_resume()

◆ M_net_smtp_status()

◆ M_net_smtp_setup_tcp()

◆ M_net_smtp_setup_tcp_timeouts()

◆ M_net_smtp_add_endpoint_tcp()

◆ M_net_smtp_add_endpoint_process()

◆ M_net_smtp_load_balance()

◆ M_net_smtp_set_num_attempts()

◆ M_net_smtp_set_stall_retries()

◆ M_net_smtp_dump_queue()

◆ M_net_smtp_queue_smtp()

◆ M_net_smtp_queue_message()

◆ M_net_smtp_use_external_queue()

◆ M_net_smtp_external_queue_have_messages()