Campaigns
Note
此页面的内容需要进行重大更新。旧页面包含过时且可能不准确的信息。您仍然可以通过 Mautic Developer Documentation archived repository 访问它。
如果您有兴趣帮助开发此页面和其他新内容的，请考虑加入文档编写工作。
请阅读 Contributing Guidelines 和 Contributing to Mautic’s documentation 以开始您的贡献。
使用此端点获取有关 Mautic 的 Campaigns 的详细信息。
使用 Mautic API 库
您可以通过以下方式使用 Mautic API Library 与此 API 进行交互，或者按照本文档中的描述使用各种 HTTP 端点。
<?php
use Mautic\MauticApi;
use Mautic\Auth\ApiAuth;
// ...
$initAuth = new ApiAuth();
$auth = $initAuth->newAuth($settings);
$apiUrl = "https://example.com";
$api = new MauticApi();
$campaignApi = $api->newApi("campaigns", $auth, $apiUrl);
Get Campaign
<?php
//...
$campaign = $campaignApi->get($id);
获取单个 Campaign 的详细信息，通过 ID 识别。
HTTP 请求
GET /campaigns/ID
响应
Expected Response Code: 200
{
"campaign": {
"id": 3,
"name": "Email A/B Test",
"description": null,
"isPublished": true,
"publishUp": null,
"publishDown": null,
"dateAdded": "2015-07-15T15:06:02-05:00",
"createdBy": 1,
"createdByUser": "Delfina Henderson",
"dateModified": "2015-07-20T13:11:56-05:00",
"modifiedBy": 1,
"modifiedByUser": "Iris Durand",
"category": null,
"events": {
"28": {
"id": 28,
"type": "lead.changepoints",
"eventType": "action",
"name": "Adjust lead points",
"description": null,
"order": 1,
"properties": {
"points": 20
},
"triggerDate": null,
"triggerInterval": 1,
"triggerIntervalUnit": "d",
"triggerMode": "immediate",
"children": [],
"parent": null,
"decisionPath": null
}
}
}
}
Campaign 属性
- Name
Type
Description
idint
Campaign 的 ID
namestring
Campaign 的名称
descriptionstring/null
Campaign 的描述
aliasstring
用于生成 Campaign 的 URL
isPublishedboolean
发布状态
publishUpdatetime/null
Campaign 的发布日期/时间
publishDowndatetime/null
Campaign 的取消发布日期/时间
dateAddeddatetimeCampaign 的创建日期/时间
createdByint
创建 Campaign 的用户的 ID
createdByUserstring
创建 Campaign 的用户的名称
dateModifieddatetime/null
Campaign 的修改日期/时间
modifiedByint
最后修改 Campaign 的用户的 ID
modifiedByUserstring
最后修改 Campaign 的用户的名称
eventsarray
Campaign 相关的事件实体数组，请参见下文
contactCountint
Campaign 中的联系人数量。此属性仅由支持 withContactCounts=true 查询参数的端点返回，例如 GET /campaigns，并且无法从 GET /campaigns/{id} 获取。
contactCountFetchedAtdatetime/null
联系人数量检索的时间戳。此属性仅由支持 withContactCounts=true 查询参数的端点返回，例如 GET /campaigns，并且无法从 GET /campaigns/{id} 获取。
Event 属性
- Name
Type
Description
idint
事件的 ID
namestring
事件名称
descriptionstring
可选的事件描述
typestring
事件类型
eventTypestring
“action” 或 “decision”
orderint
与其他事件相关的顺序，用于关卡
propertiesobject
针对该事件配置的属性
triggerModestring
immediate,interval或date
triggerDatedatetime/null
如果 triggerMode 为 “date”，则为触发事件的日期/时间
triggerIntervalint/null
事件触发的时间间隔
triggerIntervalUnitstring
事件触发的时间间隔单位。选项有：
i = minutes,h = hours,d = days,m = months,y = years
childrenarray
该事件的子元素的数组
parentobject/null
该事件的父元素
decisionPathstring/null
如果该事件连接到操作，则如果为非决策路径，此值为 “no”，如果是主动跟踪的路径，则为 “yes”
列出活动
<?php
// ...
$campaigns = $campaignApi->getList($searchFilter, $start, $limit, $orderBy, $orderByDir, $publishedOnly, $minimal);
HTTP 请求
GET /campaigns
查询参数
Name |
Description |
|---|---|
|
用于过滤实体的字符串或搜索命令 |
|
返回实体的起始行，默认为 0 |
|
要返回的实体数量限制，默认为分页系统的配置 - 默认值为 30 |
|
用于排序的列，可以使用响应中列出的任何列 |
|
排序方向： |
|
仅返回当前已发布的实体 |
|
仅返回实体数组，不包含其他列表 |
|
包含每个活动的联系人计数。接受 true 或 false，默认为 false。系统默认将联系人计数缓存 12 小时。通过在 config/local.php 中设置 campaign_contact_count_cache_ttl 参数来配置缓存 TTL（以秒为单位） |
响应
预期响应代码：200
- {
“total”: 1, “campaigns”: {
- “3”: {
“id”: 3, “name”: “Welcome Campaign”, “description”: null, “isPublished”: true, “publishUp”: null, “publishDown”: null, “dateAdded”: “2015-07-15T15:06:02-05:00”, “createdBy”: 1, “createdByUser”: “Lucine Van der Zee”, “dateModified”: “2015-07-20T13:11:56-05:00”, “modifiedBy”: 1, “modifiedByUser”: “Lucine Van der Zee”, “category”: null, “events”: {
- “22”: {
“id”: 22, “type”: “email.send”, “eventType”: “action”, “name”: “Send welcome email”, “description”: null, “order”: 1, “properties”: {
“email”: 1
}, “triggerMode”: “immediate”, “triggerDate”: null, “triggerInterval”: null, “triggerIntervalUnit”: null, “children”: [], “parent”: null, “decisionPath”: null
}, “28”: {
“id”: 28, “type”: “lead.changepoints”, “eventType”: “action”, “name”: “Adjust lead points”, “description”: null, “order”: 2, “properties”: {
“points”: 20
}, “triggerMode”: “immediate”, “triggerDate”: null, “triggerInterval”: null, “triggerIntervalUnit”: null, “children”: [], “parent”: null, “decisionPath”: null
}
}
}
}
}
Note
The withContactCounts=true parameter adds two additional fields per Campaign:
contactCount: number of Contacts in the Campaign - integercontactCountFetchedAt: timestamp of the Contact count retrieval - ISO 8601 format
The system caches Contact counts for 12 hours by default to improve performance. New Contacts added to Campaigns may not appear until the cache expires. Set the campaign_contact_count_cache_ttl parameter in config/local.php to configure the cache TTL - value in seconds.
Properties
Same as Get Campaign.
List Campaign Contacts
这个端点基本上是 stats 端点的别名，指定了 campaign_leads 表和 campaign_id。 其他参数与 stats 端点中的参数相同。
<?php
// ...
$response = $campaignApi->getContacts($campaignId, $start, $limit, $order, $where);
HTTP 请求
GET /campaigns/ID/contacts
查询参数
响应
Expected Response Code: 200
{
"total":"1",
"contacts":[
{
"campaign_id":"311",
"lead_id":"3126",
"date_added":"2017-01-25 15:11:10",
"manually_removed":"0",
"manually_added":"1"
}
]
}
创建活动
<?php
$data = array(
'name' => 'Campaign A',
'description' => 'This is my first Campaign created via API.',
'isPublished' => 1
);
$campaign = $campaignApi->create($data);
创建新的活动。 要查看更高级的示例，包括活动事件等，请参阅单元测试。
HTTP 请求
POST /campaigns/new
POST 参数
Name |
Type |
Description |
|---|---|---|
|
string |
活动名称是唯一必需的字段 |
|
string |
用于生成活动的 URL |
|
string |
对活动的一个描述。 |
|
int |
值为 0 或 1 |
响应
Expected Response Code: 201
属性
与 Get Campaign 相同。
复制活动
<?php
$camnpaignId = 12;
$campaign = $campaignApi->cloneCampaign($campaignId);
复制现有的活动。 要查看更高级的示例，包括活动事件等，请参阅单元测试。
HTTP 请求
POST /campaigns/clone/CAMPAIGN_ID
响应
Expected Response Code: 201
属性
与 Get Campaign 相同。
编辑活动
<?php
$id = 1;
$data = array(
'name' => 'New Campaign name',
'isPublished' => 0
);
// 如果 ID 为 1 的活动未找到，则创建新的活动？
$createIfNotFound = true;
$campaign = $campaignApi->edit($id, $data, $createIfNotFound);
编辑一个新的活动。 请注意，这支持 PUT 或 PATCH，具体取决于所需的行为。
PUT 如果给定的 ID 不存在，则会创建一个活动，并清除所有活动的详细信息，然后添加来自请求的信息。 PATCH 如果具有给定 ID 的活动不存在，则会失败，并且使用来自请求的值更新活动的字段值。
HTTP 请求
要编辑一个活动并在未找到该活动时返回 404：
PATCH /campaigns/ID/edit
要编辑一个活动或创建一个新的活动（如果未找到该活动）：
PUT /campaigns/ID/edit
POST 参数
Name |
Description |
|---|---|
|
活动名称，这是唯一必需的字段。 |
|
如果未设置，则自动生成别名。 |
|
对活动的描述。 |
|
值为 0 或 1。 |
响应
如果使用 PUT，则预期的响应代码为 ``200``（编辑活动时）或 ``201``（创建活动时）。
如果使用 PATCH，则预期的响应代码为 200。
属性
与 Get Campaign 相同。
删除活动
<?php
$campaign = $campaignApi->delete($id);
删除一个活动。
HTTP 请求
DELETE /campaigns/ID/delete
响应
预期的响应代码：200
属性
与 Get Campaign 相同。
导出活动
此端点允许您导出特定 Mautic 活动的数据。它将数据作为 JSON 文件或 ZIP 归档返回，其中包含 JSON 文件和相关资源。
请参阅 Mautic REST API 身份验证* 以获取身份验证详细信息。
Note
* 该旧页面包含过时且可能不准确的信息。
如果您有兴趣帮助开发此页面的新内容以及其他内容，请考虑加入文档工作。
请阅读 Contributing Guidelines 和 Contributing to Mautic’s documentation 以开始贡献。
HTTP 请求
GET /campaigns/export/<*campaign_id*>
URL 的最后部分，<*campaign_id*>，指定要导出的活动 ID。
示例请求 - cURL
curl --location 'https://{*your-mautic-domain*}/api/campaigns/export/<*campaign_id*>' \
--header 'Authorization: Bearer *<your_actual_access_token>*' \
将 <*campaign_id*> 替换为您要导出的实际活动 ID。
响应
预期的响应代码：200
Content-Type: application/json
响应体是活动数据，可以是直接的 JSON 数据或 ZIP 文件。响应头中的 Content-Type 指示格式，例如 application/json 或 application/zip。
导入活动
此端点允许您从以前导出的 JSON 或 ZIP 文件中导入 Mautic 活动。
请参阅 Mautic REST API 身份验证* 以获取身份验证详细信息。
Note
* 该旧页面包含过时且可能不准确的信息。
如果您有兴趣帮助开发此页面的新内容以及其他内容，请考虑加入文档工作。
Please read the Contributing Guidelines 和 Contributing to Mautic’s documentation 以开始使用。
HTTP 请求
POST /campaigns/import
头部信息
Header |
Description |
|---|---|
|
|
请求体
如果发送 JSON 数据： 直接在请求体中提供原始 JSON payload。
如果发送 ZIP 文件： 使用 form-data 上传 ZIP 文件。
响应
Expected Response Code: 200 或 201 Created，具体取决于 API 的行为。
将联系人添加到活动
<?php
//...
$response = $campaignApi->addContact($campaignId, $contactId);
if (!isset($response['success'])) {
// handle error
}
手动将一个联系人添加到特定的活动中。
HTTP 请求
POST /campaigns/CAMPAIGN_ID/contact/CONTACT_ID/add
响应
Expected Response Code: 200
{
"success": true
}
从活动中移除联系人
<?php
//...
$response = $listApi->removeContact($campaignId, $contactId);
if (!isset($response['success'])) {
// handle error
}
手动从特定的活动中移除一个联系人。
HTTP 请求
POST /campaigns/CAMPAIGN_ID/contact/CONTACT_ID/remove
响应
Expected Response Code: 200
{
"success": true
}