lib/libesp32/ESP-Mail-Client/src/README.md
The description of the available functions in the current reease are shown below.
param smtp The pointer to SMTP session object which holds the data and the TCP client.
param msg The pointer to SMTP_Message class which contains the header, body, and attachments.
param closeSession The option to Close the SMTP session after sent.
return boolean The boolean value indicates the success of operation.
bool sendMail(SMTPSession *smtp, SMTP_Message *msg, bool closeSession = true);
param imap The pointer to IMAP sesssion object which holds the data and the TCP client.
param msg The pointer to SMTP_Message class which contains the header, body, and attachments.
param lastAppend The last message to append (optional). In case MULTIAPPEND extension
is supported, set this to false will append messages in single APPEND command.
param flags The flags to set to this message.
param dateTime The date/time to set to this message (optional).
return boolean The boolean value indicates the success of operation.
bool appendMessage(IMAPSession *imap, SMTP_Message *msg, T flags = "");
param imap The pointer to IMAP sesssion object which holds the data and the TCP client.
param closeSession The option to close the IMAP session after fetching or searching the Email.
return boolean The boolean value indicates the success of operation.
bool readMail(IMAPSession *imap, bool closeSession = true);
param imap The pointer to IMAP session object which holds the data and the TCP client.
param msgUID The UID of the message.
param flags The flag list to set.
param closeSession The option to close the IMAP session after set flag.
param silent The option to ignore the response.
param modsequence The int32_t option for UNCHANGESINCE conditional test.
return boolean The boolean value indicates the success of operation.
The modsequence value can be used only if IMAP server supports Conditional STORE extension and the selected mailbox supports modsequences.
bool setFlag(IMAPSession *imap, int msgUID, <string> flags, bool closeSession, bool silent = false, int32_t modsequence = -1);
param imap The pointer to IMAP session object which holds the data and the TCP client.
param sequenceSet The sequence set string i.g., unique identifier (UID) or
message sequence number or ranges of UID or sequence number.
param UID The option for sequenceSet whether it is UID or message sequence number.
param flags The flag list to set.
param closeSession The option to close the IMAP session after set flag.
param silent The option to ignore the response.
param modsequence The int32_t option for UNCHANGESINCE conditional test.
return boolean The boolean value indicates the success of operation.
The modsequence value can be used only if IMAP server supports Conditional STORE extension and the selected mailbox supports modsequences.
bool setFlag(IMAPSession *imap, <string> sequenceSet, bool UID, <string> flags, bool closeSession, bool silent = false, int32_t modsequence = -1);
param imap The pointer to IMAP session object which holds the data and the TCP client.
param msgUID The UID of the message.
param flags The flag list to add.
param closeSession The option to close the IMAP session after add flag.
param silent The option to ignore the response.
param modsequence The int32_t option for UNCHANGESINCE conditional test.
return boolean The boolean value indicates the success of operation.
The modsequence value can be used only if IMAP server supports Conditional STORE extension and the selected mailbox supports modsequences.
bool addFlag(IMAPSession *imap, int msgUID, <string> flags, bool closeSession, int32_t modsequence = -1);
param imap The pointer to IMAP session object which holds the data and the TCP client.
param sequenceSet The sequence set string i.g., unique identifier (UID) or
message sequence number or ranges of UID or sequence number.
param UID The option for sequenceSet whether it is UID or message sequence number.
param flags The flag list to add.
param closeSession The option to close the IMAP session after set flag.
param silent The option to ignore the response.
param modsequence The int32_t option for UNCHANGESINCE conditional test.
return boolean The boolean value indicates the success of operation.
The modsequence value can be used only if IMAP server supports Conditional STORE extension and the selected mailbox supports modsequences.
bool addFlag(IMAPSession *imap, <string> sequenceSet, bool UID, <string> flags, bool closeSession, bool silent = false, int32_t modsequence = -1);
param imap The pointer to IMAP session object which holds the data and the TCP client.
param msgUID The UID of the message that flags to be removed.
param flags The flag list to remove.
param closeSession The option to close the IMAP session after remove flag.
param silent The option to ignore the response.
param modsequence The int32_t option for UNCHANGESINCE conditional test.
return boolean The boolean value indicates the success of operation.
The modsequence value can be used only if IMAP server supports Conditional STORE extension and the selected mailbox supports modsequences.
bool removeFlag(IMAPSession *imap, int msgUID, <string> flags, bool closeSession, int32_t modsequence = -1);
param imap The pointer to IMAP session object which holds the data and the TCP client.
param sequenceSet The sequence set string i.g., unique identifier (UID) or
message sequence number or ranges of UID or sequence number.
param UID The option for sequenceSet whether it is UID or message sequence number.
param flags The flag list to remove.
param closeSession The option to close the IMAP session after set flag.
param silent The option to ignore the response.
param modsequence The int32_t option for UNCHANGESINCE conditional test.
return boolean The boolean value indicates the success of operation.
The modsequence value can be used only if IMAP server supports Conditional STORE extension and the selected mailbox supports modsequences.
bool removeFlag(IMAPSession *imap, <string> sequenceSet, bool UID, <string> flags, bool closeSession, bool silent = false, int32_t modsequence = -1);
param reconnect The boolean to set/unset WiFi AP reconnection.
void networkReconnect(bool reconnect);
param ss The SPI Chip/Slave Select pin.
param sck The SPI Clock pin.
param miso The SPI MISO pin.
param mosi The SPI MOSI pin.
aram frequency The SPI frequency.
return boolean The boolean value indicates the success of operation.
bool sdBegin(int8_t ss = -1, int8_t sck = -1, int8_t miso = -1, int8_t mosi = -1, uint32_t frequency = 4000000);
param ss SPI Chip/Slave Select pin.
param sdFSConfig The pointer to SDFSConfig object (ESP8266 only).
return boolean type status indicates the success of the operation.
bool sdBegin(SDFSConfig *sdFSConfig);
param ss The SPI Chip/Slave Select pin.
param spiConfig The pointer to SPIClass object for SPI configuartion.
param frequency The SPI frequency.
return boolean The boolean value indicates the success of operation.
bool sdBegin(int8_t ss, SPIClass *spiConfig = nullptr, uint32_t frequency = 4000000);
param sdFatSPIConfig The pointer to SdSpiConfig object for SdFat SPI configuration.
param ss The SPI Chip/Slave Select pin.
param sck The SPI Clock pin.
param miso The SPI MISO pin.
param mosi The SPI MOSI pin.
return boolean The boolean value indicates the success of operation.
bool sdBegin(SdSpiConfig *sdFatSPIConfig, int8_t ss = -1, int8_t sck = -1, int8_t miso = -1, int8_t mosi = -1);
param sdFatSDIOConfig The pointer to SdioConfig object for SdFat SDIO configuration.
return boolean The boolean value indicates the success of operation.
bool sdBegin(SdioConfig *sdFatSDIOConfig);
param mountpoint The mounting point.
param mode1bit Allow 1 bit data line (SPI mode).
param format_if_mount_failed Format SD_MMC card if mount failed.
return Boolean type status indicates the success of the operation.
bool sdMMCBegin(const char *mountpoint = "/sdcard", bool mode1bit = false, bool format_if_mount_failed = false);
return int Free memory amount in byte.
int getFreeHeap();
The following functions are available from the IMAP Session class.
This class used for controlling IMAP transports and retrieving the data from the IMAP server.
param timeoutSec The tcp timeout in seconds.
void setTCPTimeout(unsigned long timeoutSec);
param client The pointer to Arduino Client derived class e.g. WiFiClient, WiFiClientSecure, EthernetClient or GSMClient.
void setClient(Client *client);
param client The pointer to TinyGsmClient.
param modem The pointer to TinyGsm modem object. Modem should be initialized and/or set mode before transfering data.
param pin The SIM pin.
param apn The GPRS APN (Access Point Name).
param user The GPRS user.
param password The GPRS password.
void setGSMClient(Client *client, void *modem, const char *pin, const char *apn, const char *user, const char *password);
param networkConnectionCB The function that handles the network connection.
void networkConnectionRequestCallback(NetworkConnectionRequestCallback networkConnectionCB);
param networkStatusCB The function that handle the network connection status acknowledgement.
void networkStatusRequestCallback(NetworkStatusRequestCallback networkStatusCB);
param status The network status.
void setNetworkStatus(bool status);
param rx The BearSSL receive buffer size in bytes.
param tx The BearSSL trasmit buffer size in bytes.
void setSSLBufferSize(int rx = -1, int tx = -1);
param ts timestamp in seconds from midnight Jan 1, 1970.
param gmtOffset The GMT offset.
This function allows the internal time setting by timestamp i.e. timestamp from external RTC.
void setSystemTime(time_t ts, float gmtOffset = 0);
param session_config The pointer to Session_Config structured data that keeps the server and log in details.
param imap_data The pointer to IMAP_Data structured data that keeps the operation options.
param login The bool option for login after server connection.
return boolean The boolean value which indicates the success of operation.
bool connect(Session_Config *session_config, IMAP_Data *imap_data, bool login = true);
param email The IMAP server account email.
param password The IMAP server account password.
return boolean The boolean value which indicates the success of operation.
bbool loginWithPassword(<string> email, <string> password);
param email The IMAP server account email.
param token The Access token to log in.
return boolean The boolean value which indicates the success of operation.
bbool loginWithAccessToken(<string> email, <string> token);
param identification The pointer to IMAP_Identification structured data that keeps
the key properties e.g., name, version, os, os_version, vendor, support_url, address,
date, command, arguments, and environment.
bool id(IMAP_Identification *identification);
return The server ID string.
String serverID();
return boolean The boolean value indicates SASL authentication status.
bool isAuthenticated();
return boolean The boolean value indicates log in status.
bool isLoggedIn();
return boolean The boolean value indicates the firmware update status.
bool isFirmwareUpdateSuccess();
return boolean The boolean value which indicates the success of operation.
bool closeSession();
param tcpKeepIdleSeconds lwIP TCP Keepalive idle in seconds.
param tcpKeepIntervalSeconds lwIP TCP Keepalive interval in seconds.
param tcpKeepCount lwIP TCP Keepalive count.
For the TCP (KeepAlive) options, see this doc.
If value of one of these parameters is zero, the TCP KeepAlive will be disabled.
You can check the server connecting status, by exexuting <IMAPSession>.connected() which will return true when connection to the server is still alive.
void keepAlive(int tcpKeepIdleSeconds, int tcpKeepIntervalSeconds, int tcpKeepCount);
return Boolean status of TCP Keepalive.
bool isKeepAlive();
return boolean The boolean value indicates the connection status.
bool connected();
param level The level to enable the debug message
level = 0, no debugging
level = 1, basic level debugging
void debug(int level);
param folders The FoldersCollection class that contains the collection of the
FolderInfo structured data.
return boolean The boolean value which indicates the success of operation.
bool getFolders(FoldersCollection &folders);
param folderName The known mailbox folder name. The default name is INBOX.
param readOnly The option to open the mailbox for read only. Set this option to false when you wish
to modify the Flags using the setFlag, addFlag and removeFlag functions.
return boolean The boolean value which indicates the success of operation.
note: the function will exit immediately and return true if the time since previous success folder selection (open) with the same readOnly mode, is less than 5 seconds.
bool selectFolder(<string> folderName, bool readOnly = true);
param folderName The name of known mailbox folder to be opened.
param readOnly The option to open the mailbox for reading only. Set this option to false when you wish
to modify the flags using the setFlag, addFlag and removeFlag functions.
return boolean The boolean value which indicates the success of operation.
note: the function will exit immediately and return true if the time since previous success folder selection (open) with the same readOnly mode, is less than 5 seconds.
bool openFolder(<string> folderName, bool readOnly = true);
param expunge The option to allow emty the deleted flag set messages in case folder was open with editable mode.
return boolean The boolean value which indicates the success of operation.
bool closeFolder(bool expunge = false);
param folderName The name of folder to create.
return boolean The boolean value which indicates the success of operation.
bool createFolder(<string> folderName);
param reference The reference name.
param mailbox The mailbox name with possible wildcards.
param folders The return FoldersCollection that contains the folder info e.g., name, attribute and delimiter.
return boolean The boolean value which indicates the success of operation.
bool getSubscribesMailboxes(<string> reference, <string> mailbox, FoldersCollection &folders);
param folderName The name of folder to subscribe.
return boolean The boolean value which indicates the success of operation.
bool subscribe(<string> folderName)
param folderName The name of folder to unsubscribe.
return boolean The boolean value which indicates the success of operation.
bool unSubscribe(<string> folderName)
param currentFolderName The name of folder to create.
param newFolderName The new name of folder to create.
return boolean The boolean value which indicates the success of operation.
bool renameFolder(<string> currentFolderName, <string> newFolderName);
param folderName The name of folder to delete..
return boolean The boolean value which indicates the success of operation.
bool deleteFolder(<string> folderName);
param msgNum The message number or order in the total message numbers.
return boolean The boolean value which indicates the success of operation.
Returns 0 when fail to get UID.
int getUID(int msgNum);
param msgNum The message number or order in the total message numbers.
return string Message flags in selected or opened mailbox.
empty string when fail to get flags.
const char *getFlags(int msgNum);
param cmd The command string.
param callback The function that accepts IMAP_Response as parameter.
param tag The tag string to pass to the callback function.
return boolean The boolean value which indicates the success of operation.
imap.connect and imap.selectFolder or imap.openFolder are needed to call once prior to call this function.
bool sendCustomCommand(<string> cmd, imapResponseCallback callback, <string> tag);
param data The string data.
param lastData The flag represents the last data to send (optional).
return boolean The boolean value which indicates the success of operation.
Should be used after calling sendCustomCommand("APPEND xxxxxx");
bool sendCustomData(T data, bool lastData = false);
param data The byte data.
param size The data size.
param lastData The flag represents the last data to send (optional).
return boolean The boolean value which indicates the success of operation.
Should be used after calling ssendCustomCommand("APPEND xxxxxx");
bool sendCustomData(uint8_t *data, size_t size, bool lastData = false);
param session_config The pointer to Session_Config structured data that keeps the server and log in details.
param callback The callback function that accepts IMAP_Response as parameter.
param tag The tag that pass to the callback function.
return The boolean value indicates the success of operation.
bool customConnect(Session_Config *session_config, imapResponseCallback callback, <string> tag);
param toCopy The pointer to the MessageList class that contains the list of messages to copy.
param dest The destination folder that the messages to copy to.
return boolean The boolean value which indicates the success of operation.
bool copyMessages(MessageList *toCopy, <string> dest);
param sequenceSet The sequence set string i.g., unique identifier (UID) or
message sequence number or ranges of UID or sequence number.
param UID The option for sequenceSet whether it is UID or message sequence number.
param dest The destination folder that the messages to copy to.
return boolean The boolean value which indicates the success of operation.
bool copyMessages(<string> sequenceSet, bool UID, <string> dest);
param toMove The pointer to the MessageList class that contains the list of messages to move.
param dest The destination folder that the messages to move to.
return boolean The boolean value which indicates the success of operation.
bool moveMessages(MessageList *toMove, <string> dest);
param sequenceSet The sequence set string i.g., unique identifier (UID) or
message sequence number or ranges of UID or sequence number.
param UID The option for sequenceSet whether it is UID or message sequence number.
param dest The destination folder that the messages to move to.
return boolean The boolean value which indicates the success of operation.
bool moveMessages(<string> sequenceSet, bool UID, <string> dest);
param toDelete The pointer to the MessageList class that contains the list of messages to delete.
param expunge The boolean option to expunge all messages.
param modsequence The int32_t option for UNCHANGESINCE conditional test.
return boolean The boolean value indicates the success of operation.
The modsequence value can be used only if IMAP server supports Conditional STORE extension and the selected mailbox supports modsequences.
bool deleteMessages(MessageList *toDelete, bool expunge = false, int32_t modsequence = -1);
param sequenceSet The sequence set string i.g., unique identifier (UID) or
message sequence number or ranges of UID or sequence number.
param UID The option for sequenceSet whether it is UID or message sequence number.
param expunge The boolean option to expunge all messages.
param modsequence The int32_t option for UNCHANGESINCE conditional test.
return boolean The boolean value indicates the success of operation.
The modsequence value can be used only if IMAP server supports Conditional STORE extension and the selected mailbox supports modsequences.
bool deleteMessages(<string> sequenceSet, bool UID, bool expunge = false, int32_t modsequence = -1);
param quotaRoot The quota root to get.
param info The pointer to IMAP_Quota_Root_Info that contains quota root's resource name, usage and limit.
return boolean The boolean value which indicates the success of operation.
bool getQuota(<string> quotaRoot, IMAP_Quota_Root_Info *info);
param quotaRoot The quota root to set.
param data The pointer to IMAP_Quota_Root_Info that contains quota root's resource name, usage and limit.
return boolean The boolean value which indicates the success of operation.
bool setQuota(<string> quotaRoot, IMAP_Quota_Root_Info *data);
param mailbox The mailbox name.
param quotaRootsList The pointer to IMAP_Quota_Roots_List that contains the list of IMAP_Quota_Root_Info.
return boolean The boolean value which indicates the success of operation.
bool getQuotaRoot(<string> mailbox, IMAP_Quota_Roots_List *quotaRootsList);
param mailbox The mailbox name.
param aclList The pointer to the returning IMAP_Rights_List object.
return boolean The boolean value which indicates the success of operation.
bool getACL(<string> mailbox, IMAP_Rights_List *aclList);
param mailbox The mailbox name.
param acl The pointer to the acl IMAP_Rights_Info to set.
return boolean The boolean value which indicates the success of operation.
bool setACL(<string> mailbox, IMAP_Rights_Info *acl);
param mailbox The mailbox name.
param identifier The identifier (user) to remove the rights.
return boolean The boolean value which indicates the success of operation.
bool deleteACL(<string> mailbox, <string> identifier);
param mailbox The mailbox name.
param acl The pointer to the returning IMAP_Rights_Info object.
return boolean The boolean value which indicates the success of operation.
bool myRights(<string> mailbox, IMAP_Rights_Info *acl);
param mailbox The mailbox name.
param ns The pointer to the returning IMAP_Namespaces_List object.
return boolean The boolean value which indicates the success of operation.
bool getNamespace(IMAP_Namespaces_List *ns);
param capability The mailbox name.
return boolean The boolean value which indicates the success of operation.
bool enable(<string> capability);
return boolean The boolean value which indicates the success of operation.
bool listen();
return boolean The boolean value which indicates the success of operation.
bool stopListen();
return boolean The boolean value which indicates the changes status of mailbox.
bool folderChanged();
param imapCallback The function that accepts the imapStatusCallback as parameter.
void callback(imapStatusCallback imapCallback);
param callback The function that accepts the pointer to IMAP_Decoding_Info as parameter.
void characterDecodingCallback(imapCharacterDecodingCallback callback);
param mimeDataStreamCallback The function that accepts the MIME_Stream_Info as parameter.
void mimeDataStreamCallback(MIMEDataStreamCallback mimeDataStreamCallback);
bool headerOnly();
return The IMAP_MSG_List structured data which contains the text and html contents,
attachments, inline images, embedded rfc822 messages details for each message.
IMAP_MSG_List data();
return The SelectedFolderInfo class instance which contains the info about flags, total messages, next UID,
earch count and the available messages count.
SelectedFolderInfo selectedFolder();
return String The string of error details.
String errorReason();
return int The value of operating status error code.
The negative value indicated error.
See src/ESP_Mail_Error.h and extras/MB_FS.h
int errorCode();
void empty();
return IMAP_Status The IMAP_Status object contains the fetching and searching statuses.
IMAP_Status status();
return The JSON string of filenames.
note This will available only when standard SD library was used and file storage is SD.
String fileList();
The following functions are available from the SMTP Session class.
This class is similar to the IMAP session class, used for controlling SMTP transports and retrieving the data from the SMTP server.
param timeoutSec The tcp timeout in seconds.
void setTCPTimeout(unsigned long timeoutSec);
param client The pointer to Arduino Client derived class e.g. WiFiClient, WiFiClientSecure, EthernetClient or GSMClient.
void setClient(Client *client);
param client The pointer to TinyGsmClient.
param modem The pointer to TinyGsm modem object. Modem should be initialized and/or set mode before transfering data.
param pin The SIM pin.
param apn The GPRS APN (Access Point Name).
param user The GPRS user.
param password The GPRS password.
void setGSMClient(Client *client, void *modem, const char *pin, const char *apn, const char *user, const char *password);
param networkConnectionCB The function that handles the network connection.
void networkConnectionRequestCallback(NetworkConnectionRequestCallback networkConnectionCB);
param networkStatusCB The function that handle the network connection status acknowledgement.
void networkStatusRequestCallback(NetworkStatusRequestCallback networkStatusCB);
param status The network status.
void setNetworkStatus(bool status);
param rx The BearSSL receive buffer size in bytes.
param tx The BearSSL trasmit buffer size in bytes.
void setSSLBufferSize(int rx = -1, int tx = -1);
param ts timestamp in seconds from midnight Jan 1, 1970.
param gmtOffset The GMT offset.
This function allows the internal time setting by timestamp i.e. timestamp from external RTC.
void setSystemTime(time_t ts, float gmtOffset = 0);
param session_config The pointer to Session_Config structured data that keeps the server and log in details.
param login The bool option for login after server connection.
return boolean The boolean value indicates the success of operation.
bool connect(Session_Config *session_config, bool login = true);
param email The SMTP server account email.
param password The SMTP server account password.
return boolean The boolean value which indicates the success of operation.
bool loginWithPassword(<string> email, <string> password);
param email The SMTP server account email.
param token The Access token to log in.
return boolean The boolean value which indicates the success of operation.
bool loginWithAccessToken(<string> email, <string> token);
return boolean The boolean value indicates SASL authentication status.
bool isAuthenticated();
return boolean The boolean value indicates log in status.
bool isLoggedIn();
bool closeSession();
param tcpKeepIdleSeconds lwIP TCP Keepalive idle in seconds.
param tcpKeepIntervalSeconds lwIP TCP Keepalive interval in seconds.
param tcpKeepCount lwIP TCP Keepalive count.
For the TCP (KeepAlive) options, see this doc.
If value of one of these parameters is zero, the TCP KeepAlive will be disabled.
You can check the server connecting status, by exexuting <SMTPSession>.connected() which will return true when connection to the server is still alive.
void keepAlive(int tcpKeepIdleSeconds, int tcpKeepIntervalSeconds, int tcpKeepCount);
return Boolean status of TCP Keepalive.
bool isKeepAlive();
return boolean The boolean value indicates the connection status.
bool connected();
param session_config The pointer to Session_Config structured data that keeps the server and log in details.
param callback The callback function that accepts the SMTP_Response as parameter.
param commandID The command identifier number that will pass to the callback.
return The int value of response code.
If commandID was not set or set to -1, the command identifier will be auto increased started from zero.
int customConnect(Session_Config *session_config, smtpResponseCallback callback, int commandID = -1);
param cmd The command string.
param callback The function that accepts the SMTP_Response as parameter.
return boolean The boolean value which indicates the success of operation.
smtp.connect or smtp.customConnect is needed to call once prior to call this function.
bool sendCustomCommand(<string> cmd, smtpResponseCallback callback);
param data The string data.
return The boolean value which indicates the success of operation.
Should be used after calling sendCustomCommand("DATA");
bool sendCustomData(<string> data);
param data The byte data.
param size The data size.
return The boolean value which indicates the success of operation.
Should be used after calling sendCustomCommand("DATA");
bool sendCustomData(uint8_t *data, size_t size);
param level The level to enable the debug message
level = 0, no debugging
level = 1, basic level debugging
void debug(int level);
return String The string of error details.
String errorReason();
return int The value of operating status error code.
The negative value indicated error.
See src/ESP_Mail_Error.h and extras/MB_FS.h
int errorCode();
return int The value of SMTP server response status code.
See RFC 5321 standard's documentation.
int statusCode();
return String The value of SMTP server response status message.
String statusMessage();
param smtpCallback The callback function that accept the smtpStatusCallback param.
void callback(smtpStatusCallback smtpCallback);
return SMTP_Status The SMTP_Status object contains the sending status.
SMTP_Status status();
The following functions are available from the SMTP Message class.
This class is used for storing the message data including headers, body and attachments which will be processed with the SMTP session class.
param att The SMTP_Attachment class that stores the info about attachment
This function was used for clear the internal data of attachment item to be ready for reuse.
void resetAttachItem(SMTP_Attachment &att);
void clear();
void clearInlineimages();
void clearAttachments();
void clearRFC822Messages();
void clearRecipients();
void clearCc();
void clearBcc();
void clearHeader();
param att The SMTP_Attachment data item
void addAttachment(SMTP_Attachment &att);
param att The SMTP_Attachment data item
void addParallelAttachment(SMTP_Attachment &att);
param att The SMTP_Attachment data item
void addInlineImage(SMTP_Attachment &att);
param msg The RFC822_Message class object
void addMessage(SMTP_Message &msg);
param name The name of primary recipient
param email The Email address of primary recipient
void addRecipient(<string> name, <string> email);
param email The Email address of secondary recipient
void addCc(<string> email);
param email The Email address of the tertiary recipient
void addBcc(<string> email);
param hdr The header name and value
void addHeader(<string> hdr);
This property has the sub properties
esp_mail_email_info_t sender;
const char *subject;
byte type;
This property has the sub properties
esp_mail_plain_body_t text;
This propery has the sub properties
esp_mail_html_body_t html;
This propery has the sub properties
esp_mail_smtp_notify_never = 0,
esp_mail_smtp_notify_success = 1,
esp_mail_smtp_notify_failure = 2, and
esp_mail_smtp_notify_delay = 4
esp_mail_smtp_msg_response_t response;
This property has the enumeration values
esp_mail_smtp_priority_high = 1,
esp_mail_smtp_priority_normal = 3,
esp_mail_smtp_priority_low = 5
esp_mail_smtp_priority priority;
This propery has the sub property
esp_mail_smtp_enable_option_t enable;
This property has the sub properties
esp_mail_email_info_t from;
const char *ID;
const char *keywords;
const char *comments;
const char *date;
const char *return_path;
const char *in_reply_to;
const char *references;
The following functions are available from the IMAP Status class.
This class is used as the callback parameter for retrieving the status while reading the Email.
return string The info for each process
const char *info();
return boolean The bool value indicates that all reading processes are finished
bool success();
void empty();
The following functions are available from the SMTP Status class.
This class is used as the callback parameter for retrieving the status while sending the Email.
return string The info for each process
const char *info();
return boolean The bool value indicates that all sending processes are finished
bool success();
void empty();
return number The number of message that was sent
size_t completedCount();
return number The number of message that was not sent
size_t failedCount();
The following functions are available from the SendingResult class.
This class is used for retrieving the info about the result of sending the messages.
param index The index number of a message sending status
return SMTP_Result The SMTP_Result type data that provides these properties
SMTP_Result getItem(size_t index);
return number The number of result item
size_t size();
The following properties are available from the SMTP_Response data type.
This data type obtains the response from sending custom SMTP commands.
int id;
MB_String text;
int respCode;
The following functions are available from the FoldersCollection class.
This class is used for retrieving the info about the mailbox folders which available to read or serach in the user Email mailbox.
param index The index number of folders
return esp_mail_folder_info_item_t The esp_mail_folder_info_item_t structured data that provides these properties
esp_mail_folder_info_item_t info(size_t index);
return number The number of folder in the collection
size_t size();
The following functions are available from the SelectedFolderInfo class.
This class is used for retrieving the info about the sselected or opened mailbox folder.
return number The numbers of flags
size_t flagCount();
return number The numbers of messages in the selected mailbox folder
size_t msgCount();
return number The numbers of messages in the selected mailbox folder that recent flag was set
size_t recentCount();
return IMAP_Polling_Status The data that holds the polling status.
The IMAP_Polling_Status has the properties e.g. type, messageNum, and argument.
The type property is the type of status e.g.imap_polling_status_type_undefined, imap_polling_status_type_new_message, imap_polling_status_type_remove_message, and imap_polling_status_type_fetch_message.
The messageNum property is message number or order from the total number of message that added, fetched or deleted.
The argument property is the argument of commands e.g. FETCH
struct IMAP_Polling_Status pollingStatus();
return number The number represents the next message UID number
size_t nextUID();
return number The total number of messsages from search
size_t searchCount();
return number The number of messsage stored from search
size_t availableMessages();
return index The index of flag in the flags list
return String The argument of selected flag
String flag(size_t index);
The following properties are available from the Session_Config data type.
This data type is used for storing the session info about the server and login credentials.
This property has the sub properties
esp_mail_sesson_sever_config_t server;
This property has the sub properties
esp_mail_sesson_login_config_t login;
This property has the sub properties
esp_mail_sesson_secure_config_t secure;
This property has the sub properties
esp_mail_ports_functions ports_functions;
esp_mail_sesson_cert_config_t certificate;
esp_mail_spi_ethernet_module_t spi_ethernet_module;
NetworkConnectionHandler network_connection_handler;
uint16_t port;
The port protocol e.g. esp_mail_protocol_plain_text, esp_mail_protocol_ssl and esp_mail_protocol_tls.
esp_mail_protocol protocol;
The following properties are available from the IMAP_Data data type.
This data type is used for storing the IMAP transport and operating options to control and store the operation result e.g. the messahe contents from search and fetch.
This property has the sub properties
esp_mail_imap_fetch_config_t fetch;
This property has the sub properties
or message sequence number or ranges of UID or sequence number.
esp_mail_imap_sequence_set_t fetch;
This property has the sub properties
esp_mail_imap_search_config_t search;
This property has the sub properties
This is only limit for data to be stored in the IMAPSession.
The IMAP idle (polling) timeout in ms (1 min to 29 min). Default is 10 min.
The IMAP idle (polling) host check interval in ms (30 sec to imap_idle_timeout) for internet availability checking to ensure the connection is active.
Default is 1 min.
esp_mail_imap_limit_config_t limit;
This property has the sub properties
esp_mail_imap_enable_config_t enable;
This property has the sub properties
esp_mail_imap_download_config_t download;
This property has the sub properties
esp_mail_file_storage_type_none = 0,
esp_mail_file_storage_type_flash = 1, and
esp_mail_file_storage_type_sd = 2
esp_mail_imap_storage_config_t storage;
This property has the sub properties
esp_mail_imap_firmware_config_t firmware_update;
The following properties are available from the IMAP_Data data type.
This data type is used for storing the IMAP transport and operating options to control and store the operation result e.g. the messahe contents from search and fetch.
bool enable;
const char* enable;
esp_mail_smtp_embed_message_type_attachment = 0
sp_mail_smtp_embed_message_type_inline = 1
esp_mail_smtp_embed_message_type type;
The following properties are available from the esp_mail_blob_message_content_t data type.
This data type is used for storing the blob info of message body.
const uint8_t * data;
size_t size;
The following properties are available from the esp_mail_file_message_content_t data type.
This data type is used for storing the file info of message body.
const char *name;
esp_mail_file_storage_type type;
The following properties are available from the IMAP_MSG_Item data type.
This data type is used for message item info and its contents from search and fetch.
int msgNo;
int UID;
const char *ID;
const char *acceptLang;
const char *contentLang;
const char *from;
const char *fromCharset;
const char *to;
const char *toCharset;
const char *cc;
const char *ccCharset;
const char *date;
const char *subject;
const char *subjectCharset;
esp_mail_plain_body_t text;
esp_mail_html_body_t html;
const char *sender;
const char *senderCharset;
const char *keyword;
const char *comments;
const char *return_path;
const char *reply_to;
const char *in_reply_to;
const char *references;
const char *bcc;
const char *bccCharset;
const char *fetchError;
std::vector<IMAP_Attach_Item> attachments;
std::vector<IMAP_MSG_Item> rfc822;
The following properties are available from the IMAP_Response data type.
This data type obtains the response from sending custom IMAP commands.
MB_String tag;
MB_String text;
bool completed;
The following properties are available from the MIME_Data_Stream_Info data type.
This data type obtains the IMAP multipart body or MIME stream data via the callback function.
uint32_t uid;
const char *type;
const char *disposition;
const char *charSet;
bool flowed;
bool delsp;
const char *transfer_encoding;
const char *cid;
const char *description;
const char *filename;
const char *name;
const char *date;
size_t size;
size_t octet_size;
int octet_count;
size_t data_size;
void *data;
bool isFirstData;
bool isLastData;
The following properties are available from the IMAP_Decoding_Info data type.
This data type obtains the IMAP header and text (plain and html) strings to be decoded via the callback function based on its character set.
const char *charset;
const char *data;
0 or IMAP_Decoding_Info::message_part_type_header
1 or IMAP_Decoding_Info::message_part_type_text
message_part_type type;
Search crieria is used for searching the mailbox for messages that match the given searching criteria.
Searching criteria consist of one or more search keys. When multiple keys are specified, the result is the intersection (AND function) of all the messages that match those keys.
Example:
DELETED FROM "SMITH" SINCE 1-Feb-1994 refers
to all deleted messages from Smith that were placed in the mailbox since
February 1, 1994.
A search key can also be a parenthesized list of one or more search keys (e.g., for use with the OR and NOT keys).
SINCE 10-Feb-2019 will search all messages that received since 10 Feb 2019
UID SEARCH ALL will seach all message which will return the message UID
that can be use later for fetch one or more messages.
The following keywords can be used for the search criteria.
ALL - All messages in the mailbox; the default initial key for ANDing.
ANSWERED - Messages with the \Answered flag set.
BCC - Messages that contain the specified string in the envelope structure's BCC field.
BEFORE - Messages whose internal date (disregarding time and timezone) is earlier than the specified date.
BODY - Messages that contain the specified string in the body of the message.
CC - Messages that contain the specified string in the envelope structure's CC field.
DELETED - Messages with the \Deleted flag set.
DRAFT - Messages with the \Draft flag set.
FLAGGED - Messages with the \Flagged flag set.
FROM - Messages that contain the specified string in the envelope structure's FROM field.
HEADER - Messages that have a header with the specified field-name (as defined in [RFC-2822])
and that contains the specified string in the text of the header (what comes after the colon).
If the string to search is zero-length, this matches all messages that have a header line with
the specified field-name regardless of the contents.
KEYWORD - Messages with the specified keyword flag set.
LARGER - Messages with an (RFC-2822) size larger than the specified number of octets.
NEW - Messages that have the \Recent flag set but not the \Seen flag.
This is functionally equivalent to "(RECENT UNSEEN)".
NOT - Messages that do not match the specified search key.
OLD - Messages that do not have the \Recent flag set. This is functionally equivalent to
"NOT RECENT" (as opposed to "NOT NEW").
ON - Messages whose internal date (disregarding time and timezone) is within the specified date.
OR - Messages that match either search key.
RECENT - Messages that have the \Recent flag set.
SEEN - Messages that have the \Seen flag set.
SENTBEFORE - Messages whose (RFC-2822) Date: header (disregarding time and timezone) is earlier than the specified date.
SENTON - Messages whose (RFC-2822) Date: header (disregarding time and timezone) is within the specified date.
SENTSINCE - Messages whose (RFC-2822) Date: header (disregarding time and timezone) is within or later than the specified date.
SINCE - Messages whose internal date (disregarding time and timezone) is within or later than the specified date.
SMALLER - Messages with an (RFC-2822) size smaller than the specified number of octets.
SUBJECT - Messages that contain the specified string in the envelope structure's SUBJECT field.
TEXT - Messages that contain the specified string in the header or body of the message.
TO - Messages that contain the specified string in the envelope structure's TO field.
UID - Messages with unique identifiers corresponding to the specified unique identifier set.
Sequence set ranges are permitted.
UNANSWERED - Messages that do not have the \Answered flag set.
UNDELETED - Messages that do not have the \Deleted flag set.
UNDRAFT - Messages that do not have the \Draft flag set.
UNFLAGGED - Messages that do not have the \Flagged flag set.
UNKEYWORD - Messages that do not have the specified keyword flag set.
UNSEEN - Messages that do not have the \Seen flag set.
The helper function to set and get the system time.
param gmtOffset The GMT time offset in hour.
param daylightOffset The Daylight time offset in hour.
return boolean The status indicates the success of operation.
This requires internet connection
bool setClock(float gmtOffset, float daylightOffset);
param year The year.
param mon The months from 1 to 12.
param date The dates.
param hour The hours.
param mins The minutes.
param sec The seconds.
return time_t The value of timestamp.
time_t getTimestamp(int year, int mon, int date, int hour, int mins, int sec);
param gmt Return GMT time.
return timestamp of time string.
time_t getTimestamp(const char* timeString, bool gmt = false);
return uint64_t The value of current timestamp.
uint64_t getCurrentTimestamp();
return String The current date time string.
String getDateTimeString();
The MIT License (MIT)
Copyright (c) 2023 K. Suwatchai (Mobizt)
Permission is hereby granted, free of charge, to any person returning a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.