SMTP: Simple Mail Transfer Protocol

https://en.m.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol

Client API

enum smtpclient::SmtpState

Values:

eSMTP_Banner = 0
eSMTP_Hello
eSMTP_StartTLS
eSMTP_SendAuth
eSMTP_SendingAuthLogin
eSMTP_RequestingAuthChallenge
eSMTP_SendAuthResponse
eSMTP_SendingAuth
eSMTP_Ready
eSMTP_SendMail
eSMTP_SendingMail
eSMTP_SendRcpt
eSMTP_SendingRcpt
eSMTP_SendData
eSMTP_SendingData
eSMTP_SendHeader
eSMTP_SendingHeaders
eSMTP_StartBody
eSMTP_SendingBody
eSMTP_Sent
eSMTP_Quitting
eSMTP_Disconnect
typedef Delegate<int(SmtpClient &client, int code, char *status)> SmtpClientCallback
SMTP_QUEUE_SIZE
SMTP_ERROR_LENGTH
SMTP_CODE_SERVICE_READY

SMTP response codes

SMTP_CODE_BYE
SMTP_CODE_AUTH_OK
SMTP_CODE_REQUEST_OK
SMTP_CODE_AUTH_CHALLENGE
SMTP_CODE_START_DATA
SMTP_OPT_PIPELINE
SMTP_OPT_STARTTLS
SMTP_OPT_AUTH_PLAIN
SMTP_OPT_AUTH_LOGIN
SMTP_OPT_AUTH_CRAM_MD5
class MailMessage
#include <MailMessage.h>

Public Functions

MailMessage &setHeader(const String &name, const String &value)

Set a header value.

Parameters
  • name:
  • value:
Return Value
  • MailMessage&:

HttpHeaders &getHeaders()

Get a reference to the current set of headers.

Return Value
  • HttpHeaders&:

MailMessage &setBody(const String &body, MimeType mime = MIME_TEXT)

Sets the body of the email.

Parameters
  • body:
  • mime:
Return Value
  • MailMessage&:

MailMessage &setBody(IDataSourceStream *stream, MimeType mime = MIME_TEXT)

Sets the body of the email.

Parameters
  • stream:
  • mime:
Return Value
  • MailMessage&:

MailMessage &addAttachment(FileStream *stream)

Adds attachment to the email.

Parameters
  • stream:
Return Value
  • MailMessage&:

MailMessage &addAttachment(IDataSourceStream *stream, MimeType mime, const String &filename = "")

Adds attachment to the email.

Parameters
  • stream:
  • mime:
  • filename:
Return Value
  • MailMessage&:

MailMessage &addAttachment(IDataSourceStream *stream, const String &mime, const String &filename = "")

Adds attachment to the email.

Parameters
  • stream:
  • mime:
  • filename:
Return Value
  • MailMessage&:

Public Members

String to
String from
String subject
String cc
class SmtpClient : protected TcpClient
#include <SmtpClient.h>

Public Functions

SmtpClient(bool autoDestroy = false)
~SmtpClient()
bool connect(const Url &url)

Connects to remote URL.

Parameters
  • url: Provides the protocol, remote server, port and user credentials allowed protocols:
    • smtp - clear text SMTP
    • smtps - SMTP over SSL connection

bool send(const String &from, const String &to, const String &subject, const String &body)

Queues a single message before it is sent later to the SMTP server.

Parameters
  • from:
  • to:
  • subject:
  • body: The body in plain text format
Return Value
  • bool: true when the message was queued successfully, false otherwise

bool send(MailMessage *message)

Powerful method to queues a single message before it is sent later to the SMTP server.

Parameters
  • message:
Return Value
  • bool: true when the message was queued successfully, false otherwise

MailMessage *getCurrentMessage()

Gets the current message.

Return Value
  • MailMessage*: The message, or NULL if none is scheduled

size_t countPending()
void quit()

Sends a quit command to the server and closes the TCP conneciton.

SmtpState getState()

Returns the current state of the SmtpClient.

void onMessageSent(SmtpClientCallback callback)

Callback that will be called every time a message is sent successfully.

Parameters
  • callback:

void onServerError(SmtpClientCallback callback)

Callback that will be called every an error occurs.

Parameters
  • callback:

Protected Functions

bool connect(const String &server, int port, bool useSsl = false)
bool connect(IpAddress addr, uint16_t port, bool useSsl = false)
void close()
void setReceiveDelegate(TcpClientDataDelegate receiveCb = nullptr)

Set or clear the callback for received data.

Parameters
  • receiveCb: callback delegate or nullptr

void setCompleteDelegate(TcpClientCompleteDelegate completeCb = nullptr)

Set or clear the callback for connection close.

Parameters
  • completeCb: callback delegate or nullptr

bool send(const char *data, uint16_t len, bool forceCloseAfterSent = false)
bool sendString(const String &data, bool forceCloseAfterSent = false)
bool isProcessing()
TcpClientState getConnectionState()
void setCloseAfterSent(bool ignoreIncomingData = false)

Schedules the connection to get closed after the data is sent

Parameters
  • ignoreIncomingData: when that flag is set the connection will start ignoring incoming data.

int writeString(const char *data, uint8_t apiflags = TCP_WRITE_FLAG_COPY)
int writeString(const String &data, uint8_t apiflags = TCP_WRITE_FLAG_COPY)
virtual int write(const char *data, int len, uint8_t apiflags = TCP_WRITE_FLAG_COPY)

Base write operation.

Parameters
  • data:
  • len:
  • apiflags: TCP_WRITE_FLAG_COPY, TCP_WRITE_FLAG_MORE
Return Value
  • int: -1 on error

int write(IDataSourceStream *stream)
uint16_t getAvailableWriteSize()
void flush()
void setTimeOut(uint16_t waitTimeOut)
IpAddress getRemoteIp() const
uint16_t getRemotePort() const
void setDestroyedDelegate(TcpConnectionDestroyedDelegate destroyedDelegate)

Sets a callback to be called when the object instance is destroyed.

Parameters
  • destroyedDelegate:

void setSslInitHandler(Ssl::Session::InitDelegate handler)

Set the SSL session initialisation callback.

Parameters
  • handler:

bool setSslConnection(Ssl::Connection *connection)
Ssl::Session *getSsl()

Get a pointer to the current SSL session object.

Note that this is typically used so we can query properties of an established session. If you need to change session parameters this must be done via setSslInitHandler.