SendGrid api/v3/mail/send接口custom_args字段支持值及对象约束咨询

SendGrid官方文档对api/v3/mail/send接口的custom_args字段描述存在错误——文档声称该字段接受字符串类型，但实际调用时仅支持对象类型，传入字符串会触发类型错误。

该字段可传入的对象需遵循以下约束：

• 必须是标准JSON键值对结构，键为字符串类型
• 值仅支持字符串、数字、布尔值三种基础类型，不允许嵌套对象、数组或其他复杂数据结构
• 键名只能包含字母、数字、下划线（_）、连字符（-）和点号（.），禁止使用空格及特殊符号
• 整个custom_args对象的总大小不得超过10KB（10240字节），超出会触发接口报错
• 避免使用sendgrid_前缀的键名，这类为SendGrid保留键，可能被系统忽略或覆盖

错误请求示例 #

curl https://api.sendgrid.com/v3/mail/send -X POST -H 'Authorization: Bearer [redacted]' \
-H 'content-type: application/json' \
-d '{ 
  "personalizations": [ { "to": [ { "email": "you@you.you" } ] } ], 
  "from": { "email": "me@me.me" }, 
  "content": [{ "type": "text/plain", "value": "sample payload" }], 
  "subject": "test subj", 
  "custom_args": "this is a string" 
}'

错误返回示例 #

{"errors":[{"message":"Invalid type. Expected: object, given: string.","field":"custom_args","help":"http://sendgrid.com/docs/API_Reference/Web_API_v3/Mail/errors.html#message.custom_args"}]}

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