SMTP client

Data Structures
struct	lws_smtpc_result
struct	lws_smtpc_info

Macros
#define	LWS_SMTPC_PROTOCOL_NAME   "lws-smtp-client"

Typedefs
typedef enum lws_smtpc_tls	lws_smtpc_tls_t
typedef enum lws_smtpc_outcome	lws_smtpc_outcome_t
typedef struct lws_smtpc_result	lws_smtpc_result_t
typedef void(*	lws_smtpc_done_cb_t) (void *opaque, const lws_smtp_email_t *email, const lws_smtpc_result_t *res)
typedef struct lws_smtpc_info	lws_smtpc_info_t

Enumerations
enum	lws_smtpc_tls { LWS_SMTPC_TLS_NONE , LWS_SMTPC_TLS_IMPLICIT , LWS_SMTPC_TLS_STARTTLS }
enum	lws_smtpc_outcome { LWS_SMTPC_DELIVERED , LWS_SMTPC_REFUSED , LWS_SMTPC_GAVE_UP , LWS_SMTPC_ABANDONED }

Detailed Description

SMTP client

Queue mails, and lws delivers them to an SMTP relay in the background, telling you how each one went. The relay is typically the local MTA on 127.0.0.1:25, which is the default.

Every vhost has one, configured from its "lws-smtp-client" per-vhost options if it has any, which you get with lws_smtpc_vhost(). You can also make your own with lws_smtpc_create().

Mails are queued in memory, not persisted, and delivered one at a time, in order, over one connection to the relay that is kept for as long as there are mails to send. The SMTP itself is the sansIO session of lws-smtp.h.

• a mail the relay accepts, or refuses with a 5xx, is done with then
• a 4xx, a session the relay refuses, or a connection that ends before the mail at the head of the queue is done with, counts as a try for that mail: at max_tries it is given up, otherwise it is tried again on the next connection
• connections are made with backoff, so a relay that is down, or that keeps failing sessions, is not hammered. Failing to connect at all does not count as a try: mails wait, up to max_queue of them, until the relay is back, or until a retry policy with a finite conceal_count is exhausted, when they are given up

All of this is on the lws service thread: call the apis from there.

---

Data Structure Documentation

lws_smtpc_result

struct lws_smtpc_result

Definition at line 86 of file lws-smtp-client.h.

Collaboration diagram for lws_smtpc_result:

Data Fields
lws_smtpc_outcome_t	outcome
int	code	the relay's last reply code about the mail, 0 if none
const char *	text	that reply's text, printable ASCII, "" if none

lws_smtpc_info

struct lws_smtpc_info

Definition at line 109 of file lws-smtp-client.h.

Collaboration diagram for lws_smtpc_info:

Data Fields
struct lws_vhost *	vhost	the vhost whose client tls context the connections use
const char *	address	the relay to connect to, NULL for "127.0.0.1"
const char *	host	the name the relay's certificate is checked against, NULL for .address
uint16_t	port	0 for 25, or 465 with LWS_SMTPC_TLS_IMPLICIT
lws_smtpc_tls_t	tls	how the connection is secured
uint32_t	tls_flags	further LCCSCF_ flags for the tls, eg LCCSCF_SKIP_SERVER_CERT_HOSTNAME_CHECK
const char *	helo	our name for EHLO, NULL for "localhost"
const lws_retry_bo_t *	retry	backoff between connections to the relay, NULL for 100ms, 1s, 5s, 15s then 30s, with 20% jitter, concealing always. A finite conceal_count gives up the mails queued once the relay could not be used that many connections in a row; the next mail queued starts a fresh backoff. It must outlive the lws_smtpc
uint16_t	max_queue	the most mails queued at once, 0 for 128
uint16_t	reply_timeout_secs	how long to wait for each reply from the relay, 0 for 60s
uint8_t	max_tries	tries before a mail is given up, 0 for 5

Macro Definition Documentation

LWS_SMTPC_PROTOCOL_NAME

#define LWS_SMTPC_PROTOCOL_NAME   "lws-smtp-client"

#include <lws-smtp-client.h>

Definition at line 60 of file lws-smtp-client.h.

Typedef Documentation

lws_smtpc_tls_t

typedef enum lws_smtpc_tls lws_smtpc_tls_t

#include <lws-smtp-client.h>

lws_smtpc_outcome_t

typedef enum lws_smtpc_outcome lws_smtpc_outcome_t

#include <lws-smtp-client.h>

lws_smtpc_result_t

typedef struct lws_smtpc_result lws_smtpc_result_t

#include <lws-smtp-client.h>

lws_smtpc_done_cb_t

typedef void(* lws_smtpc_done_cb_t) (void *opaque, const lws_smtp_email_t *email, const lws_smtpc_result_t *res)

#include <lws-smtp-client.h>

lws_smtpc_done_cb_t - how a queued mail went

Parameters

opaque	as given to lws_smtpc_queue()
email	the mail as it was sent, with its date and message_id; the pointers are only valid during the callback
res	how it went

Called exactly once for each mail lws_smtpc_queue() accepted, never from inside lws_smtpc_queue() itself. lws_smtpc_queue() may be called from here, and lws_smtpc_destroy() on an lws_smtpc you created.

Definition at line 106 of file lws-smtp-client.h.

lws_smtpc_info_t

typedef struct lws_smtpc_info lws_smtpc_info_t

#include <lws-smtp-client.h>

Enumeration Type Documentation

lws_smtpc_tls

enum lws_smtpc_tls

#include <lws-smtp-client.h>

Enumerator
LWS_SMTPC_TLS_NONE	plaintext, eg to a local relay on :25
LWS_SMTPC_TLS_IMPLICIT	tls from the start, eg submissions on :465
LWS_SMTPC_TLS_STARTTLS	plaintext, then STARTTLS before any mail, eg submission on :587. A relay that does not offer it, or refuses it, gets no mail

Definition at line 62 of file lws-smtp-client.h.

                           {
        LWS_SMTPC_TLS_NONE,
        LWS_SMTPC_TLS_IMPLICIT,
        LWS_SMTPC_TLS_STARTTLS,
} lws_smtpc_tls_t;

lws_smtpc_outcome

enum lws_smtpc_outcome

#include <lws-smtp-client.h>

Enumerator
LWS_SMTPC_DELIVERED	the relay accepted the mail
LWS_SMTPC_REFUSED	the relay refused it with a 5xx
LWS_SMTPC_GAVE_UP	it was tried max_tries times without being done with, or the relay could not be used for as many connections in a row as the retry policy conceals
LWS_SMTPC_ABANDONED	the lws_smtpc was destroyed, or its vhost was, before it was done with

Definition at line 72 of file lws-smtp-client.h.

                               {
        LWS_SMTPC_DELIVERED,
        LWS_SMTPC_REFUSED,
        LWS_SMTPC_GAVE_UP,
        LWS_SMTPC_ABANDONED,
} lws_smtpc_outcome_t;