Node.js/Express环境下Sendgrid API v3动态模板添加邮件附件的实现方法

这部分完全依靠Sendgrid动态交易模板的原生能力实现，不需要额外写服务端逻辑：

• 打开Sendgrid控制台的动态模板管理页，定位到需要挂载固定附件的对应模板，进入最新版本的编辑界面
• 在编辑器右侧侧边栏，找到和「邮件主题」「发件人地址」平级的「Attachments」配置入口，上传需要固定挂载的文件，自定义设置附件的展示文件名、对应MIME类型后，保存为新的模板版本
• 后续调用API发信时，你完全按照原有逻辑传{{{data}}}动态变量即可，不需要在请求体里加任何附件相关字段，配置好的固定附件会自动随每封通过该模板发出的邮件投递到收件人邮箱

注意：该配置是和模板版本强绑定的，配置完成后要确保你API调用时指定的templateId对应到了刚保存的新版本，避免附件跟随旧版本丢失。模板内置附件和API传入的动态附件是共存关系，不会互相覆盖。

这部分只需要在原有发信请求的基础上，按照Sendgrid API v3的规范补充附件字段即可，完全不改动你现有动态模板变量的传参逻辑。

核心规则 #

Sendgrid API v3要求传入的附件内容必须是无格式前缀的Base64编码字符串，附件配置字段和dynamicTemplateData（也就是你传动态变量的字段）是同层级的独立配置项，不需要把附件内容嵌到模板变量里。

实际Node/Express场景代码示例 #

（用你当前已经在用的官方@sendgrid/mail SDK举例，和你现有代码完全兼容）

const sgMail = require('@sendgrid/mail');
// 原有SDK初始化逻辑保留，不做改动
sgMail.setApiKey(process.env.SENDGRID_API_KEY);

// 以用户购买电子书的业务流程为例
async function sendOrderMailAfterPurchase(user, ebookBuffer) {
  const requestBody = {
    to: user.email,
    from: 'noreply@your-domain.com',
    // 原有模板ID配置不变
    templateId: 'd-你的模板ID字符串',
    // 原有动态变量传参逻辑完全不变，你之前用的{{{data}}}全放在这里
    dynamicTemplateData: {
      userName: user.name,
      orderNo: user.orderNo,
      downloadDeadline: '2024-12-31',
    },
    // 新增动态附件配置，和dynamicTemplateData平级
    attachments: [
      {
        // 直接把读取到的文件Buffer转Base64，不要加`data:application/pdf;base64,`这类前缀
        content: ebookBuffer.toString('base64'),
        filename: 'your-purchased-ebook.pdf',
        type: 'application/pdf',
        disposition: 'attachment' // 明确标记为附件，避免被识别为内嵌资源
      }
    ]
  };

  // 原有发送逻辑不变
  await sgMail.send(requestBody);
}

实际踩坑提示 #

• Sendgrid单封邮件的所有附件总大小（Base64编码后）不能超过10MB，如果你的电子书文件过大，需要提前压缩，否则会触发发信接口报错
• 不需要把附件内容传到动态模板变量里，模板的变量解析逻辑无法处理附件结构，直接在请求顶层配置attachments即可
• 如果你同时启用了模板内置的固定附件，API传入的动态附件会和模板固定附件自动合并投递，不会出现丢失或覆盖的问题
• 如果你没有用SDK，而是直接用Express内置的fetch/axios调Sendgrid原生v3接口，只需要在请求JSON里添加和personalizations、template_id同层级的attachments数组，结构和上面代码里的字段完全一致

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