listmonk 如何通过 /api/subscribers/query/lists 按 SQL 查询批量加入或移除列表成员【免费下载链接】listmonkHigh performance, self-hosted, newsletter and mailing list manager with a modern dashboard. Single binary app.项目地址: https://gitcode.com/GitHub_Trending/li/listmonk如果你需要一次性把一批订阅者加入某个列表、或从列表中移除/退订一批订阅者逐个调用 PUT /api/subscribers/lists 会非常低效。listmonk 提供了PUT /api/subscribers/query/lists接口可以基于一个 SQL 表达式或自由文本搜索动态圈定一批订阅者再对这批人执行add、remove或unsubscribe三种批量动作。本文基于 docs/docs/content/apis/subscribers.md 和 docs/docs/content/querying-and-segmentation.md 说明如何构造这次调用以及如何验证执行结果。前提条件API 访问凭证listmonk 的 HTTP API 支持 BasicAuth 或Authorization: token请求头API 用户和 token 在管理后台Admin - Users创建管理见 docs/docs/content/apis/apis.md。示例中api_username:access_token即为你自己的 API 用户名和 tokenhttp://localhost:9000为你的 listmonk 服务地址。用户角色权限要通过 API 管理列表和订阅关系API 用户必须挂载相应的权限。使用query字段SQL 表达式时用户需要subscribers:sql_query权限否则请求会返回 403 Permission Denied见 cmd/subscribers.go 中的权限检查。列表范围权限请求中的源列表list_ids和目标列表target_list_ids会按当前用户的列表权限过滤用户只会被允许操作其有权限的列表。请求体参数接口为PUT /api/subscribers/query/lists请求体为 JSON参数如下来自 subscribers.md 的参数表NameTypeRequiredDescriptionactionstringYes要执行的动作add、remove或unsubscribe。target_list_idsnumber[]Yes匹配到的订阅者要加入或移除的列表 ID 数组。querystringNo过滤订阅者的 SQL 表达式例如subscribers.email LIKE %domain.com。searchstringNo自由文本搜索作用于 name、email 或其他通用文本属性。list_idsnumber[]No可选的源列表 ID把查询过滤范围限定在这些列表内的订阅者。statusstringRequired foradd订阅时设置的订阅状态confirmed、unconfirmed或unsubscribed。subscription_statusstringNo可选的订阅状态过滤作用于list_ids指定的源列表。注意query与search是二选一的圈人方式query是部分 Postgres SQL 表达式表达能力更强可查询属性、时间戳等字段search只是简单文本匹配。可用的 SQL 查询字段query参数中可以引用订阅者表中的以下字段见 querying-and-segmentation.md字段说明subscribers.uuid订阅者随机生成的唯一 IDsubscribers.email订阅者邮箱subscribers.name订阅者姓名subscribers.status状态enabled、disabled、blocklistedsubscribers.attribs任意 JSON 属性通过 Postgres 的-和-操作符访问subscribers.created_at订阅者首次加入的时间戳subscribers.updated_at订阅者最近被修改的时间戳文档给出的常用表达式写法-- 按邮箱精确匹配 subscribers.email somedomain.com -- 按邮箱前缀/后缀模糊匹配 subscribers.email LIKE %domain.com -- 多条件组合 subscribers.email LIKE John% AND subscribers.status blocklisted -- 查询 JSON 属性- 返回文本配合类型转换做数值比较 subscribers.attribs-city Bengaluru AND (subscribers.attribs-projects)::INT 3 -- 查询嵌套 JSON 属性? 操作符检查列表中值的存在性 subscribers.status blocklisted AND (subscribers.attribs-likes_tea)::BOOLEAN true AND subscribers.attribs-stack-languages ? python AND subscribers.attribs-stack-preferred_language go文档建议要写更复杂的 JSON 属性查询可参考 Postgres 的 JSONB 文档。批量加入列表add把邮箱以domain.com结尾的订阅者加入 ID 为 3 的列表状态设为confirmedcurl -u api_username:access_token -X PUT http://localhost:9000/api/subscribers/query/lists \ -H Content-Type: application/json \ --data-raw { query: subscribers.email LIKE \%domain.com\, action: add, target_list_ids: [3], status: confirmed }action为add时必须提供status可选值confirmed、unconfirmed、unsubscribed。如果只想在特定源列表中圈人例如只处理已订阅列表 1 的用户加上list_ids与subscription_statuscurl -u api_username:access_token -X PUT http://localhost:9000/api/subscribers/query/lists \ -H Content-Type: application/json \ --data-raw { query: subscribers.attribs-\city\ \Bengaluru\, action: add, target_list_ids: [3], list_ids: [1, 2], subscription_status: confirmed, status: confirmed }其中list_ids表示只检查这些源列表中的订阅者subscription_status是对源列表订阅状态的过滤。批量移除列表成员remove从 ID 为 3 的列表中移除所有不是domain.com邮箱的订阅者文档中的示例场景curl -u api_username:access_token -X PUT http://localhost:9000/api/subscribers/query/lists \ -H Content-Type: application/json \ --data-raw { query: NOT subscribers.email LIKE \%domain.com\, action: remove, target_list_ids: [3] }remove不需要status参数。unsubscribe动作的参数用法与remove相同区别在于执行的是退订动作而非直接删除订阅关系。注意以上 JSON 中\是 shell 单引号字符串内部的转义写法如果你的请求体放在文件或工具里直接写标准 JSON 字符串即可如query: subscribers.email LIKE %domain.com。验证执行结果接口执行成功时返回 200 与如下响应体文档示例{ data: true }data: true只表示批量动作已执行不返回受影响的订阅者数量。要确认哪些订阅者被加入或移除了列表可以用GET /api/subscribers按同样的条件回查curl -u api_username:access_token -X GET http://localhost:9000/api/subscribers \ --url-query page1 \ --url-query per_page100 \ --url-query querysubscribers.email LIKE %domain.com返回结果中每个订阅者的lists数组会列出其订阅的列表含subscription_status、id、name等可据此核对目标列表是否已出现在匹配订阅者的lists中或其订阅状态是否符合预期。也可以按单个订阅者回查GET /api/subscribers/{subscriber_id}。错误码与常见失败原因按 docs/docs/content/apis/apis.md 的通用错误码约定data: true之外的响应会带 40x/50x 状态码和message字段。与本接口直接相关的几种情况现象原因400action不是add/remove/unsubscribe之一或add时缺少statussubscribers.invalidAction400target_list_ids为空subscribers.errorNoListsGiven400请求参数缺失或值非法通用 400 语义403用户缺少subscribers:sql_query权限而请求中使用了query422请求体包含无法处理的数据另外若 SQL 表达式写错或写成了文档不支持的字段会按通用 4xx/500 处理message中给出错误信息可据此修改表达式重试。下一步需要按 SQL 表达式批量封禁订阅者时用PUT /api/subscribers/query/blocklist需要批量删除订阅者时用POST /api/subscribers/query/delete见 subscribers.md。完整的接口参数定义可参考 docs/swagger/collections.yaml 中的SubscriberQueryRequestschema 和manageSubscriberListsByQuery接口描述。【免费下载链接】listmonkHigh performance, self-hosted, newsletter and mailing list manager with a modern dashboard. Single binary app.项目地址: https://gitcode.com/GitHub_Trending/li/listmonk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
