How to Get Started with Aspose.Email FOSS for C++

Aspose.Email FOSS for C++ is a library for reading and writing Outlook MSG files, EML messages, and CFB containers. It has no third-party dependencies and requires only a C++17 compiler and CMake.

Step 1 — Clone and Add to Your CMake Project

git clone https://github.com/aspose-email-foss/Aspose.Email-FOSS-for-Cpp.git

Add the library as a subdirectory and link it in your CMakeLists.txt:

add_subdirectory(Aspose.Email-FOSS-for-Cpp)
target_link_libraries(your_target PRIVATE AsposeEmailFoss::AsposeEmailFoss)

The library uses only the C++ standard library and has no third-party dependencies. GCC 9+, Clang 10+, and MSVC 2019+ are reported as supported in the project README.

Step 2 — Read an MSG File

Include the mapi_message header and open a file with mapi_message::from_stream():

#include <fstream>
#include <iostream>
#include "aspose/email/foss/msg/mapi_message.hpp"

int main()
{
    std::ifstream input("sample.msg", std::ios::binary);
    auto message = aspose::email::foss::msg::mapi_message::from_stream(input);

    std::cout << "Subject: " << message.subject() << '\n';
    std::cout << "From: "    << message.sender_email_address() << '\n';
    std::cout << "Body: "    << message.body() << '\n';

    for (const auto& recipient : message.recipients())
        std::cout << "To: " << recipient.email_address << '\n';

    for (const auto& attachment : message.attachments())
        std::cout << "Attachment: " << attachment.filename
                  << " (" << attachment.mime_type << ")\n";
}

mapi_message::from_stream() parses the MSG file’s CFB container and exposes all MAPI properties through typed accessor methods. No Microsoft Outlook installation is required.

Step 3 — Create a New MSG File

Use mapi_message::create() to build a message in memory, set sender and recipient fields, and save to disk with save():

#include <fstream>
#include "aspose/email/foss/msg/mapi_message.hpp"

int main()
{
    auto message = aspose::email::foss::msg::mapi_message::create(
        "Meeting Notes", "Please find the agenda attached.");

    message.set_sender_name("Alice");
    message.set_sender_email_address("alice@example.com");
    message.add_recipient("bob@example.com", "Bob");
    message.add_attachment(
        "agenda.txt",
        std::vector<std::uint8_t>{'I', 't', 'e', 'm', ' ', '1'},
        "text/plain");

    std::ofstream output("meeting_notes.msg", std::ios::binary);
    message.save(output);
}

mapi_message::create() produces an in-memory message. save() accepts a file path, an std::ostream, or no arguments (returning a std::vector<std::uint8_t>).

Step 4 — Convert EML to MSG (and Back)

Load an EML file with mapi_message::load_from_eml(), then serialize to MSG with save(). The round-trip preserves subject, plain-text body, HTML body property, sender, recipients, and attachments:

#include <filesystem>
#include <iostream>
#include "aspose/email/foss/msg/mapi_message.hpp"

int main()
{
    // EML → MSG
    auto message = aspose::email::foss::msg::mapi_message::load_from_eml(
        std::filesystem::path("message.eml"));

    std::cout << "Subject: " << message.subject() << '\n';
    message.save(std::filesystem::path("converted.msg"));

    // MSG → EML round-trip
    auto loaded = aspose::email::foss::msg::mapi_message::from_file(
        std::filesystem::path("converted.msg"));
    loaded.save_to_eml(std::filesystem::path("roundtrip.eml"));

    std::cout << "Saved converted.msg and roundtrip.eml\n";
}

Common Issues and Fixes

Binary mode not set on the stream. Opening a file with std::ifstream input("file.msg") without std::ios::binary may cause Windows line-ending translation that corrupts the CFB container. Pass std::ios::binary for both input and output streams.

Linker error: AsposeEmailFoss::AsposeEmailFoss not found. Verify that add_subdirectory(Aspose.Email-FOSS-for-Cpp) appears before target_link_libraries(...) in your CMakeLists.txt, and that the subdirectory name matches the cloned folder exactly.

C++17 not enabled. The library requires C++17 features. If the compiler reports errors about structured bindings or std::filesystem, add set(CMAKE_CXX_STANDARD 17) at the top of your CMakeLists.txt before the add_subdirectory call.

Empty subject or body after reading. Some MSG files store text in Unicode properties while others use ANSI code-page properties. message.subject() and message.body() return the string from whichever storage is present; check message.html_body() if message.body() is empty.

load_from_eml throws on malformed EML. Verify that the EML file uses RFC 5322 line endings (CRLF) and has valid MIME headers. The library does not silently skip malformed headers.

Frequently Asked Questions

Does the library require Microsoft Outlook or any COM component?

No. Aspose.Email FOSS for C++ uses its own CFB and MAPI parser and has no third-party dependencies. It works on Linux, macOS, and Windows without Outlook installed.

Which formats can I read and write?

MSG (Outlook Message), EML (RFC 5322 / MIME), and CFB (Compound File Binary) are supported for both reading and writing. TNEF (winmail.dat), IMAP, SMTP, and POP3 are not supported.

How do I save a message to bytes instead of a file?

Call save() or save_to_eml() with no arguments. Both return std::vector<std::uint8_t>, which you can write to any buffer or stream.

What C++ standard is required?

C++17. The library uses std::filesystem, std::optional, and other C++17 standard-library features. GCC 9+, Clang 10+, and MSVC 2019+ are listed as supported in the project README.

Is there a package manager release (vcpkg, Conan)?

Version 0.1.0 is distributed via source only. Clone the repository and use add_subdirectory as shown above. Package manager manifests may be added in future releases.