smtp.h File Reference

Outbound SMTP client (RFC 5321) - send a device email alert. More...

#include <stddef.h>
#include <stdint.h>

Go to the source code of this file.

Classes
struct	SmtpConfig
	Server address + credentials for one send. Addresses are bare (no angle brackets). More...
struct	SmtpMessage
	One plain-text message. More...

Typedefs
typedef int(*	SmtpSendFn) (void *ctx, const uint8_t *data, size_t len)
	Transport seam for smtp_run(): the engine sends and receives raw bytes only through these, so it can run against a real socket or a test mock.
typedef int(*	SmtpRecvFn) (void *ctx, uint8_t *buf, size_t cap)

Enumerations
enum class	SmtpResult : int32_t {   SMTP_OK = 0 , SMTP_ERR_ARG = -1 , SMTP_ERR_CONNECT = -2 , SMTP_ERR_TLS = -3 ,   SMTP_ERR_IO = -4 , SMTP_ERR_PROTOCOL = -5 , SMTP_ERR_AUTH = -6 , SMTP_ERR_OVERFLOW = -7 }
	Result of an SMTP send. 0 is success; every failure is a distinct negative code. More...

Functions
SmtpResult	smtp_run (const SmtpConfig *cfg, const SmtpMessage *msg, SmtpSendFn send, SmtpRecvFn recv, void *ctx)
	Drive the full SMTP exchange over send / recv. Pure - no lwIP or TLS - so it is host-testable with a scripted transport.
SmtpResult	smtp_send (const SmtpConfig *cfg, const SmtpMessage *msg)
	Blocking one-shot send over the real transport (det_client, plus TLS when cfg->tls). Opens the connection, runs smtp_run(), and closes.

Detailed Description

Outbound SMTP client (RFC 5321) - send a device email alert.

A blocking one-shot: connect, greet, optional AUTH LOGIN, then MAIL FROM / RCPT TO / DATA a plain-text message and QUIT. It rides the shared outbound client transport (det_client), with implicit TLS (SMTPS, typically port 465) when the config sets tls and DETWS_ENABLE_TLS is on. Zero heap; every buffer is a compile-time size (DETWS_SMTP_*). Gated by DETWS_ENABLE_SMTP.

The dialogue itself (smtp_run) is written against a send/recv seam, so the whole protocol exchange - greeting codes, AUTH, dot-stuffing, the terminating . - is unit-tested on the host with a scripted mock server, no lwIP or TLS required.

"SMS fallback" needs no extra code: most mobile carriers accept an email-to-SMS gateway address (e.g. 5551234567@txt.example.net) as the recipient.

Author

Douglas Quigg (dstroy0)

Date

2026

Definition in file smtp.h.

Typedef Documentation

SmtpSendFn

typedef int(* SmtpSendFn) (void *ctx, const uint8_t *data, size_t len)

Transport seam for smtp_run(): the engine sends and receives raw bytes only through these, so it can run against a real socket or a test mock.

Returns

send: number of bytes written (must equal len), or <0 on error.

recv: number of bytes read (>0), or <=0 on close / error / timeout.

Definition at line 51 of file smtp.h.

SmtpRecvFn

typedef int(* SmtpRecvFn) (void *ctx, uint8_t *buf, size_t cap)

Definition at line 52 of file smtp.h.

Enumeration Type Documentation

SmtpResult

enum class SmtpResult : int32_t

strong

Result of an SMTP send. 0 is success; every failure is a distinct negative code.

Enumerator
SMTP_OK
SMTP_ERR_ARG	a required field (host / from / to) was null or empty
SMTP_ERR_CONNECT	could not open the transport (DNS / connect)
SMTP_ERR_TLS	the TLS handshake failed (SMTPS)
SMTP_ERR_IO	a send/recv failed or the reply timed out
SMTP_ERR_PROTOCOL	the server returned an unexpected reply code
SMTP_ERR_AUTH	AUTH was rejected (bad user/password)
SMTP_ERR_OVERFLOW	a command line or the message exceeded its fixed buffer

Definition at line 32 of file smtp.h.

Function Documentation

smtp_run()

SmtpResult smtp_run	(	const SmtpConfig *	cfg,
		const SmtpMessage *	msg,
		SmtpSendFn	send,
		SmtpRecvFn	recv,
		void *	ctx
	)

Drive the full SMTP exchange over send / recv. Pure - no lwIP or TLS - so it is host-testable with a scripted transport.

Returns

SmtpResult::SMTP_OK on a delivered message, else an SmtpResult error.

smtp_send()

SmtpResult smtp_send	(	const SmtpConfig *	cfg,
		const SmtpMessage *	msg
	)

Blocking one-shot send over the real transport (det_client, plus TLS when cfg->tls). Opens the connection, runs smtp_run(), and closes.

Returns

SmtpResult::SMTP_OK or an SmtpResult error. On non-Arduino (host) builds there is no lwIP, so this returns SmtpResult::SMTP_ERR_CONNECT; use smtp_run() directly in tests.