如何通过Microsoft Graph API为邮件添加自定义标头

你之前尝试的几种方案存在几个认知偏差，对应修正后即可实现需求：

• 直接修改InternetMessageHeaders字段后上传Message实体的方案不可行：该字段在Graph API中为只读属性，无论新建还是更新邮件接口，传入的该字段值都会被服务端忽略或部分丢弃，且直接上传结构化Message对象时，不会自动携带原始MIME中的多部分正文、内嵌附件、非公开标头等内容，必然出现数据丢失。
• 调用更新接口直接修改邮件标头的思路确实不可行，官方接口定义中未开放标头修改权限。

推荐方案：使用单值扩展属性实现跟踪需求 #

如果你的核心诉求是给邮件打可识别的跟踪标记、方便定位邮件最终位置，完全不需要修改原始MIME标头，使用Graph原生的单值扩展属性即可，该方案对原邮件无侵入，不会丢失任何数据，稳定性最高，实现步骤如下：

• 提前为你的应用生成一个固定的GUID，用于定义自定义扩展属性，属性ID格式为String {你的GUID} Name {你原本的自定义标头名}。
• 移动邮件前，调用邮件更新接口，给目标邮件写入对应扩展属性的值。
• 直接调用Graph原生的邮件移动接口将邮件移入目标文件夹即可，不需要删除原邮件再重建。

对应实现代码：

// 替换为你自己生成的固定GUID，不要每次运行生成新值
private const string TrackPropertyId = "String 11111111-1111-1111-1111-111111111111 Name X-Your-Track-Header";

// 给邮件打跟踪标记
await graphServiceClient.Users[user.Id].Messages[message.Id]
    .Request()
    .UpdateAsync(new Message
    {
        SingleValueExtendedProperties = new List<SingleValueExtendedProperty>
        {
            new SingleValueExtendedProperty
            {
                Id = TrackPropertyId,
                Value = headerValue
            }
        }
    });

// 直接移动邮件到目标文件夹，无需删除重建
await graphServiceClient.Users[user.Id].Messages[message.Id]
    .Move(destinationMailFolder.Id)
    .Request()
    .PostAsync();

后续查询邮件时，直接通过该扩展属性筛选即可匹配到对应目标邮件，完全满足跟踪需求。

备选方案：上传修改后的MIME流 #

如果你必须将自定义标头写入邮件实际的MIME头中，可以使用MIME流上传接口，你之前没找到对应方法是因为使用了错误的上传端点：不要调用结构化Message的Add接口，直接将修改完标头的MIME内容作为流上传到目标文件夹即可，对应SDK调用代码：

// modifiedMimeStream 为你添加完自定义标头后的MIME内容流
Message uploadedMessage = await graphServiceClient.Users[user.Id]
    .MailFolders[destinationMailFolder.Id]
    .Messages
    .Request()
    .AddAsync(modifiedMimeStream);

// 上传成功后删除原邮件
await graphServiceClient.Users[user.Id].Messages[message.Id].Request().DeleteAsync();

注意：该方案会生成一封全新的邮件存入目标文件夹，原邮件的接收时间、已读状态等属性可能发生变化，部分邮件客户端会将其识别为新邮件触发提醒，非必要不推荐使用。

内容的提问来源于stack exchange，提问作者TheLethalCoder