This article will teach you how to send email from ESP8266 NodeMCU board via SMTP Server. We'll show you how to send an email with plain text, HTML text, and attachments such as images and files (.txt). The Arduino core will be used to program the ESP8266 NodeMCU board.
In this tutorial, we cover the following topics:
Introducing SMTP Servers
SMTP is an internet standard for email transmission that stands for Simple Mail Transfer Protocol. You need to connect the ESP8266 NodeMCU to an SMTP server to send emails using it.
ESP-Mail-Client Library
We'll use the ESP-Mail-Client library to send email from ESP8266 NodeMCU board. The ESP8266 NodeMCU can send and receive emails with or without attachments over SMTP and IMAP servers using this library. If you like this library and plan to use it in your projects, please consider supporting the developer's efforts by visiting the library's GitHub page.
We'll use SMTP in this article to send an email with and without attachments. We'll submit an image (.png) and a text (.txt) file as examples. The email files may be kept in the ESP8266 filesystem (SPIFFS or LittleFS) or on a microSD card (not covered in this article).
Installing the ESP Mail Client Library
You need to install the ESP-Mail-Client library before proceeding with this tutorial. This library cannot be installed using the Arduino IDE Library Manager. To install the library, follow the next steps:
- Click here to download the ESP-Mail-Client library.zip folder.
- In your Arduino IDE, go to Sketch > Include Library > Add .zip Library.
- Select the zip file you’ve just downloaded.
Then, under File > Examples > ESP-Mail-Client, you'll find various examples to test. The examples are also available on the library's GitHub page.
To include the library in your platformio.ini file if you're using the ESP8266 with VS Code and PlatformIO, copy the following to your platformio.ini file:
lib_deps = mobizt/ESP Mail Client @ ^1.1.7Sender Email (New Account)
To send emails to your main personal email address, we recommend starting a new email account. Do not use your primary personal email address to send email from ESP8266 NodeMCU. You may be banned or have your account temporarily suspended if anything goes wrong in your code or if you submit too many requests by accident.
To send the emails, we'll use a newly created Gmail.com account, but you may use any other email service. The receiver's email address may be your personal email address without issue.
Create a Sender Email Account
Create a new email account to use to send email from ESP8266 NodeMCU board. Go to this link to create a Gmail account if you wish to use it.
![Arduino UNO R4 WiFi [ABX00087] - Renesas RA4M1 / ESP32-S3 - Wi-Fi, Bluetooth, USB-C, CAN, DAC, OP AMP, Qwiic Connector, 12x8 LED Matrix](https://m.media-amazon.com/images/I/416S910MpBL.jpg)
Create an App Password
You'll need to create an app password so that the ESP32 can send emails using your Gmail account. A less secure app or device may access your Google Account with the use of an app password, which is a 16-digit number. Learn more about sign-in with app passwords here.
An app password can only be used with accounts that have 2-step verification turned on.
- Open your Google Account.
- In the navigation panel, select “Security“.
- Under “Signing in to Google“, select “2-Step Verification > Get Started“.
- Follow the on-screen steps.
You may create an app password after enabling 2-step verification.
- Open your Google Account.
- In the navigation panel, select “Security“.
- Under “Signing in to Google”, select “App Passwords“.
- Choose mail in the Select App field. Give the device a name, such as ESP32, and select “Other“. Then, click on “Generate“. When you use ESP32 or ESP8266 to send emails, a window with a password will pop up. You'll need that password later, even though it says you don't need to remember it.
You should now have an app password that you'll use to send emails from the ESP32 code.
Check out how to create an app password if you're using another email provider. A quick Google search for “your_email_provider + create app password” should provide the instructions.
Gmail SMTP Server Settings
If you’re using a Gmail account, these are the SMTP Server details:
![Official Arduino Starter Kit [K000007] (English Projects Book) - 12 DIY Projects with All Necessary Electronic Components and Instructions - origianl kit by Arduino from Italy](https://m.media-amazon.com/images/I/51fPv6DsjQL.jpg)
- SMTP Server: smtp.gmail.com
- SMTP username: Complete Gmail address
- SMTP password: Your Gmail password
- SMTP port (TLS): 587
- SMTP port (SSL): 465
- SMTP TLS/SSL required: yes
Outlook SMTP Server Settings
For Outlook accounts, these are the SMTP Server settings:
- SMTP Server: smtp.office365.com
- SMTP Username: Complete Outlook email address
- SMTP Password: Your Outlook password
- SMTP Port: 587
- SMTP TLS/SSL Required: Yes
Live or Hotmail SMTP Server Settings
For Live or Hotmail accounts, these are the SMTP Server settings:
- SMTP Server: smtp.live.com
- SMTP Username: Complete Live/Hotmail email address
- SMTP Password: Your Windows Live Hotmail password
- SMTP Port: 587
- SMTP TLS/SSL Required: Yes
You need to search for its SMTP Server settings if you're using another email service. You now have everything you need to get started send email from ESP8266 NodeMCU board.
In your Arduino IDE, go to File > Examples > ESP-Mail-Client and play about with the examples—you'll need to enter your email data (sender and recipient accounts), the SMTP server settings, and your SSID and password.
Send an Email with HTML or Raw Text with ESP8266
The code below sends an email containing HTML or raw text over an SMTP server. The ESP8266, for example, sends an email once when it boots. The code should then be able to be modified and integrated into your own projects.
Don't upload the code just yet; you'll need to make some changes to make it work for you.
/*
LEDEdit PRO
Complete project details at:
- ESP32: https://lededitpro.com/send-email-from-esp32-via-smtp-server/
- ESP8266: https://lededitpro.com/send-email-from-esp8266-nodemcu-via-smtp-server/
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files.
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
Example adapted from: https://github.com/mobizt/ESP-Mail-Client
*/
// To send Emails using Gmail on port 465 (SSL), you need to create an app password: https://support.google.com/accounts/answer/185833
#include <Arduino.h>
#if defined(ESP32)
#include <WiFi.h>
#elif defined(ESP8266)
#include <ESP8266WiFi.h>
#endif
#include <ESP_Mail_Client.h>
#define WIFI_SSID "REPLACE_WITH_YOUR_SSID"
#define WIFI_PASSWORD "REPLACE_WITH_YOUR_PASSWORD"
#define SMTP_HOST "smtp.gmail.com"
#define SMTP_PORT 465
/* The sign in credentials */
#define AUTHOR_EMAIL "YOUR_EMAIL@XXXX.com"
#define AUTHOR_PASSWORD "YOUR_EMAIL_PASS"
/* Recipient's email*/
#define RECIPIENT_EMAIL "RECIPIENTE_EMAIL@XXXX.com"
/* The SMTP Session object used for Email sending */
SMTPSession smtp;
/* Callback function to get the Email sending status */
void smtpCallback(SMTP_Status status);
void setup(){
Serial.begin(115200);
Serial.println();
Serial.print("Connecting to AP");
WiFi.begin(WIFI_SSID, WIFI_PASSWORD);
while (WiFi.status() != WL_CONNECTED){
Serial.print(".");
delay(200);
}
Serial.println("");
Serial.println("WiFi connected.");
Serial.println("IP address: ");
Serial.println(WiFi.localIP());
Serial.println();
/** Enable the debug via Serial port
* none debug or 0
* basic debug or 1
*/
smtp.debug(1);
/* Set the callback function to get the sending results */
smtp.callback(smtpCallback);
/* Declare the session config data */
ESP_Mail_Session session;
/* Set the session config */
session.server.host_name = SMTP_HOST;
session.server.port = SMTP_PORT;
session.login.email = AUTHOR_EMAIL;
session.login.password = AUTHOR_PASSWORD;
session.login.user_domain = "";
/* Declare the message class */
SMTP_Message message;
/* Set the message headers */
message.sender.name = "ESP";
message.sender.email = AUTHOR_EMAIL;
message.subject = "ESP Test Email";
message.addRecipient("Sara", RECIPIENT_EMAIL);
/*Send HTML message*/
String htmlMsg = "<div style=\"color:#2f4468;\"><h1>Hello World!</h1><p>- Sent from ESP board</p></div>";
message.html.content = htmlMsg.c_str();
message.html.content = htmlMsg.c_str();
message.text.charSet = "us-ascii";
message.html.transfer_encoding = Content_Transfer_Encoding::enc_7bit;
/*
//Send raw text message
String textMsg = "Hello World! - Sent from ESP board";
message.text.content = textMsg.c_str();
message.text.charSet = "us-ascii";
message.text.transfer_encoding = Content_Transfer_Encoding::enc_7bit;
message.priority = esp_mail_smtp_priority::esp_mail_smtp_priority_low;
message.response.notify = esp_mail_smtp_notify_success | esp_mail_smtp_notify_failure | esp_mail_smtp_notify_delay;*/
/* Set the custom message header */
//message.addHeader("Message-ID: <abcde.fghij@gmail.com>");
/* Connect to server with the session config */
if (!smtp.connect(&session))
return;
/* Start sending Email and close the session */
if (!MailClient.sendMail(&smtp, &message))
Serial.println("Error sending Email, " + smtp.errorReason());
}
void loop(){
}
/* Callback function to get the Email sending status */
void smtpCallback(SMTP_Status status){
/* Print the current status */
Serial.println(status.info());
/* Print the sending result */
if (status.success()){
Serial.println("----------------");
ESP_MAIL_PRINTF("Message sent success: %d\n", status.completedCount());
ESP_MAIL_PRINTF("Message sent failled: %d\n", status.failedCount());
Serial.println("----------------\n");
struct tm dt;
for (size_t i = 0; i < smtp.sendingResult.size(); i++){
/* Get the result item */
SMTP_Result result = smtp.sendingResult.getItem(i);
time_t ts = (time_t)result.timestamp;
localtime_r(&ts, &dt);
ESP_MAIL_PRINTF("Message No: %d\n", i + 1);
ESP_MAIL_PRINTF("Status: %s\n", result.completed ? "success" : "failed");
ESP_MAIL_PRINTF("Date/Time: %d/%d/%d %d:%d:%d\n", dt.tm_year + 1900, dt.tm_mon + 1, dt.tm_mday, dt.tm_hour, dt.tm_min, dt.tm_sec);
ESP_MAIL_PRINTF("Recipient: %s\n", result.recipients.c_str());
ESP_MAIL_PRINTF("Subject: %s\n", result.subject.c_str());
}
Serial.println("----------------\n");
}
}As well as setting the sender email, SMTP Server details, recipient, and message, you will need to insert your network credentials.
How the Code Works
This code has been modified from a library example. The code in the example is well-commented, so you can understand what each line of code does. Let's take a look at the relevant parts that you need or may need to update.
First, insert your network credentials in the following lines:
#define WIFI_SSID "REPLACE_WITH_YOUR_SSID"
#define WIFI_PASSWORD "REPLACE_WITH_YOUR_PASSWORD"Put in your SMTP server settings. If you're sending emails using a Gmail account, these are the settings:
#define SMTP_HOST "smtp.gmail.com"
#define SMTP_PORT 465Fill in the sender's email sign-in credentials (full email and APP password you already created).
#define AUTHOR_EMAIL "YOUR_EMAIL@XXXX.com"
#define AUTHOR_PASSWORD "YOUR_EMAIL_PASS"Insert the recipient email:
#define RECIPIENT_EMAIL "RECIPIENTE_EMAIL@XXXX.com"Set the message headers in setup() by including the following lines: sender name, sender email, email topic, and recipient name and email:
/* Set the message headers */
message.sender.name = "ESP";
message.sender.email = AUTHOR_EMAIL;
message.subject = "ESP Test Email";
message.addRecipient("Sara", RECIPIENT_EMAIL);Set the message content (raw text) in the textMsg variable in the following lines:
//Send raw text message
String textMsg = "Hello World! - Sent from ESP board";
message.text.content = textMsg.c_str();
message.text.charSet = "us-ascii";
message.text.transfer_encoding = Content_Transfer_Encoding::enc_7bit;You should insert your HTML line in the htmlMsg variable if you wish to transmit HTML text instead of plain text. Uncomment the following lines:
/*Send HTML message*/
/*String htmlMsg = "<div style=\"color:#2f4468;\"><h1>Hello World!</h1><p>- Sent from ESP board</p></div>";
message.html.content = htmlMsg.c_str();
message.html.content = htmlMsg.c_str();
message.text.charSet = "us-ascii";
message.html.transfer_encoding = Content_Transfer_Encoding::enc_7bit;*/Finally, the following lines send the message:
if (!MailClient.sendMail(&smtp, &message))
Serial.println("Error sending Email, " + smtp.errorReason());Demonstration
Transfer the code to your ESP8266. After uploading, open the serial monitor at 115200 baud.
If everything goes as planned, you should see a message similar to this in the Serial Monitor.
Check your email account. You should have received an email from your ESP8266 board.
If the option to send a message using HTML text is set, the message will look like this:
This is the email you should get if you enabled raw text messages.
Send Attachments via Email with ESP8266 (Arduino IDE)
This section will show you how to send attachments in ESP8266 emails. We'll show you how to send text or image files. This might be useful to send a.txt file with sensor readings from the past several hours or for other purposes.
The files you intend to send should be saved on the ESP8266 filesystem (SPIFFS or LittleFS). You may also save attachments to a microSD card, but we won't cover that subject in this tutorial.
Setting the Filesystem
You should save files on the ESP8266 filesystem before sending them over email. SPIFFS or LittleFS may be used. Using the Arduino IDE, you will need to install a Filesystem Uploader Plugin to upload files to the filesystem. Depending on the filesystem you wish to use, read one of the following tutorials and install the plugin:
- Install ESP8266 SPIFFS Filesystem Uploader in Arduino IDE
- Install ESP8266 LittleFS Filesystem Uploader in Arduino IDE
To learn how to upload files to LittleFS while using VS Code and PlatformIO, follow the next tutorial:
ESP8266 NodeMCU with VS Code and PlatformIO: Upload Files to Filesystem (LittleFS)
IMPORTANT
Note: You need to edit the library files (ESP_Mail_FS.h) to use that specific filesystem when using LittleFS with the ESP-Mail-Client library. If you wish to use LittleFS, please read the following section: Otherwise, you may skip forward to this section.
Edit the Library Files to use LittleFS
The ESP-Mail-Client library's default filesystem is SPIFFS. You may skip this section if you wish to use SPIFFS. Otherwise, keep reading to learn how to edit the library to use LittleFS instead.
To use LittleFS, you must edit the ESP_Mail_FS.h file.
Go to the Libraries folder in your Arduino installation. It is located on the following path in my case (yours may be similar):
C:\Users\USERNAME\Documents\Arduino\librariesGo to ESP-Mail-Client-master > src and open the ESP_Mail_FS.h file with a text editor.
Locate the following section:
Replace it with the following:
#if defined(ESP32)
#define ESP_Mail_DEFAULT_FLASH_FS SPIFFS
#endif
#if defined(ESP8266)
#include <LittleFS.h>
#define ESP_Mail_DEFAULT_FLASH_FS LittleFS
#endifThis way, it uses the SPIFFS filesystem by default for the ESP32 and LittleFS for the ESP8266.
Save the file. Now the library will use LittleFS as the default filesystem for the ESP8266.
Upload Files to the Filesystem
Create and save a new Arduino sketch. To see the Sketch folder, go to Sketch > Show Sketch folder. Create a folder named data within the Arduino sketch folder. Add a.png and a.txt files to your data folder.
Alternatively, you can click here to download the project folder.
Note: Your files must be named image.png and text_file.txt using the default code, or you may modify the code to import files with different names.
We’ll be sending these files:
Your folder structure should look as follows (download project folder):
After moving the files to the data folder, open the Arduino IDE and go to Tools > ESP8266 Sketch Data Upload or ESP8266 LittleFS Data Upload, depending on the filesystem, and wait for the files to be uploaded.
In the debugging window, you should see a success message. Move on to the next section if the files were uploaded successfully.
Code
The following code sends an email that includes a .txt file and a picture. Make sure to insert your sender's email address as well as your recipient's email address before you upload the code.
/*
LEDEdit PRO
Complete project details at:
- ESP8266: https://lededitpro.com/send-email-from-esp8266-nodemcu-via-smtp-server/
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files.
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
Example adapted K. Suwatchai (Mobizt): https://github.com/mobizt/ESP-Mail-Client Copyright (c) 2021 mobizt
*/
// To send Emails using Gmail on port 465 (SSL), you need to create an app password: https://support.google.com/accounts/answer/185833
// The file systems for flash and sd memory can be changed in ESP_Mail_FS.h.
#include <Arduino.h>
#include <ESP8266WiFi.h>
#include <ESP_Mail_Client.h>
#define WIFI_SSID "REPLACE_WITH_YOUR_SSID"
#define WIFI_PASSWORD "REPLACE_WITH_YOUR_PASSWORD"
#define SMTP_HOST "smtp.gmail.com"
/** The smtp port e.g.
* 25 or esp_mail_smtp_port_25
* 465 or esp_mail_smtp_port_465
* 587 or esp_mail_smtp_port_587
*/
#define SMTP_PORT 465
/* The log in credentials */
#define AUTHOR_EMAIL "YOUR_EMAIL@XXXX.com"
#define AUTHOR_PASSWORD "YOUR_EMAIL_PASS"
/* Recipient's email*/
#define RECIPIENT_EMAIL "RECIPIENTE_EMAIL@XXXX.com"
/* The SMTP Session object used for Email sending */
SMTPSession smtp;
/* Callback function to get the Email sending status */
void smtpCallback(SMTP_Status status);
void setup(){
Serial.begin(115200);
Serial.println();
Serial.print("Connecting to AP");
WiFi.begin(WIFI_SSID, WIFI_PASSWORD);
while (WiFi.status() != WL_CONNECTED){
Serial.print(".");
delay(200);
}
Serial.println("");
Serial.println("WiFi connected.");
Serial.println("IP address: ");
Serial.println(WiFi.localIP());
Serial.println();
if (!LittleFS.begin()) {
// Uncomment to use SPIFFS
//if (!SPIFFS.begin()) {
Serial.println("An error has occurred while mounting the filesystem");
}
else{
Serial.println("Filesystem mounted successfully");
}
/** Enable the debug via Serial port
* none debug or 0
* basic debug or 1
*/
smtp.debug(1);
/* Set the callback function to get the sending results */
smtp.callback(smtpCallback);
/* Declare the session config data */
ESP_Mail_Session session;
/* Set the session config */
session.server.host_name = SMTP_HOST;
session.server.port = SMTP_PORT;
session.login.email = AUTHOR_EMAIL;
session.login.password = AUTHOR_PASSWORD;
session.login.user_domain = "";
/* Declare the message class */
SMTP_Message message;
/* Enable the chunked data transfer with pipelining for large message if server supported */
message.enable.chunking = true;
/* Set the message headers */
message.sender.name = "ESP";
message.sender.email = AUTHOR_EMAIL;
message.subject = "Email with attachments";
message.addRecipient("Sara", RECIPIENT_EMAIL);
String htmlMsg = "This message contains attachments: image and text file.";
message.html.content = htmlMsg.c_str();
message.html.charSet = "utf-8";
message.html.transfer_encoding = Content_Transfer_Encoding::enc_qp;
message.priority = esp_mail_smtp_priority::esp_mail_smtp_priority_normal;
message.response.notify = esp_mail_smtp_notify_success | esp_mail_smtp_notify_failure | esp_mail_smtp_notify_delay;
/* The attachment data item */
SMTP_Attachment att;
/** Set the attachment info e.g.
* file name, MIME type, file path, file storage type,
* transfer encoding and content encoding
*/
att.descr.filename = "image.png";
att.descr.mime = "image/png";
att.file.path = "/image.png";
att.file.storage_type = esp_mail_file_storage_type_flash;
att.descr.transfer_encoding = Content_Transfer_Encoding::enc_base64;
/* Add attachment to the message */
message.addAttachment(att);
message.resetAttachItem(att);
att.descr.filename = "text_file.txt";
att.descr.mime = "text/plain";
att.file.path = "/text_file.txt";
att.file.storage_type = esp_mail_file_storage_type_flash;
att.descr.transfer_encoding = Content_Transfer_Encoding::enc_base64;
/* Add attachment to the message */
message.addAttachment(att);
/* Connect to server with the session config */
if (!smtp.connect(&session))
return;
/* Start sending the Email and close the session */
if (!MailClient.sendMail(&smtp, &message, true))
Serial.println("Error sending Email, " + smtp.errorReason());
}
void loop(){
}
/* Callback function to get the Email sending status */
void smtpCallback(SMTP_Status status){
/* Print the current status */
Serial.println(status.info());
/* Print the sending result */
if (status.success()){
Serial.println("----------------");
ESP_MAIL_PRINTF("Message sent success: %d\n", status.completedCount());
ESP_MAIL_PRINTF("Message sent failled: %d\n", status.failedCount());
Serial.println("----------------\n");
struct tm dt;
for (size_t i = 0; i < smtp.sendingResult.size(); i++){
/* Get the result item */
SMTP_Result result = smtp.sendingResult.getItem(i);
time_t ts = (time_t)result.timestamp;
localtime_r(&ts, &dt);
ESP_MAIL_PRINTF("Message No: %d\n", i + 1);
ESP_MAIL_PRINTF("Status: %s\n", result.completed ? "success" : "failed");
ESP_MAIL_PRINTF("Date/Time: %d/%d/%d %d:%d:%d\n", dt.tm_year + 1900, dt.tm_mon + 1, dt.tm_mday, dt.tm_hour, dt.tm_min, dt.tm_sec);
ESP_MAIL_PRINTF("Recipient: %s\n", result.recipients);
ESP_MAIL_PRINTF("Subject: %s\n", result.subject);
}
Serial.println("----------------\n");
}
}How the code works
We'll just take a look at the relevant parts to send attachments since this code is pretty similar to the previous one.
In the setup(), you need to initialize the filesystem: SPIFFS or LittleFS.
if (!LittleFS.begin()) {
// Uncomment to use SPIFFS
//if (!SPIFFS.begin()) {
Serial.println("An error has occurred while mounting the filesystem");
}
else{
Serial.println("Filesystem mounted successfully");
}You need to create an attachment as follows:
/* The attachment data item */
SMTP_Attachment att;Then, add the attachment details: filename, MIME type, file path, file storage type, and transfer encoding. We're sending the image file in the following lines:
att.descr.filename = "image.png";
att.descr.mime = "image/png";
att.file.path = "/image.png";
att.file.storage_type = esp_mail_file_storage_type_flash;
att.descr.transfer_encoding = Content_Transfer_Encoding::enc_base64;Finally, add the attachment to the message:
message.addAttachment(att);If you want to send multiple attachments, you need to call the following line after adding the previous attachment:
message.resetAttachItem(att);Then, enter the details of the other attachment (text file):
att.descr.filename = "text_file.txt";
att.descr.mime = "text/plain";
att.file.path = "/text_file.txt";
att.file.storage_type = esp_mail_file_storage_type_flash;
att.descr.transfer_encoding = Content_Transfer_Encoding::enc_base64;And add this attachment to the message:
message.addAttachment(att);Finally, you just need to send the message as you did with the previous example:
if (!MailClient.sendMail(&smtp, &message, true))
Serial.println("Error sending Email, " + smtp.errorReason());Demonstration
After uploading the code, open the Serial Monitor at a 115200 baud rate. If everything goes as planned, you should see a message similar to this on the Serial Monitor.
If you go to your inbox, you should get the message with the two attachments:
Conclusion
In this tutorial, you learned how to send emails with the ESP8266 NodeMCU board using an SMTP server. You've already learned how to send HTM text, raw text, and attachments.
Now, you're going to modify the code and include it in your own projects. For example, it may be useful to send a .txt file with the last hour's sensor readings, notifications when motion is detected, and much more.
We hope you find this tutorial useful. Thanks for reading.
