如何在SendGrid邮件活动API复合查询中正确使用CONTAINS关键字？

问题背景 #

需要通过SendGrid Email Activity Feed API实现自动化查询，替代手动登录导出操作，目标查询条件：

• 日期范围：2025/01/02 全天
• 邮件状态：未送达（not_delivered）
• 邮件主题包含"Invoice"

已成功实现前两个条件的API查询，但添加主题过滤时遇到问题：文档未明确CONTAINS关键字在复合查询中的用法，尝试多种方式均失败：

• 追加AND CONTAINS(subject, "Invoice")到现有查询，返回400错误，提示"CONTAINS expects an array or map type as the first argument"
• 单独使用CONTAINS(subject, "Invoice")作为查询参数，同样返回上述400错误
• 移除query参数名仅保留编码后的CONTAINS语句，返回200但未按主题过滤
• 添加文档中的额外括号也无效果

正确解决方案 #

SendGrid的CONTAINS关键字仅适用于数组或映射类型字段（如categories数组），而subject是字符串类型，需使用LIKE操作符配合通配符实现包含匹配。

完整请求示例（编码后URL） #

https://api.sendgrid.com/v3/messages?limit=10&query=status%3D%22not_delivered%22%20AND%20last_event_time%20BETWEEN%20TIMESTAMP%20%222025-01-02T00%3A00%3A00Z%22%20AND%20TIMESTAMP%20%222025-01-02T23%3A59%3A59Z%22%20AND%20subject%20LIKE%20%22%25Invoice%25%22

未编码的原始查询语句 #

status="not_delivered" AND last_event_time BETWEEN TIMESTAMP "2025-01-02T00:00:00Z" AND TIMESTAMP "2025-01-02T23:59:59Z" AND subject LIKE "%Invoice%"

关键说明 #

• 字符串字段的模糊匹配使用LIKE操作符，%表示任意长度的字符（前后都加表示包含指定内容）
• CONTAINS不可用于字符串类型字段，仅针对数组、映射这类复杂类型生效

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