Skip to content

xreef/EMailSender

BranchesTags

Repository files navigation

EMailSender Library v4.1.1

EMailSender Logo

arduino-library-badge

A comprehensive Arduino library for sending emails via SMTP with full support for attachments, multiple recipients, and secure connections (SSL/TLS and STARTTLS).

Author: Renzo Mischianti
Website: www.mischianti.org
GitHub: @xreef

📚 Documentation & Tutorials

Complete tutorials and articles available on mischianti.org:

General Documentation

Platform-Specific Guides

ESP32 Tutorials

ESP8266 Tutorials

Arduino Tutorials

STM32 Tutorials

Raspberry Pi Pico (RP2040) Tutorials

Advanced Topics

📋 Table of Contents

✨ Features

Core Features

  • ✅ Send emails via SMTP with authentication
  • ✅ Multiple recipients (To, Cc, Bcc)
  • ✅ HTML and plain text email formats
  • ✅ File attachments from various storage systems
  • ✅ Base64 encoding for attachments
  • ✅ Custom sender name and email address
  • ✅ Subject and message body customization

Security Features (NEW in v4.0.0)

  • ✅ STARTTLS support (Port 587) - NEW!
  • ✅ Implicit SSL/TLS (Port 465)
  • ✅ Multiple authentication methods:
    • AUTH LOGIN (default)
    • AUTH PLAIN (SASL)
    • CRAM-MD5 (ESP32 only)
  • ✅ Internal SSLClient for STARTTLS on ESP32/ESP8266
  • ✅ OpenSLab SSLClient (BearSSL) for Ethernet shields

Network Support

  • Multiple network interfaces (WiFi, Ethernet, WiFiNINA)
  • Automatic IP resolution
  • Connection retry logic
  • Flexible client configuration

🎯 Supported Platforms

Platform WiFi Ethernet SSL/TLS STARTTLS
ESP32 ✅ ✅ ✅ ✅
ESP8266 ✅ ✅ ✅ ✅
Arduino Mega/Uno ❌ ✅ ❌ ❌
Arduino SAMD ✅ ✅ ✅ ✅
STM32 ❌ ✅ ✅ ✅
Raspberry Pi Pico (RP2040) ✅ ✅ ✅ ✅

⚠️ IMPORTANTE - Arduino Mega/Uno e SSL/TLS:

Arduino Mega and Uno DO NOT support SSL/TLS due to severe RAM limitations:

  • Arduino Mega has only 8KB of RAM
  • Arduino Uno has only 2KB of RAM
  • BearSSL for SSL/TLS requires at least 24KB of RAM for encryption buffers

Alternative solutions for Arduino Mega/Uno:

  1. ✅ Use non-secure SMTP (port 25) - Works but not recommended
  2. ✅ Use a local SMTP relay - Configure a local server that handles SSL
  3. ✅ Switch to ESP32/ESP8266 - They have more RAM and native SSL/TLS support
  4. ✅ Use Arduino SAMD (MKR WiFi 1010) - Has 32KB RAM and supports SSL/TLS

Arduino Mega/Uno examples in this library use only non-secure SMTP!

🌐 Supported Network Interfaces

  • WiFi (ESP32/ESP8266) - WiFiClient / WiFiClientSecure
  • WiFi (SAMD/MBED) - WiFiNINA library
  • Ethernet W5100/W5200/W5500 - Standard Ethernet library
  • Ethernet ENC28J60 - UIPEthernet library
  • Ethernet with SSL - SSLClient wrapper for secure connections

💾 Supported Storage Systems

Internal Storage (Microcontroller Flash)

  • SPIFFS (ESP32, ESP8266)
  • LittleFS (ESP32, ESP8266, RP2040)
  • FFAT (ESP32)
  • SPIFM (SPI Flash with Adafruit_SPIFlash)
  • Generic stream and string attachments option

External Storage (SD/microSD Cards)

  • SD (Standard SD library)
  • SdFat (Version 1.x for RP2040/ESP8266)
  • SdFat2 (Version 2.x for modern platforms)

📦 Installation

Arduino IDE

  1. Open Arduino IDE
  2. Go to Sketch > Include Library > Manage Libraries
  3. Search for "EMailSender"
  4. Click Install

PlatformIO

Add to your platformio.ini:

lib_deps = 
    xreef/EMailSender@^4.1.1

Manual Installation

  1. Download the library from GitHub
  2. Extract to Arduino libraries folder
  3. Restart Arduino IDE

🚀 Basic Usage

Simple Email (ESP32 with Gmail)

#include <WiFi.h>
#include <EMailSender.h>

const char* ssid = "YOUR_SSID";
const char* password = "YOUR_PASSWORD";

// Gmail SMTP configuration
EMailSender emailSend("[email protected]", 
                      "your_app_password",
                      "[email protected]", 
                      "Your Name",
                      "smtp.gmail.com", 
                      587);  // Port 587 for STARTTLS

void setup() {
  Serial.begin(115200);
  
  // Connect to WiFi
  WiFi.begin(ssid, password);
  while (WiFi.status() != WL_CONNECTED) {
    delay(500);
    Serial.print(".");
  }
  Serial.println("\nWiFi Connected!");
  
  // Prepare email message
  EMailSender::EMailMessage message;
  message.subject = "Test Email";
  message.message = "Hello from ESP32!";
  
  // Send email
  EMailSender::Response resp = emailSend.send("[email protected]", message);
  
  Serial.println("Sending status: ");
  Serial.println(resp.code);
  Serial.println(resp.desc);
  Serial.println(resp.status);
}

void loop() {
  // Nothing here
}

HTML Email with Multiple Recipients

EMailSender::EMailMessage message;
message.subject = "HTML Email Test";
message.message = "<h1>Hello!</h1><p>This is an <b>HTML</b> email.</p>";
message.mime = MIME_TEXT_HTML;  // Set MIME type to HTML

// Multiple recipients
const char* recipients[] = {
  "[email protected]",
  "[email protected]",
  "[email protected]"
};

EMailSender::Response resp = emailSend.send(recipients, 3, message);

Email with CC and BCC

// Array with To, Cc, and Bcc addresses
const char* allRecipients[] = {
  "[email protected]",      // To (1)
  "[email protected]",      // Cc (1)
  "[email protected]"      // Bcc (1)
};

// send(recipients, numTo, numCc, numBcc, message)
EMailSender::Response resp = emailSend.send(allRecipients, 1, 1, 1, message);

Debug Mode

Enable debugging by uncommenting in EMailSenderKey.h:

#define EMAIL_SENDER_DEBUG
#define DEBUG_PRINTER Serial

This will print detailed SMTP communication to Serial Monitor.

Memory Issues

For boards with limited RAM (like Arduino Uno):

  • Disable attachments if not needed
  • Use smaller email messages
  • Consider using Arduino Mega or ESP32

Gmail Specific Issues

"Username and Password not accepted"

  1. Enable 2-Factor Authentication
  2. Generate App Password at https://myaccount.google.com/apppasswords
  3. Use the 16-character app password (no spaces)

"Less secure app access"

  • Google removed "less secure apps" option
  • You MUST use App Passwords now
  • Regular account password will not work

Change log v4.x

  • 10/11/2025: v4.1.1
    • Minor enhancements: add support for Stream and String attachments improvements
    • Bug fixes: edge-case encoding issues and small fixes in attachment handling
  • 10/11/2025: v4.1.0
    • Add Stream and File as attachement type
    • Bug fix for size and encoding
  • 09/10/2025: v4.0.1 Fix path sslclient and code completition of Platformio

📝 Changelog v4.0.0 - 08/10/2025

New Features

  • ✨ STARTTLS support (Port 587) - Full implementation for secure email on port 587
  • ✨ Internal SSLClient integration - Built-in SSL/TLS support for ESP32/ESP8266
  • ✨ Enhanced authentication - Better support for various SMTP auth methods
  • ✨ Improved error handling - More detailed error messages and responses

Improvements

  • 🔧 Unified client handling for better compatibility
  • 🔧 Better SSL/TLS handshake management
  • 🔧 Improved EHLO/HELO command handling with multi-line response support
  • 🔧 Enhanced connection retry logic
  • 🔧 Better memory management for large attachments

Bug Fixes

  • 🐛 Fixed SSLClient initialization on ESP32
  • 🐛 Fixed STARTTLS upgrade sequence
  • 🐛 Corrected client scope issues
  • 🐛 Fixed BearSSL integration for Ethernet shields

Breaking Changes

  • ⚠️ Minimum Arduino IDE version: 1.8.x
  • ⚠️ ESP32 core minimum version: 2.0.x (for WiFiClientSecure improvements)
  • ⚠️ Some internal API changes (user-facing API remains compatible)

Migration from v3.x

Most code will work without changes. If using custom client configuration:

  • Check EMailSenderKey.h for new defines
  • Update authentication methods if using advanced features
  • Test STARTTLS connections (port 587) for better security

Change log v3.x

  • 14/03/2024: v3.0.14 Support Arduino GIGA WiFi
  • 31/10/2023: v3.0.13 Fix wrong implementation of FORCE_DISABLE_SSL
  • 17/10/2023: v3.0.12 Fix warnigs of variable not used #43 thanks to @Patriboom @Andy2015
  • 16/02/2023: v3.0.11 Add support for Ethernet_Generic
  • 20/01/2023: v3.0.10 Add the management of ESP8266SdFat library on Raspberry Pi Pico #forum
  • 17/01/2023: v3.0.10 Add the mamagement of auto check of response number #36 thanks to @HACKER-3000 @H3
  • 13/01/2023: v3.0.9 Fix external storage error 404 (#forum
  • 05/01/2023: v3.0.8 Fix distribution list examples
  • 22/09/2022: v3.0.7 Add Raspberry Pi Pico W and rp2040 boards
  • 20/09/2022: v3.0.7 Add STM32 management for https://github.com/rogerclarkmelbourne/Arduino_STM32 library.
  • 16/08/2022: v3.0.6 Add FORCE_DISABLE_SSL to disable SSL if present
  • 19/07/2022: v3.0.5 Additional fix on additional response management (#26)
  • 12/07/2022: v3.0.4 Fixed attachment issue on SPIFFS and LittleFS
  • 06/07/2022: v3.0.3 Manage multiple response message after connect and HELO (#26)
  • 03/06/2022: v3.0.2 Add possibility to set additionalResponseLineOnConnection with void setAdditionalResponseLineOnConnection(uint8_t numLines = 0), needed if on connection you receive 220 response as error, and add Ethernet2.
  • 20/05/2022: v3.0.1 Put inside scope the client declaration (if you don't use SSLClient) for backward compatibility
  • 18/05/2022: v3.0.0 Add STM32 support. Add SSLClient integration to allow send Email with SSL encryption (like Gmail) with ethernet (tested with STM32, ESP32, w5500, and enc28j60), minor fix
  • 12/04/2021: v2.4.3 Fix multiple email send
  • 12/04/2021: v2.4.1 Add support for LITTLEFS and Ffat on esp32 and fix certificate verification from esp32 core 1.0.5
  • 18/03/2021: v2.3.0 Add support for LittleFS on esp8266
  • 02/01/2021: v2.2.0 New support for SAMD devices via WiFiNINA (Arduino MKR WiFi 1010, Arduino Vidor 4000 and Arduino UNO WiFi Rev.2 ecc.).
  • 01/01/2021: v2.1.5 Add possibility to use EHLO instead of HELO, and SASL login.
  • 27/11/2020: v2.1.4 Add more constructor to allow more structure for distribution list (now const char*, char* and String array are supported)

📄 License

MIT License - See LICENSE file for details

Copyright (c) 2017-2025 Renzo Mischianti

🤝 Contributing

Contributions are welcome! Please:

  1. Fork the repository
  2. Create a feature branch
  3. Commit your changes
  4. Push to the branch
  5. Create a Pull Request

📞 Support

👤 Author

Renzo Mischianti

⭐ Show Your Support

If this library helped your project, please ⭐ star it on GitHub!

Made with ❤️ by Renzo Mischianti

About

Arduino, esp32, Esp8266 EMailSender with Arduino IDE, simple library to send email via smtp with attachments.

www.mischianti.org/category/my-libraries/emailsender-send-email-with-attachments/

Topics

arduino esp8266 esp32 wifi email-sender smtp arduino-library raspberry ethernet gmail-smtp wifinina rp2040 pico-w

Resources

Readme

License

MIT license
Activity

Stars

78 stars

Watchers

9 watching

Forks

31 forks
Report repository

Releases 27

Release v4.1.1: Hotfix for ESP8266 and Raspberry Pi Pico Latest
Nov 22, 2025
+ 26 releases

Packages

No packages published

Contributors 7

Languages