> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sendify.dingstore.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 创建营销活动

> 创建普通批量邮件营销任务草稿

一次提交完整配置，校验通过后创建当前 API Key 所属用户的普通批量营销活动草稿，并返回营销活动 ID。

```http theme={null}
POST https://api.sendify.dingstore.cn/dmx/v2/campaigns
```

<Note>
  创建营销活动不会生成收件人快照或发送邮件。重复调用会创建不同的营销活动；当前接口不支持 A/B 测试、附件、定时发送及通过 API 更新活动。
</Note>

## 认证

在 `Authorization` 请求头中使用 Bearer API Key：

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

<Warning>
  请勿在前端代码、公开仓库或日志中保存真实 API Key。
</Warning>

## 请求体

Content-Type：`application/json`

| 字段 | 类型 | 必填 | 说明 |
| - | - | - | - |
| `name` | `string` | 是 | 营销任务名称（Campaign Name），并非邮件主题。不得为空白或包含单引号，UTF-8 编码长度小于 255 字节 |
| `subject` | `string` | 是 | 收件人看到的邮件主题。不得为空白，UTF-8 编码长度小于 255 字节 |
| `from` | `object` | 是 | 当前用户可用的发件邮箱与显示名称 |
| `from.email` | `string` | 是 | 发件邮箱地址 |
| `from.name` | `string` | 否 | 发件显示名称 |
| `replyTo` | `object` | 否 | 当前用户可用的回复地址；不提供则不设置独立回复地址 |
| `replyTo.email` | `string` | 条件必填 | 提供 `replyTo` 对象时必填。`replyTo` 仅支持设置邮箱地址，不支持设置显示名称 |
| `previewText` | `string` | 否 | 收件箱中主题旁的预览文字；不传则不设置 |
| `content` | `object` | 是 | 邮件正文；`html` 与 `plainText` 至少一个非空白 |
| `content.html` | `string` | 条件必填 | HTML 邮件正文；与 `plainText` 至少提供一个 |
| `content.plainText` | `string` | 条件必填 | 纯文本邮件正文；与 `html` 至少提供一个 |
| `recipients` | `object` | 是 | 收件范围；创建时检查引用的可访问性，实际收件人在发送时解析 |
| `recipients.include` | `object` | 是 | 必须通过联系人 ID 或标签 ID 指定至少一个包含对象，不允许空对象表示全部联系人 |
| `recipients.include.contactIds` | `array<string>` | 条件必填 | 要包含的联系人 ID 列表 |
| `recipients.include.tagIds` | `array<string>` | 条件必填 | 要包含的标签 ID 列表 |
| `recipients.exclude` | `object` | 否 | 从包含范围中排除的联系人与标签；不传或为空表示不额外排除 |
| `recipients.exclude.contactIds` | `array<string>` | 否 | 要排除的联系人 ID 列表 |
| `recipients.exclude.tagIds` | `array<string>` | 否 | 要排除的标签 ID 列表 |

<Info>
  `replyTo` 只接受 `email` 字段。请勿在 `replyTo` 对象中传入 `name`。
</Info>

## 请求示例

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST \
      "https://api.sendify.dingstore.cn/dmx/v2/campaigns" \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "九月会员营销任务",
        "subject": "会员专属优惠已上线",
        "from": {
          "email": "marketing@example.com",
          "name": "会员服务"
        },
        "replyTo": {
          "email": "support@example.com"
        },
        "previewText": "查看本月新品和专属优惠",
        "content": {
          "html": "<html><body><h1>会员优惠</h1></body></html>",
          "plainText": "会员专属优惠已上线"
        },
        "recipients": {
          "include": { "tagIds": ["tag-vip"] },
          "exclude": { "contactIds": ["contact-001"] }
        }
      }'
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const response = await fetch(
      "https://api.sendify.dingstore.cn/dmx/v2/campaigns",
      {
        method: "POST",
        headers: {
          Authorization: "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name: "九月会员营销任务",
          subject: "会员专属优惠已上线",
          from: { email: "marketing@example.com", name: "会员服务" },
          replyTo: { email: "support@example.com" },
          content: { plainText: "会员专属优惠已上线" },
          recipients: { include: { tagIds: ["tag-vip"] } },
        }),
      }
    );

    console.log(await response.json());
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    payload = {
        "name": "九月会员营销任务",
        "subject": "会员专属优惠已上线",
        "from": {
            "email": "marketing@example.com",
            "name": "会员服务",
        },
        "replyTo": {"email": "support@example.com"},
        "content": {"plainText": "会员专属优惠已上线"},
        "recipients": {"include": {"tagIds": ["tag-vip"]}},
    }

    response = requests.post(
        "https://api.sendify.dingstore.cn/dmx/v2/campaigns",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
        json=payload,
    )
    print(response.status_code)
    print(response.text)
    ```
  </Tab>
</Tabs>

## 成功响应

| 字段 | 类型 | 说明 |
| - | - | - |
| `id` | `string` | 新营销活动的唯一标识，可用于查询或启动营销活动 |

```json theme={null}
{
  "id": "03ec9355-4bf3-4a09-9829-4f3ef1d12a90"
}
```

## 错误响应

| HTTP 状态码 | 说明 |
| - | - |
| `400` | 请求参数不合法，或引用了当前用户无权访问的发件地址、回复地址、联系人或标签 |
| `401` | 访问未授权，请检查是否传递了正确的 Bearer API Key |
| `403` | 无 API 访问权限，请检查 API Key 的权限配置 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.