Mailio: A Comprehensive Guide to the Cross-Platform C++ Email Processing Library

1 Overview of Mailio

Mailio is a cross-platform email processing library written in modern C++17. It aims to provide C++ developers with a simple yet powerful API for handling various email-related operations. The design philosophy of this library is to simplify the complexity of email protocols, allowing developers to focus on business logic rather than low-level implementation details.

As a comprehensive email solution, Mailio supports full MIME (Multipurpose Internet Mail Extensions) format handling and implements three main email protocols: SMTP (Simple Mail Transfer Protocol), POP3 (Post Office Protocol version 3), and IMAP (Internet Message Access Protocol). This means you can use Mailio to create, send, receive, and even manage emails on a server, meeting various email processing needs.

One notable feature of Mailio is its robust cross-platform support, allowing it to run seamlessly on various operating systems such as Linux, FreeBSD, macOS, and Windows (including Cygwin and MinGW environments). Regardless of the development environment you are working in, Mailio provides a consistent interface and behavior. Additionally, Mailio is built on the Boost library, leveraging this mature and widely tested C++ library to enhance its functionality and reliability.

1.1 Core Features

The Mailio library offers a range of powerful features that make it an ideal choice for C++ email processing:

Complete Protocol Support: Mailio not only supports the SMTP protocol for sending emails but also supports POP3 and IMAP protocols for receiving and managing emails. The comprehensive support for the IMAP protocol, including message retrieval, deletion, searching, obtaining mailbox statistics, and managing folders, allows you to build fully functional email client applications.
Flexible Authentication and Encryption: The library supports unencrypted, SSL, and TLS versions of SMTP, POP3, and IMAP interfaces, including the STARTTLS command. This allows you to choose the appropriate connection method based on the requirements of the email server, ensuring secure communication.
Comprehensive MIME Support: Mailio can parse and construct complex multi-level MIME structures, supporting various encoding formats, including 7bit, 8bit, binary, Base64, and Quoted Printable. This means you can easily handle emails containing various types of data, including text, images, audio, and video.
Strict Parsing Mode: Mailio provides options for loose or strict email format parsing, allowing you to balance compatibility and standard compliance based on your needs.

1.2 Applicable Scenarios

The Mailio library is suitable for various application scenarios:

Enterprise Automated Email Systems: Integrating email notifications, report sending, and other functionalities within enterprise internal systems.
Personal Email Client Development: Building fully functional desktop or command-line email clients.
Email Notifications in Cloud Services: Integrating email sending and receiving functionalities in cloud services or web applications.
Server-Side Email Processing Services: Developing server-side applications for handling incoming emails.

2 Installation and Configuration

2.1 Dependency Management

Mailio is based on C++17 and the Boost library, so before installing Mailio, ensure that your development environment meets the following requirements:

A compiler that supports C++17 (such as GCC 7.0+, Clang 5.0+, or MSVC 2017+)
Boost library (especially the System, Date Time, and Regex components)
CMake build tool (recommended version 3.12 or higher)

On Ubuntu/Debian systems, you can install the dependencies using the following command:

sudo apt-get install build-essential cmake libboost-all-dev

On macOS, you can use Homebrew:

brew install cmake boost

2.2 Installing via CMake

Mailio recommends using CMake for installation, with the following steps:

Clone the repository:

git clone https://github.com/karastojko/mailio.git
cd mailio

Create a build directory:
```
mkdir build
cd build
```
Configure and compile:
```
cmake ..
make
```
Install the library files:
```
sudo make install
```

2.3 Project Configuration

After installation, you can integrate Mailio into your CMake project:

cmake_minimum_required(VERSION 3.12)
project(MyEmailProject)

find_package(mailio REQUIRED)

add_executable(email_app main.cpp)
target_link_libraries(email_app mailio::mailio)

Or in a non-CMake project, simply link the Mailio library during compilation:

g++ -std=c++17 -o my_app main.cpp -lmailio -lboost_system -lboost_date_time

3 Core Features and Code Examples

3.1 Creating Email Messages

The mailio::message class is one of the cores of Mailio, used for creating and representing email messages. It provides comprehensive functionality for setting the sender, recipient, subject, content, and adding attachments.

Here is an example of creating a simple text email:

#include <mailio/message.hpp>
#include <mailio/mime.hpp>
#include <iostream>

using namespace mailio;
using std::cout;
using std::endl;

int main()
{
    try
    {
        // Create email message object
        message msg;

        // Set basic email information
        msg.from(mail_address("Sender Name", "[email protected]"));
        msg.add_recipient(mail_address("Recipient Name", "[email protected]"));
        msg.subject("This is a test email");
        msg.content("Hello, this is a test email sent using the Mailio library!");

        cout << "Email created successfully!" << endl;
        return 0;
    }
    catch (const std::exception& e)
    {
        cout << "Error: " << e.what() << endl;
        return 1;
    }
}

For more complex scenarios, such as creating an email with attachments:

#include <mailio/message.hpp>
#include <mailio/mime.hpp>
#include <fstream>

using namespace mailio;

int main()
{
    try
    {
        message msg;

        // Set email headers
        msg.from(mail_address("My Application", "[email protected]"));
        msg.add_recipient(mail_address("User", "[email protected]"));
        msg.subject("Email with Attachment");

        // Set email body
        msg.content("Please see the attached report document.");

        // Add attachment
        std::ifstream report_file("report.pdf", std::ios::binary);
        msg.attach(report_file, "report.pdf", mime::media_type_t::APPLICATION, "pdf");

        return 0;
    }
    catch (const std::exception& e)
    {
        std::cout << "Error: " << e.what() << std::endl;
        return 1;
    }
}

3.2 Sending Emails via SMTP

The mailio::smtps class is used to send emails via the SMTP protocol, supporting SSL/TLS encrypted connections. Here is the basic process for sending an email:

#include <mailio/smtp.hpp>
#include <mailio/message.hpp>
#include <iostream>

using namespace mailio;
using std::cout;
using std::endl;

int main()
{
    try
    {
        // Create email message
        message msg;
        msg.from(mail_address("Sender", "[email protected]"));
        msg.add_recipient(mail_address("Recipient", "[email protected]"));
        msg.subject("SMTP Test Email");
        msg.content("This is a test email sent via the SMTP protocol.");

        // Create SMTP connection (using SSL)
        smtps conn("smtp.gmail.com", 587);
        conn.authenticate("[email protected]", "your_password", smtps::auth_method_t::START_TLS);

        // Send email
        conn.submit(msg);

        cout << "Email sent successfully!" << endl;
        return 0;
    }
    catch (const std::exception& e)
    {
        cout << "SMTP Error: " << e.what() << endl;
        return 1;
    }
}

For more complex handling, such as using a local SMTP server or unencrypted connections:

#include <mailio/smtp.hpp>

using namespace mailio;

int main()
{
    try
    {
        message msg;
        msg.from(mail_address("System Administrator", "[email protected]"));
        msg.add_recipient(mail_address("Technical Support", "[email protected]"));
        msg.subject("System Report");
        msg.content("Please see the latest system operation report.");

        // Use unencrypted SMTP connection
        smtp conn("localhost", 25);
        // If the server requires authentication
        // conn.authenticate("username", "password", smtp::auth_method_t::LOGIN);

        conn.submit(msg);

        return 0;
    }
    catch (const std::exception& e)
    {
        std::cout << "Error: " << e.what() << std::endl;
        return 1;
    }
}

3.3 Receiving Emails via POP3

The mailio::pop3s class is used to receive emails via the POP3 protocol, supporting SSL/TLS encryption. Here is an example of receiving and reading emails:

#include <mailio/pop3.hpp>
#include <mailio/message.hpp>
#include <iostream>
#include <vector>

using namespace mailio;
using std::cout;
using std::endl;

int main()
{
    try
    {
        // Create POP3 connection (using SSL)
        pop3s conn("pop.gmail.com", 995);
        conn.authenticate("[email protected]", "your_password");

        // Get mailbox statistics
        auto mailbox_info = conn.statistics();
        cout << "Number of emails in the mailbox: " << mailbox_info.messages_no << endl;
        cout << "Total size of mailbox (bytes): " << mailbox_info.messages_size << endl;

        // Fetch and display the latest email
        if (mailbox_info.messages_no > 0)
        {
            message msg;
            conn.fetch(1, msg);

            cout << "Latest email information:" << endl;
            cout << "Sender: " << msg.from().to_string() << endl;
            cout << "Subject: " << msg.subject() << endl;
            cout << "Content: " << msg.content() << endl;
        }

        return 0;
    }
    catch (const std::exception& e)
    {
        cout << "POP3 Error: " << e.what() << endl;
        return 1;
    }
}

3.4 Managing Emails via IMAP

The mailio::imaps class implements the IMAP protocol, providing richer email management features than POP3. IMAP allows direct management of emails on the server, including reading, deleting, and moving emails.

Here is an example of searching and managing emails via IMAP:

#include <mailio/imap.hpp>
#include <mailio/message.hpp>
#include <iostream>
#include <vector>

using namespace mailio;
using std::cout;
using std::endl;

int main()
{
    try
    {
        // Create IMAP connection (using SSL)
        imaps conn("imap.gmail.com", 993);
        conn.authenticate("[email protected]", "your_password");

        // Select mailbox folder (default is INBOX)
        conn.select("INBOX");

        // Search for emails with specific criteria
        auto search_criteria = "SUBJECT \"Important\"";
        std::vector<unsigned long> message_numbers;
        conn.search(search_criteria, message_numbers);

        cout << "Found " << message_numbers.size() << " emails matching the criteria" << endl;

        // Read the searched emails
        for (auto msg_num : message_numbers)
        {
            message msg;
            conn.fetch(msg_num, msg);

            cout << "Email #" << msg_num << ":" << endl;
            cout << "Sender: " << msg.from().to_string() << endl;
            cout << "Subject: " << msg.subject() << endl;
            cout << "Date: " << msg.date_time().to_string() << endl;
            cout << "---" << endl;
        }

        return 0;
    }
    catch (const std::exception& e)
    {
        cout << "IMAP Error: " << e.what() << endl;
        return 1;
    }
}

IMAP also supports folder management, allowing you to organize emails:

#include <mailio/imap.hpp>
#include <vector>
#include <iostream>

using namespace mailio;

int main()
{
    try
    {
        imaps conn("imap.example.com", 993);
        conn.authenticate("username", "password");

        // Get folder list
        std::vector<std::string> folders;
        conn.list_folders(folders);

        std::cout << "Available folders:" << std::endl;
        for (const auto& folder : folders)
        {
            std::cout << "- " << folder << std::endl;
        }

        // Create new folder
        conn.create_folder("Work");

        // Select specific folder
        conn.select("Work");

        // Move email to new folder
        conn.move_message(1, "Work");

        return 0;
    }
    catch (const std::exception& e)
    {
        std::cout << "Error: " << e.what() << std::endl;
        return 1;
    }
}

4 Advanced Features and Best Practices

4.1 MIME Format Handling

Mailio provides powerful MIME handling capabilities, able to process complex multi-level MIME structures. This is crucial for creating and parsing emails that contain various content types (such as text, HTML, images, and attachments).

Here is an example of creating a multipart email:

#include <mailio/message.hpp>
#include <mailio/mime.hpp>

using namespace mailio;

int main()
{
    try
    {
        message msg;

        // Set basic email headers
        msg.from(mail_address("Sender", "[email protected]"));
        msg.add_recipient(mail_address("Recipient", "[email protected]"));
        msg.subject("Multipart MIME Example");

        // Create multipart content (plain text + HTML)
        msg.content_type(mime::content_type_t::MULTIPART_ALTERNATIVE);

        // Add plain text part
        msg.add_part("text/plain", "This is the plain text version of the email.");

        // Add HTML part
        msg.add_part("text/html", "<html><body><h1>This is the HTML version of the email</h1></body></html>");

        // Add attachment
        std::ifstream image_file("photo.jpg", std::ios::binary);
        msg.attach(image_file, "photo.jpg", mime::media_type_t::IMAGE, "jpeg");

        return 0;
    }
    catch (const std::exception& e)
    {
        std::cout << "Error: " << e.what() << std::endl;
        return 1;
    }
}

4.2 Security Considerations

Mailio provides various security features to help you build secure email applications:

Encrypted Connections: Always prioritize using SSL/TLS encrypted connections (smtps, pop3s, imaps classes) to protect authentication information and email content.
Secure Authentication: Use appropriate authentication methods, such as START_TLS, to ensure the security of the authentication process.
Input Validation: Validate all user inputs to prevent injection attacks.

Here is a complete example using a secure connection:

#include <mailio/smtp.hpp>
#include <mailio/pop3.hpp>
#include <mailio/imap.hpp>
#include <mailio/message.hpp>

using namespace mailio;

void send_secure_email()
{
    // Use encrypted SMTP connection
    smtps smtp_conn("smtp.gmail.com", 587);
    smtp_conn.authenticate("[email protected]", "password", smtps::auth_method_t::START_TLS);

    message msg;
    msg.from(mail_address("Sender", "[email protected]"));
    msg.add_recipient(mail_address("Recipient", "[email protected]"));
    msg.subject("Secure Email");
    msg.content("This is an email sent via a secure connection.");

    smtp_conn.submit(msg);
}

void receive_secure_emails()
{
    // Use encrypted POP3 and IMAP connections
    pop3s pop3_conn("pop.gmail.com", 995);
    pop3_conn.authenticate("[email protected]", "password");

    imaps imap_conn("imap.gmail.com", 993);
    imap_conn.authenticate("[email protected]", "password");

    // Use secure connections for email operations
    // ...
}

4.3 Error Handling and Debugging

Mailio uses C++ exceptions to report errors, and good error handling is crucial for building stable email applications:

#include <mailio/message.hpp>
#include <mailio/smtp.hpp>
#include <mailio/pop3.hpp>
#include <mailio/imap.hpp>
#include <iostream>
#include <fstream>

using namespace mailio;

class EmailManager {
public:
    void send_notification(const std::string& to, const std::string& subject, const std::string& content)
    {
        try
        {
            message msg;
            msg.from(mail_address("Notification System", "[email protected]"));
            msg.add_recipient(mail_address("User", to));
            msg.subject(subject);
            msg.content(content);

            smtps conn("smtp.example.com", 587);
            conn.authenticate("username", "password", smtps::auth_method_t::START_TLS);
            conn.submit(msg);

            std::cout << "Notification sent successfully: " << to << std::endl;
        }
        catch (const smtp_error& e)
        {
            std::cerr << "SMTP Error: " << e.what() << std::endl;
            // Handle SMTP specific errors
        }
        catch (const message_error& e)
        {
            std::cerr << "Message format error: " << e.what() << std::endl;
            // Handle message format errors
        }
        catch (const std::exception& e)
        {
            std::cerr << "General error: " << e.what() << std::endl;
            // Handle other errors
        }
    }

    bool backup_email(const std::string& message_id, const std::string& filename)
    {
        try
        {
            imaps conn("imap.example.com", 993);
            conn.authenticate("username", "password");

            message msg;
            // Fetch email by ID...

            std::ofstream backup_file(filename);
            // Save email to file...

            return true;
        }
        catch (const std::exception& e)
        {
            std::cerr << "Backup failed: " << e.what() << std::endl;
            return false;
        }
    }
};

4.4 Performance Optimization Suggestions

For applications that need to handle a large volume of emails, the following optimization suggestions may be helpful:

Connection Reuse: Reuse SMTP/POP3/IMAP connections whenever possible, rather than creating a new connection for each email.
Batch Operations: Use IMAP’s batch fetching capabilities to reduce the number of network round trips.
Streaming Processing: For large attachments, use streaming to avoid memory exhaustion.
Asynchronous Operations: In GUI applications, consider performing email operations in a background thread.

5 Conclusion

Mailio, as a comprehensive and modern C++ email processing library, provides powerful email handling capabilities through a simple API. Its main advantages include:

Cross-Platform Support: Able to run seamlessly on major operating systems such as Linux, macOS, and Windows.
Comprehensive Protocols: Fully supports SMTP, POP3, and IMAP protocols, meeting various email processing needs.
Standard Compliance: Based on C++17 and the Boost library, the code is modern and reliable.
Flexible MIME Handling: Capable of handling everything from simple text emails to complex multipart MIME messages.
Rich Documentation: Provides detailed API documentation and example code, lowering the learning curve.

Whether developing simple email notification features or building a complete email client, Mailio provides the right tools and interfaces. Its active community and ongoing updates also ensure the project’s long-term viability.