Introduction

Working with Outlook MSG files in C++ has historically required Windows-only COM automation or heavyweight third-party libraries with restrictive licenses. Aspose.Email FOSS for C++ changes that: it is a pure C++17 library with no external dependencies, no COM, and no platform-specific code. It builds identically on Linux, macOS, and Windows.

The library is released under the MIT license and distributed as source via GitHub. You integrate it by cloning the repository and adding it as a CMake subdirectory — no package manager registration is required, and no binaries need to be pre-built.

This post walks through the core workflow: reading an existing MSG file, inspecting its properties, creating a new message programmatically, and round-tripping between MSG and EML formats.

Key Features

Read Existing MSG Files

Use msg_reader to open a .msg file and msg_document to access its structured content. Both classes live in the aspose::email::foss::msg namespace.

#include "aspose/email/foss/msg/msg_reader.hpp"
#include "aspose/email/foss/msg/msg_document.hpp"
#include <filesystem>

namespace aef = aspose::email::foss;

auto reader   = aef::msg::msg_reader::from_file(std::filesystem::path("message.msg"));
auto document = aef::msg::msg_document::from_reader(reader);

msg_reader also has a from_stream overload for reading from an std::istream, which is useful in server-side or pipeline contexts where files are not present on disk.

Create Messages Programmatically

mapi_message::create produces a new in-memory message with a subject and body. You can then set sender details, add recipients, and attach binary or text payloads before saving.

#include "aspose/email/foss/msg/mapi_message.hpp"

namespace aef = aspose::email::foss;

auto msg = aef::msg::mapi_message::create(
    "Quarterly status update",
    "Hello team,\n\nPlease find the rollout summary attached.\n\nRegards");

msg.set_sender_name("Build Agent");
msg.set_sender_email_address("build.agent@example.com");
msg.add_recipient("alice@example.com", "Alice Example");
msg.save(std::filesystem::path("output.msg"));

Convert MSG to EML

mapi_message supports direct MSG-to-EML conversion through the save_to_eml method. EML output conforms to RFC 5322 (MIME), making it compatible with any standard mail client or processing pipeline.

auto loaded = aef::msg::mapi_message::from_file(
    std::filesystem::path("message.msg"), /*strict=*/false);

// Save as EML to a file
loaded.save_to_eml(std::filesystem::path("message.eml"));

// Or capture as bytes
std::vector<std::uint8_t> eml_bytes = loaded.save_to_eml();

Load from EML

The reverse direction is equally straightforward: load_from_eml reads an EML file and produces a mapi_message in memory, which can then be saved back to MSG.

auto from_eml = aef::msg::mapi_message::load_from_eml(
    std::filesystem::path("message.eml"));

from_eml.save(std::filesystem::path("restored.msg"));

Low-Level CFB Access

For advanced use cases — such as reading raw MAPI properties not exposed by the high-level API — cfb_reader gives direct access to the Compound File Binary container that underpins the MSG format.

#include "aspose/email/foss/cfb/cfb_reader.hpp"

namespace aef = aspose::email::foss;

auto cfb = aef::cfb::cfb_reader::from_file(std::filesystem::path("message.msg"));
auto storage_ids = cfb.storage_ids();
auto stream_ids  = cfb.stream_ids();

Quick Start

Step 1 — Clone and Add as Subdirectory

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

In your project CMakeLists.txt:

cmake_minimum_required(VERSION 3.26)
project(my_project)

add_subdirectory(Aspose.Email-FOSS-for-Cpp)

add_executable(my_app main.cpp)
target_link_libraries(my_app PRIVATE AsposeEmailFoss::AsposeEmailFoss)

Step 2 — Include and Use

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

namespace aef = aspose::email::foss;

int main()
{
    // Create a message
    auto msg = aef::msg::mapi_message::create("Hello from C++", "Body text here");
    msg.save(std::filesystem::path("hello.msg"));

    // Round-trip to EML
    auto loaded = aef::msg::mapi_message::from_file(
        std::filesystem::path("hello.msg"), false);
    loaded.save_to_eml(std::filesystem::path("hello.eml"));

    std::cout << "Done\n";
}

Step 3 — Build

cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build

Supported Formats

FormatExtensionReadWrite
MSG (Outlook Message).msg✓✓
EML (RFC 5322 / MIME).eml✓✓
CFB (Compound File Binary).msg, .cfb✓✓

Open Source & Licensing

Aspose.Email FOSS for C++ is released under the MIT license. The full source is available on GitHub at aspose-email-foss/Aspose.Email-FOSS-for-Cpp. Commercial use is permitted without royalties. The library has no runtime dependencies beyond a C++17 compiler and CMake 3.26 or later.

Getting Started