Firebase Trigger Email扩展报错：message非有效对象，邮件无法发送

问题背景 #

在Android Firebase应用中使用Trigger Email扩展发送邮件，已完成以下步骤：

• SendGrid外发服务配置（测试成功）
• 创建email Firestore集合并配置安全规则
• 安装Trigger Email扩展并指定发件人地址

执行代码后Firestore文档成功创建，但邮件未发送，Cloud Functions日志报错：

'message' is not a valid object and no handlebars template has been provided instead

涉及代码：

private HashMap<String, String> emailMap = new HashMap<>();
// ...省略中间代码
spinner.setVisibility(View.INVISIBLE);
Map<String, Object> data = new HashMap<>();
data.put("to", emailaddr);
emailMap.clear();
emailMap.put("subject", getString(R.string.post_alert));
emailMap.put("html", getString(R.string.posted_comment) + NL + NL + WEB_APP + url);
data.put("message", emailMap);
emailRef.add(data)
        .addOnSuccessListener(new OnSuccessListener<DocumentReference>() {
            @Override
            public void onSuccess(DocumentReference documentReference) {
                spinner.setVisibility(View.INVISIBLE);
            }
        })
        .addOnFailureListener(new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception e) {
                Log.w(TAG, "Error writing document", e);
                Toast.makeText(context, e.getLocalizedMessage(), Toast.LENGTH_LONG).show();
                spinner.setVisibility(View.INVISIBLE);
            }
        });

问题原因 #

核心原因是代码中message字段的序列化结构不符合Trigger Email扩展的要求：

• 使用HashMap<String, String>存储message内容，Firestore序列化时可能触发类型匹配异常，导致扩展无法识别为合法的邮件内容对象；
• 扩展要求message对象必须包含至少一个有效内容字段（subject+html/text），且结构严格匹配SendGrid的邮件格式规范。

修复方案 #

1. 修改emailMap的类型 #

将HashMap<String, String>替换为HashMap<String, Object>，确保Firestore序列化时保持正确的对象结构：

// 替换原有的HashMap定义
private HashMap<String, Object> emailMap = new HashMap<>();

2. 验证邮件内容格式 #

确保subject和html都是非空字符串，且html内容无语法错误（比如未闭合的HTML标签）。如果需要纯文本邮件，可添加text字段作为备选：

emailMap.put("text", getString(R.string.posted_comment) + NL + NL + WEB_APP + url);

3. 检查Firestore文档结构 #

手动查看Firestore中创建的email文档，确保结构如下（无多余嵌套或类型错误）：

{
  "to": "recipient@example.com",
  "message": {
    "subject": "邮件主题",
    "html": "邮件HTML内容"
  }
}

4. 额外排查步骤 #

• 在Firestore控制台手动创建一个符合上述格式的文档，测试是否能触发邮件发送，排除代码序列化问题；
• 检查SendGrid控制台的邮件日志，确认是否有请求到达但被拦截（比如收件人无效、发件人未验证）；
• 重新确认Trigger Email扩展的配置，确保COLLECTION_PATH设置为email，发件人地址已通过SendGrid验证。

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