OfficeIMO.Email 完整指南:不装 Outlook,如何读取 PST、MSG 与 EML 邮件并提取正文与附件

原创2026-11-06 11:46:482,162 阅读

OfficeIMO.Email 完整指南:不装 Outlook,如何读取 PST、MSG 与 EML 邮件并提取正文与附件

OfficeIMO.Email 是 OfficeIMO 项目中完全托管、无 COM 依赖的 .NET 邮件处理库,让你在没有安装 Outlook 的服务器上直接读取 PST 邮件档案、MSG 单封邮件和 EML 文件,轻松提取正文文本、HTML 内容与全部附件。本文面向新手,用最少代码带你完成从"安装包"到"批量导出"的完整实战。

一、OfficeIMO.Email 能读哪些邮件格式?📬

OfficeIMO.Email 是纯 .NET 实现(MIT 协议),不依赖 Outlook、COM 组件或任何第三方邮件解析器,跨 Windows / Linux / macOS 运行。它覆盖的邮件相关格式相当全面:

格式 文件示例 说明
EML / MIME .eml、.mime 标准邮件文件,支持多段正文、编码头、内嵌资源
MSG / OFT .msg、.oft Outlook 单封邮件与邮件模板,含 MAPI 扩展属性
TNEF .tnef、winmail.dat Outlook 的"乱码附件"问题源头,可解析其内容
PST / OST .pst、.ost Outlook 邮件档案/离线存储,支持超大文件的按需读取
OLM / EMLX .olm、.emlx Outlook for Mac、Apple Mail 导出格式
Mbox .mbox、.mbx 传统 Unix 邮件箱归档
日历与联系人 .ics、.vcf、.vcs 独立的 iCalendar 与 vCard 文档

单封消息类格式(EML/MSG/OFT/TNEF)共用同一个 EmailDocument 模型;PST、OST、OLM、EMLX、Mbox 等"容器类"格式则由 Store 会话 API 统一提供文件夹、条目与查询能力。

安装只需一条命令:

dotnet add package OfficeIMO.Email

二、3 行代码读取 MSG 或 EML 邮件(快速上手)

对单封邮件,最直接的入口是 EmailDocument.Load——无论来源是 .msg、.eml 还是 winmail.dat,读出来的都是同一个对象:

using OfficeIMO.Email;

EmailDocument message = EmailDocument.Load("message.msg");

Console.WriteLine(message.Subject);        // 主题
Console.WriteLine(message.From);           // 发件人
Console.WriteLine(message.Body.Text);      // 纯文本正文

EmailDocument 上可用的核心字段:

  • Subject / From / Recipients:主题、发件人与收件人集合(To/Cc/Bcc 分开标记)
  • Body.Text / Body.Html / Body.Rtf:正文的三种备选表示
  • Attachments:附件集合,每个附件带 FileName、ContentType、Length、Content(字节内容)
  • Date / ReceivedDate:发送时间与接收时间
  • Mapi:MSG/TNEF/PST 中未投影到常规字段的原始 MAPI 属性

💡 读取逻辑位于 EmailDocument.cs,加载与保存实现见 EmailDocument.IO.cs。

三、提取正文与附件:最常用的两个实战操作

3.1 提取正文:Text、Html、Rtf 三选一

一封邮件的正文往往同时存在纯文本、HTML 和 RTF 多个版本(multipart MIME 的备选表示),EmailBody 会全部保留:

EmailDocument message = EmailDocument.Load("invoice.eml");

if (!string.IsNullOrEmpty(message.Body.Text)) {
    Console.WriteLine(message.Body.Text);      // 纯文本,适合归档与检索
} else if (!string.IsNullOrEmpty(message.Body.Html)) {
    Console.WriteLine(message.Body.Html);     // HTML 原文
}

两点注意:

  1. 正文格式选择策略:做文本分析、搜索或 AI 处理时优先取 Body.Text;要还原排版(加粗、表格、内嵌图片引用)再取 Body.Html。
  2. HTML 是不可信内容:官方文档明确提示 raw HTML bodies remain untrusted。如需渲染展示,应安装可选的 HTML 桥接包 OfficeIMO.Email.Html,它会按策略做净化与本地资源解析。

3.2 批量提取附件到目录

不想自己处理 MIME 解码、文件名冲突和嵌套附件?EmailAttachmentExtractor 一步完成,并返回带哈希与来源信息的结果清单:

EmailAttachmentExtractionResult extraction = EmailAttachmentExtractor.Extract(message, "attachments",
    new EmailAttachmentExtractionOptions(recurseEmbeddedMessages: true));

foreach (EmailAttachmentExtractionEntry entry in extraction.Entries) {
    Console.WriteLine($"{entry.SourcePath}: {entry.OutputPath} {entry.Sha256}");
}

这个提取器内置了安全默认值:单次最多访问 1000 个条目、单文件 64 MiB、整次操作 256 MiB,且不会覆盖已存在的文件;链接型附件(只存路径不存内容)永远不会被打开,隐藏附件默认排除。实现位于 EmailAttachmentExtractor.cs。

如果只要文本类附件(CSV、TXT、代码等),还有专门的 EmailAttachmentTextReader.Read,它会尊重 MIME 中声明的 charset、处理 BOM,并给出解码诊断,避免乱码。

四、读取大 PST 邮件档案:不加载整个文件的正确姿势

PST 动辄几个 GB,正确做法是用 EmailStoreSession 打开"会话"——它只构建受限的目录索引,正文和附件都按需解码,内存占用与邮件数量无关:

using OfficeIMO.Email.Store;

using EmailStoreSession session = EmailStoreSession.Open("archive.pst");

// 浏览文件夹并枚举前 100 条
EmailStoreFolderInfo inbox = session.Folders.Single(f => f.Name == "Inbox");
foreach (EmailStoreItemReference reference in session.EnumerateItems(
    new EmailStoreEnumerationOptions(folderId: inbox.Id, maxItems: 100))) {
    EmailStoreItem item = session.ReadItem(reference);
    Console.WriteLine(item.Document.Subject);
}

对超大档案,更实用的是先搜索、再读取命中项——搜索阶段只读取少量摘要属性,扫描与结果数量都有上限:

using EmailStoreSession session = EmailStoreSession.Open("mailbox.pst");

foreach (EmailStoreSearchResult match in session.Search(new EmailStoreQuery(
    folderId: session.Folders.Single(f => f.Name == "Inbox").Id,
    subjectContains: "季度报告",
    since: DateTimeOffset.UtcNow.AddYears(-1),
    maxItemsScanned: 250_000,
    maxResults: 100))) {
    Console.WriteLine($"{match.Summary.ReceivedAt:u} {match.Summary.Subject}");

    EmailStoreItem item = session.ReadItem(match.Reference);
    // 正文、收件人、附件在这里才被投影出来
}

需要全文级别的检索时,session.SearchContent 支持按正文、附件名搜索,返回命中字段、文本片段和可续查的检查点(checkpoint),适合分批扫描几十 GB 的档案。

Store 的架构设计说明见 Store/README.md,PST 二进制结构的解析实现在 Store/Pst/PstStoreReader.cs。

OfficeIMO.Email 提取出的文档正文示例:一封包含日期、预约信息与会面安排的客户信函,展示了从邮件或文档中提取纯文本正文后的可读效果

五、批量工作流:一次读取多封符合条件的邮件

如果只是"从一个本地文件里按条件挑出若干封邮件",EmailMessageReader 是最省心的高层 API——它读完即关源文件,返回的邮件视图不持有文件句柄:

using OfficeIMO.Email;

EmailMessageReadResult result = EmailMessageReader.Read("Archive.pst",
    new EmailMessageQuery { SubjectContains = "invoice", First = 25 });

foreach (EmailMessage message in result.Messages) {
    Console.WriteLine(message.Subject + " | " + message.TextBody);

    // 只导出 PDF 附件
    EmailAttachmentExtractionResult files = message.SaveAttachments("attachments/" + message.ExportName,
        message.Attachments.Where(a => a.FileName?.EndsWith(".pdf", StringComparison.OrdinalIgnoreCase) == true)
            .Select(a => a.Index));

    // 把整封邮件另存为 EML
    message.Save("copies/" + message.ExportName + ".eml");
}

EmailMessageQuery 支持的条件包括:Folder(文件夹路径或唯一名称)、SubjectContains / SenderContains(不区分大小写的片段匹配)、Since / Before(按接收时间,回落到发送时间)、First(默认返回 1000 条)。查询条件的完整定义见 EmailMessageReader.cs。

如果要对同一档案反复查询,用 EmailMessageStore.Open(path) 显式持有会话即可,避免每次重复打开。

六、格式互转:读取后换一个格式保存

OfficeIMO.Email 的模型是格式无关的,因此 EML ↔ MSG ↔ OFT ↔ TNEF 之间的转换就是"Load 再 Save":

EmailDocument.Load("source.eml").Save("converted.msg");

Save 会根据目标扩展名自动推断输出格式(.eml / .mime → EML,.msg → MSG,.oft → 模板,.tnef 或 winmail.dat → TNEF)。如果扩展名另有用途,可以显式指定:

message.Save("artifact.bin", EmailFileFormat.OutlookMsg);

需要注意:已知的语义丢失默认会被阻断(例如把带签名的邮件改写成另一种格式会使签名失效)。遇到这种情况,先用 EmailDocumentWriter.AnalyzeConversion 查看诊断报告,确认可接受后再以 EmailConversionLossPolicy.Warn 显式放行——这种"默认拒绝、显式接受"的策略正是该库在数据安全上区别于普通第三方解析器的地方。

Mbox 归档也有专门读写器:EmailMailboxReader.Read("archive.mbox") 读整个归档,ReadEntries 则逐条流式枚举大邮件箱,配合 EmailMailboxWriter 可再写回 mboxo/mboxrd。

七、处理大文件与常见问题的实用建议 ⚡

  • 控制内存:读取大 MSG/PST 时,给 EmailReaderOptions 设置 maxInputBytes、maxAttachmentBytes 等上限;只关心元数据时用 retainAttachmentContent: false,附件字节就不会驻留内存。
  • 超大附件流式读取:EmailStoreItemReadOptions 支持 preferStreamingAttachmentContent: true,附件变成可随时重开的流,按需 CopyToAsync 即可,不必整块载入。
  • 受限诊断:需要自定义限制与结构化错误信息时,用 EmailDocumentReader + EmailReadResult.Diagnostics,它会把每一个警告/错误都暴露为带稳定代码的诊断项,而不是笼统抛异常。
  • 密码保护 PST:PST 的"密码"是校验和机制(防君子不防小人)。EmailStoreReaderOptions 提供 PstPassword 属性用于校验,读取本身不需要真实解密能力。
  • 只读原则:所有读取会话从不修改源文件;OfficeIMO.Email 也明确不提供"原地修复/追加 PST"这类危险操作,任何改写都走"写出新文件 + 语义校验 + 原子替换"的受控路径。
  • 性能预算:解析路径共享一个 ProcessingBudget 操作账本,嵌套解析器(MIME → TNEF → 内嵌 MSG)不会各自重置限额,超限时抛出 EmailLimitExceededException 并携带可操作的诊断信息。

八、目录导览:去哪里找更多细节 🔍

你想了解 去哪里看
包总览与全部 API 示例 OfficeIMO.Email/README.md
PST/OST/OLM/Mbox 存储会话 OfficeIMO.Email/Store/README.md
核心消息模型(主题/正文/附件) OfficeIMO.Email/Model/EmailDocument.cs
高级读取器与限制选项 OfficeIMO.Email/Reading/EmailDocumentReader.cs、EmailReaderOptions.cs
附件提取器 OfficeIMO.Email/Export/EmailAttachmentExtractor.cs
MSG/MAPI 属性解析 OfficeIMO.Email/Msg/MsgReader.cs
mbox 归档读写 OfficeIMO.Email/Mbox/
测试用例(最好的学习材料) OfficeIMO.Email.Tests/
性能基线与测试说明 Docs/officeimo.email-performance.md

一句话总结:单封邮件用 EmailDocument.Load 三行搞定,大档案用 EmailStoreSession 按需搜索,批量挑选用 EmailMessageReader,换格式只需再 Save 一次——全程无需 Outlook,附件、正文、MAPI 扩展属性一个都不少。

登录后查看全文
OfficeIMO