使用Microsoft Graph API发送HTML邮件时背景图片不显示的问题咨询

一、问题原因与配置排查 #

1. 邮件客户端渲染限制：多数主流邮件客户端（如Outlook）的HTML渲染引擎基于Word，不支持通过CSS background-image 引用内嵌附件（cid资源），这是背景图不显示的核心原因——并非Graph API本身不支持内嵌附件，而是客户端兼容性问题。
2. CID引用格式细节：部分客户端要求cid引用需包含尖括号，即HTML中应写为 url('cid:<backgroundImage>')，但即便调整格式，仍无法绕过Outlook等客户端对CSS背景图的限制。
3. 冗余字段说明：hasAttachments 无需手动设置，Graph API会自动根据attachments列表判断，该字段不影响背景图显示。

二、文字叠加图片的替代方案 #

由于CSS背景图在邮件客户端兼容性极差，推荐使用表格布局+内嵌图片+文字层叠加的方案，以下是具体实现：

方案1：HTML原生background属性（兼容部分客户端） #

修改HTML内容为：

<table width="100%" cellpadding="0" cellspacing="0">
  <tr>
    <td background="cid:backgroundImage" style="width: 600px; height: 400px; padding: 20px;">
      <h1>Hello, World!</h1>
      <p>This is the body of the email.</p>
    </td>
  </tr>
</table>

注：该方案仅在Gmail等部分客户端生效，Outlook仍不支持。

方案2：表格嵌套+绝对定位（兼容多数客户端） #

通过嵌套表格，将图片作为底层元素，文字层通过绝对定位覆盖，兼容性更强，示例HTML：

<table width="600" cellpadding="0" cellspacing="0" style="position: relative;">
  <tr>
    <td>
      <img src="cid:backgroundImage" width="600" height="400" style="display: block;" />
      <div style="position: absolute; top: 20px; left: 20px; color: white;">
        <h1>Hello, World!</h1>
        <p>This is the body of the email.</p>
      </div>
    </td>
  </tr>
</table>

修改后的Graph API请求体示例 #

{
  "senderAddress": "sender@abc.com",
  "requestBody": {
    "message": {
      "toRecipients": [
        {
          "emailAddress": {
            "address": "receiver@abc.com"
          }
        }
      ],
      "attachments": [
        {
          "@odata.type": "#microsoft.graph.fileAttachment",
          "name": "backgroundImage.png",
          "contentId": "backgroundImage",
          "isInline": true,
          "contentBytes": "Valid Base 64 String",
          "contentType": "image/png"
        }
      ],
      "subject": "Test Mail",
      "body": {
        "contentType": "html",
        "content": "<table width=\"600\" cellpadding=\"0\" cellspacing=\"0\" style=\"position: relative;\"><tr><td><img src=\"cid:backgroundImage\" width=\"600\" height=\"400\" style=\"display: block;\" /><div style=\"position: absolute; top: 20px; left: 20px; color: white;\"><h1>Hello, World!</h1><p>This is the body of the email.</p></div></td></tr></table>"
      }
    }
  }
}

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