Introduction

This post walks through the core workflow for reading, creating, and converting Outlook MSG files in C++ using Aspose.Email FOSS — a pure C++17, MIT-licensed library with no external dependencies and no COM. You will learn how to read an existing MSG file, inspect its properties, create a new message programmatically, and round-trip between MSG and EML formats.

The library builds identically on Linux, macOS, and Windows. It is distributed as source via GitHub and integrates by cloning the repository and adding it as a CMake subdirectory — no package manager registration is required.

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

Clone the repository into your project’s source tree or a vendor directory:

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

Then reference it in your project CMakeLists.txt using add_subdirectory:

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 the mapi_message header and write a simple program to create a MSG file and convert it to EML:

#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

Run these CMake commands from the project root to configure and compile:

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

Supported Formats

FormatExtensionReadWriteNotes
MSG.msg✓✓Outlook message format
EML.eml✓✓RFC 5322 / MIME email format

CFB note. MSG files are stored internally in Compound File Binary format. The library reads CFB structures transparently when loading .msg files; no separate CFB format class is required.

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