OfficeIMO.Email 完整指南:不装 Outlook,如何读取 PST、MSG 与 EML 邮件并提取正文与附件
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 原文
}
两点注意:
- 正文格式选择策略:做文本分析、搜索或 AI 处理时优先取
Body.Text;要还原排版(加粗、表格、内嵌图片引用)再取Body.Html。 - 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。
五、批量工作流:一次读取多封符合条件的邮件
如果只是"从一个本地文件里按条件挑出若干封邮件",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 扩展属性一个都不少。
