POST https://api.sendify.dingstore.cn/dmx/v2/contacts
认证
在Authorization 请求头中使用 Bearer API Key：
Authorization: Bearer YOUR_TOKEN
请勿在前端代码、公开仓库或日志中保存真实 API Key。
请求体
Content-Type：application/json
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
email | string | 是 | 联系人的邮件地址 |
tagNames | array<string> | 否 | 要添加到联系人的标签名称列表。保留已有标签，仅添加本次列表中的新标签 |
customFields | array<object> | 否 | 自定义字段值 |
autoCreateTags | boolean | 否 | 标签不存在时是否自动创建，默认为 false |
conflictPolicy | enum<string> | 否 | 联系人已存在时的处理策略，默认创建失败 |
customFields 对象
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
fieldName | string | 是 | 自定义字段名称。字段必须已存在且唯一；不存在或匹配不唯一时请求失败 |
fieldValue | string | 否 | 自定义字段值 |
标签自动创建
autoCreateTags 控制 tagNames 中不存在的标签如何处理：
false：请求中存在未命中的标签名称时，请求失败。true：自动创建不存在的标签，并将其添加到联系人。
联系人冲突策略
| 值 | 行为 |
|---|---|
CONTACT_CONFLICT_POLICY_FAIL_IF_EXISTS | 联系人已存在时返回冲突错误，不更新联系人 |
CONTACT_CONFLICT_POLICY_UPDATE_IF_EXISTS | 按 email 更新已有联系人；保留已有标签，仅追加本次提交的新标签 |
请求体示例
{
"email": "string",
"tagNames": [
"string"
],
"customFields": [
{
"fieldName": "string",
"fieldValue": "string"
}
],
"autoCreateTags": true,
"conflictPolicy": "CONTACT_CONFLICT_POLICY_FAIL_IF_EXISTS"
}
请求示例
- cURL
- TypeScript
- Python
curl -X POST \
"https://api.sendify.dingstore.cn/dmx/v2/contacts" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"email": "string",
"tagNames": ["string"],
"customFields": [
{
"fieldName": "string",
"fieldValue": "string"
}
],
"autoCreateTags": true,
"conflictPolicy": "CONTACT_CONFLICT_POLICY_FAIL_IF_EXISTS"
}'
const response = await fetch(
"https://api.sendify.dingstore.cn/dmx/v2/contacts",
{
method: "POST",
headers: {
Authorization: "Bearer YOUR_TOKEN",
"Content-Type": "application/json",
},
body: JSON.stringify({
email: "string",
tagNames: ["string"],
customFields: [
{
fieldName: "string",
fieldValue: "string",
},
],
autoCreateTags: true,
conflictPolicy: "CONTACT_CONFLICT_POLICY_FAIL_IF_EXISTS",
}),
}
);
const data = await response.json();
console.log(data);
import requests
url = "https://api.sendify.dingstore.cn/dmx/v2/contacts"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
"Content-Type": "application/json",
}
payload = {
"email": "string",
"tagNames": ["string"],
"customFields": [
{
"fieldName": "string",
"fieldValue": "string",
}
],
"autoCreateTags": True,
"conflictPolicy": "CONTACT_CONFLICT_POLICY_FAIL_IF_EXISTS",
}
response = requests.post(url, headers=headers, json=payload)
print(response.status_code)
print(response.text)
成功响应
HTTP200 返回创建或更新后的联系人：
| 字段 | 类型 | 说明 |
|---|---|---|
contact | object | 联系人对象 |
contact.id | string | 联系人 ID |
contact.email | string | 邮件地址 |
contact.tagNames | array<string> | 标签名称列表 |
contact.customFields | array<object> | 自定义字段值 |
contact.customFields[].fieldName | string | 自定义字段名称 |
contact.customFields[].fieldValue | string | 自定义字段值 |
contact.createTime | string (date-time) | 创建时间 |
响应示例
{
"contact": {
"id": "string",
"email": "string",
"tagNames": [
"string"
],
"customFields": [
{
"fieldName": "string",
"fieldValue": "string"
}
],
"createTime": "string"
}
}
错误响应
| HTTP 状态码 | 说明 |
|---|---|
401 | 访问未授权，请检查是否传递了正确的 Bearer API Key |
403 | 无 API 访问权限，请检查 API Key 的权限配置 |