search

karastojko / mailio

mailio is a cross platform C++ library for MIME format and SMTP, POP3, IMAP protocols. It is based on the standard C++ 17 and Boost library.
Other
387 stars 104 forks source link
c-plus-plus-11 email imap library mime pop3 smtp

readme

mailio

C++ License Conan Center Vcpkg

中文文档

mailio is a cross platform C++ library for MIME format and SMTP, POP3 and IMAP protocols. It is based on the standard C++ 17 and Boost library.

Examples

To send a mail, one has to create message object and set it's attributes as author, recipient, subject and so on. Then, an SMTP connection is created by constructing smtp (or smtps) class. The message is sent over the connection:

message msg;
msg.from(mail_address("mailio library", "mailio@gmail.com"));
msg.add_recipient(mail_address("mailio library", "mailio@gmail.com"));
msg.subject("smtps simple message");
msg.content("Hello, World!");

smtps conn("smtp.gmail.com", 587);
conn.authenticate("mailio@gmail.com", "mailiopass", smtps::auth_method_t::START_TLS);
conn.submit(msg);

To receive a mail, a message object is created to store the received message. Mail can be received over POP3 or IMAP, depending of mail server setup. If POP3 is used, then instance of pop3 (or pop3s) class is created and message is fetched:

pop3s conn("pop.mail.yahoo.com", 995);
conn.authenticate("mailio@yahoo.com", "mailiopass", pop3s::auth_method_t::LOGIN);
message msg;
conn.fetch(1, msg);

Receiving a message over IMAP is analogous. Since IMAP recognizes folders, then one has to be specified, like inbox:

imaps conn("imap.gmail.com", 993);
conn.authenticate("mailio@gmail.com", "mailiopass", imap::auth_method_t::LOGIN);
message msg;
conn.fetch("inbox", 1, msg);

More advanced features are shown in examples directory, see below how to compile them.

Note for Gmail users: it might be needed to register mailio as a trusted application. Follow the Gmail instructions to add it and use the generated password for all three protocols.

Note for Zoho users: if 2FA is turned on, then instead of the primary password, the application password must be used. Follow Zoho instructions to add mailio as trusted application and use the generated password for all three protocols.

Setup

mailio library is supposed to work on all platforms supporting C++ 17 compiler, Boost 1.81 or newer and CMake build tool. The platforms tested so far are Linux, Windows, FreeBSD, MacOS, Cygwin, MinGW and the compilers are Gcc, Microsoft Visual C++ and Clang.

There are several ways to build mailio: by cloning the repo and using Cmake, by using Vcpkg or xmake.

CMake

Ensure that OpenSSL, Boost and CMake are in the path. If they are not in the path, one could use CMake options -DOPENSSL_ROOT_DIR, -DBOOST_ROOT and Boost_INCLUDE_DIRS to set them. Boost must be built with the OpenSSL support. If it cannot be found in the path, set the path explicitly via library-path and include parameters of b2 script (after bootstrap finishes). Both static and dynamic libraries should be built in the build directory.

If one wants to specify a non-default installation directory, say /opt/mailio, then the option -DCMAKE_INSTALL_PREFIX should be used. If a user does not have privileges for the default directories, then it must specify one by using this CMake variable.

Other available options are BUILD_SHARED_LIBS (whether a shared or static library shall be built, by default a shared lib is built), MAILIO_BUILD_DOCUMENTATION (if Doxygen documentation is generated, by default is on) and MAILIO_BUILD_EXAMPLES (if examples are built, by default is on).

Linux, FreeBSD, MacOS, Cygwin

From the terminal go into the directory where the library is downloaded to, and execute:

mkdir build
cd ./build
cmake ..
make install

Installing the project ensures that the test project has also the auxiliary files copied, required by several tests.

Microsoft Windows/Visual Studio

From the command prompt go into the directory where the library is downloaded, and execute:

mkdir build
cd .\build
cmake ..

A solution file will be built, open it from Visual Studio and build the project. To install it, build the INSTALL project of the mailio solution, it copies also auxiliary files required by several tests.

Microsoft Windows/MinGW

Open the command prompt by using the open_distro_window.bat script, and execute:

mkdir build
cd .\build
cmake.exe .. -G "MinGW Makefiles"
make install

Vcpkg

Install Vcpkg and run:

vcpkg install mailio

Tests are not available as an option in this case. Use the CMake way to build them.

Features

Issues and improvements

The library is tested on valid mail servers, so probably there are negative test scenarios that are not covered by the code. In case you find one, please contact me. Here is a list of issues known so far and planned to be fixed in the future.

Contributors

Thanks to all people who contribute to the project by improving the source code, report problems and propose new features. Here is a list from the Git history, in case I missed someone please let me know.

References

Contact

In case you find a bug, please drop me a mail to contact (at) alepho.com. Since this is my side project, I'll do my best to be responsive.