Segments

使用此端点来操作并获取有关 Mautic 分段的详细信息。

使用 Mautic API 库

您可以使用以下 :xref:`Mautic API 库与此 API 进行交互，或者使用本文档中描述的各种 HTTP 端点。

<?php
use Mautic\MauticApi;
use Mautic\Auth\ApiAuth;

// ...
$initAuth   = new ApiAuth();
$auth       = $initAuth->newAuth($settings);
$apiUrl     = "https://example.com";
$api        = new MauticApi();
$segmentApi = $api->newApi("segments", $auth, $apiUrl);

获取分段

检索单个分段。

<?php

//...
$segment = $segmentApi->get($id);

HTTP 请求

GET /segments/ID

响应

当请求成功检索到分段时，返回 200 OK。

{
   "list": {
       "isPublished": true,
       "dateAdded": "2026-02-19T19:36:21+00:00",
       "dateModified": "2026-02-19T19:37:16+00:00",
       "createdBy": 1,
       "createdByUser": "Admin Mautic",
       "modifiedBy": 1,
       "modifiedByUser": "Admin Mautic",
       "id": 2,
       "name": "Acme Global Conference",
       "publicName": "Acme Global Conference",
       "alias": "acme-global-conference",
       "description": null,
       "category": null,
       "filters": [
           {
               "glue": "and",
               "field": "companyname",
               "object": "company",
               "type": "text",
               "operator": "=",
               "properties": {
                   "filter": "Beta Inc."
               }
           }
       ],
       "isGlobal": true,
       "isPreferenceCenter": false
   }
}

分段属性

- Name
  - Type
  - Description
- - isPublished
  - boolean
  - 分段发布状态
- - dateAdded
  - datetime
  - 分段记录创建日期和时间
- - dateModified
  - datetime
  - 分段记录上次修改日期和时间
- - createdBy
  - integer
  - 创建分段的用户ID
- - createdByUser
  - string
  - 创建分段的用户名
- - modifiedBy
  - integer
  - 最后修改分段的用户的ID
- - modifiedByUser
  - string
  - 最后修改分段的用户名
- - id
  - integer
  - 分段ID
- - name
  - string
  - 分段名称
- - publicName
  - string
  - 向联系人显示的公共分段名称
- - alias
  - string
  - 分段的自动生成的别名或 slug
- - description
  - string
  - 分段描述
- - category
  - object
  - 赋给分段的类别
- - filters
  - array
  - 定义分段实体的过滤器标准数组
- - isGlobal
  - boolean
  - 全局可见性状态 - 设置为 1 或 true 以将分段与所有用户共享。如果未设置，则默认为受限访问
- - isPreferenceCenter
  - boolean
  - 偏好中心状态 - 设置为 1 或 true 以将分段包含在偏好中心中。如果未设置，则默认为隐藏

列出分段

检索分段列表。

<?php

//...
$segments = $segmentApi->getList($searchFilter, $start, $limit, $orderBy, $orderByDir, $publishedOnly, $minimal);

HTTP 请求

GET /segments

查询参数

Name	Type	Description
`searchFilter`	string	用于过滤实体的字符串或搜索命令
`start`	integer	返回实体开始的行数 - 默认为 0
`limit`	integer	要返回的最大实体数量 - 默认为 30
`orderBy`	string	用于排序的列。响应中的任何列都有效。注意: 将 `camelCase` 属性转换为 `snake_case`。例如，`dateAdded` 变为 `date_added`，`webhookUrl` 变为 `webhook_url`，依此类推
`orderByDir`	string	排序方向 - `asc` 或 `desc`
`publishedOnly`	boolean	仅返回当前已发布的实体
`minimal`	boolean	仅返回简单的映射对象，不包含其他列表

响应

当请求成功检索分段列表时，返回 200 OK。

```json {

“total”: 2, “lists”: {

“2”: {
“isPublished”: true, “dateAdded”: “2026-02-19T19:36:21+00:00”, “dateModified”: “2026-02-19T19:37:16+00:00”, “createdBy”: 1, “createdByUser”: “Admin Mautic”, “modifiedBy”: 1, “modifiedByUser”: “Admin Mautic”, “id”: 2, “name”: “Acme Global Conference”, “publicName”: “Acme Global Conference”, “alias”: “acme-global-conference”, “description”: null, “category”: null, “filters”: [

{
“glue”: “and”, “field”: “companyname”, “object”: “company”, “type”: “text”, “operator”: “=”, “properties”: {

“filter”: “Beta Inc.”

}

}

], “isGlobal”: true, “isPreferenceCenter”: false

}, // …

}

}

Properties

Name	Type	Description
`total`	integer	Total count of Segments
`lists`	object	A mapped collection of Segments indexed by their ID

For the rest of the properties, refer to Segment properties.

Create Segment

Creates a new Segment.

<?php

 $data = array(
     'name'               => 'VIP Customers', // Required
     'alias'              => 'vip-customers',
     'description'        => 'High-value customers',
     'isPublished'        => true,
     'isGlobal'           => true,
     'filters'            => array(
         array(
             'glue'       => 'and',
             'field'      => 'points',
             'object'     => 'lead',
             'type'       => 'number',
             'operator'   => 'gte',
             'properties' => array(
                 'filter' => '100'
             )
         )
     )
 );

 $segment = $segmentApi->create($data);

HTTP request

POST /segments/new

POST parameters

Name	Type	Description
`name`	string	Required.

```

Segment name

- publicName
- string
- 向联系人显示的 Segment 的公开名称
- alias
- string
- Segment 的自动生成的别名或 slug
- description
- string
- Segment 的描述
- isPublished
- boolean
- Segment 的发布状态
- category
- object
- 分配给 Segment 的类别
- filters
- array
- 定义 Segment 实体的过滤器标准数组
- isGlobal
- boolean
- 全局可见性状态 - 设置为 1 或 true 以将 Segment 与所有用户共享。如果未设置，则默认为受限访问
- isPreferenceCenter
- boolean
- 偏好中心状态 - 设置为 1 或 true 以将 Segment 包含在偏好中心中。如果未设置，则默认为隐藏

Response

当请求成功创建 Segment 时，返回 201 Created。

响应与 Get Segment 中的响应相同。

Properties

请参阅 Segment properties.

Edit Segment

编辑一个 Segment。

此操作支持 PUT 或 PATCH，具体取决于所需的行为：

PUT: 完全替换。如果 ID 缺失，则请求会创建一个新的 Segment。如果 ID 存在，则请求会清除所有现有数据并将其替换为提供的值。
PATCH: 部分更新。请求仅根据请求数据更新字段值。如果 Segment ID 不存在，则请求失败。

<?php

$id   = 1;
$data = array(
    'name' => 'Updated VIP Customers',
    'description' => 'Updated high-value customers segment',
);

// 如果未找到 ID 1，则创建新的 Segment
$createIfNotFound = true;

$segment = $segmentApi->edit($id, $data, $createIfNotFound);

HTTP request

PUT /segments/ID/edit: 更新现有的 Segment 或在 ID 不存在时创建一个新的 Segment。
PATCH /segments/ID/edit: 更新现有的 Segment。如果 ID 不存在，则请求失败。

POST parameters

接受与 Create Segment 中描述的相同参数。所有参数都是可选的。

Response

PUT: 当请求成功更新 Segment 时，返回 200 OK；当请求创建 Segment 时，返回 201 Created。
PATCH: 当请求成功更新 Segment 时，返回 200 OK；如果 Segment ID 不存在，则返回 404 Not Found 错误。

响应与 Get Segment 中的响应相同。

Properties

请参阅 Segment properties.

Delete Segment

删除一个 Segment。

<?php

$segment = $segmentApi->delete($id);

HTTP request

DELETE /segments/ID/delete

Response

Returns 200 OK when the request successfully deletes the Segment.

The response is similar to Get Segment but contains the deleted Segment data.

Properties

Refer to Segment properties.

Add Contact to Segment

Adds a Contact to a specific Segment.

<?php

$segmentApi->addContact($segmentId, $contactId);

HTTP request

POST /segments/SEGMENT_ID/contact/CONTACT_ID/add

Response

Returns 200 OK when the request successfully adds the Contact to the Segment.

{
    "success": 1
}

Add Contacts to Segment

Adds multiple Contacts to a specific Segment.

<?php

$contactIds = array(1, 2, 3);
$segmentApi->addContacts($segmentId, $contactIds);

HTTP request

POST /segments/SEGMENT_ID/contacts/add

Parameters

Name

Type

Description

contactIds

array

Required.

Array of Contact IDs to add to the Segment

Response

Returns 200 OK when the request successfully adds the Contacts to the Segment.

{
    "success": 1,
    "details": {
        "1": {
            "success": true
        },
        "2": {
            "success": true
        },
        "3": {
            "success": false
        }
    }
}

Properties

Name	Type	Description
`success`	integer	Overall status of the request where `1` indicates completion
`details`	object	A mapped collection of processing results indexed by Contact ID
`details/{id}`	object	Result status for a specific Contact within the request
`details/{id}/success`	boolean	Individual confirmation of whether the Contact joined the Segment successfully

Remove Contact from Segment

Remove a Contact from a specific Segment.

<?php

$segmentApi->removeContact($segmentId, $contactId);

HTTP request

POST /segments/SEGMENT_ID/contact/CONTACT_ID/remove

Response

Returns 200 OK when the request successfully removes the Contact from the Segment.

{
    "success": 1
}

Get User Segments

Retrieves a list of Segments that are available to the current User.

$segments = $segmentApi->getUserSegments();

HTTP 请求

GET /contacts/list/segments

响应

当请求成功检索到用户的 Segment 时，返回 200 OK。

{
    "1": {
        "id": 1,
        "name": "VIP Customers",
        "alias": "vip-customers"
    },
    "2": {
        "id": 2,
        "name": "Newsletter Subscribers",
        "alias": "newsletter-subscribers"
    }
}

Segment 属性

名称	类型	描述
`{id}`	object	Segment 数据，按 Segment ID 索引
`{id}/id`	integer	Segment 的 ID
`{id}/name`	string	Segment 名称
`{id}/alias`	string	Segment 的自动生成的别名或 slug

Segment 过滤器

Segment 使用过滤器来定义要包含的对象类型，可以是 lead、company 或 behaviors。过滤器支持各种字段类型和运算符。

过滤器结构

{
     "object": "company",
     "glue": "and",
     "field": "companyname",
     "type": "text",
     "operator": "=",
     "properties": {
         "filter": "Beta Inc."
     }
}

过滤器属性

名称	类型	描述
`object`	string	对象类型，可以是 `lead`、`company` 或 `behaviors`
`glue`	string	使用 `and` 或 `or` 连接的过滤器之间的关系
`field`	string	字段或行为动作标识符，例如 `email`、`points`、`lead_email_received` 等
`type`	string	字段的数据类型，例如 `text`、`number`、`date` 等
`operator`	string	过滤器的比较逻辑，例如 `=`、`!empty`、`lte`、`startsWith` 等。请参考按字段类型划分的常用运算符获取详细信息
`properties`	object	用于 `filter` 值的对象以及配置，包括 `display`

按字段类型划分的常用运算符

文本字段

运算符	描述
`=`	与指定文本完全匹配
`!=`	排除指定的文本
`like`	字段中包含字符串
`!like`	字段中不包含字符串
`empty`	标识没有数据的字段
`!empty`	标识包含任何数据的字段

数字字段

- Operator
  - Description
- - =
  - Value equal to the specified number
- - !=
  - Value not equal to the specified number
- - gt
  - Value greater than the specified number
- - gte
  - Value greater than or equal to the specified number
- - lt
  - Value less than the specified number
- - lte
  - Value less than or equal to the specified number

Date fields

Operator	Description
`=`	Match for the specific date
`!=`	Exclusion of the specific date
`gt`	Occurrence after the specified date
`gte`	Occurrence on or after the specified date
`lt`	Occurrence before the specified date
`lte`	Occurrence on or before the specified date

Select or multi-select fields

Operator	Description
`=`	Selection matching the specified value
`!=`	Selection not matching the specified value
`in`	Match for any value within the provided list
`!in`	Exclusion of all values within the provided list

Filter examples

Email domain filter

{
    "glue": "and",
    "field": "email",
    "object": "lead",
    "type": "email",
    "operator": "like",
    "properties": {
        "filter": "%@company.com"
    }
}

Points filter

{
    "glue": "and",
    "field": "points",
    "object": "lead",
    "type": "number",
    "operator": "gte",
    "properties": {
        "filter": "100"
    }
}

Date filter

{
    "glue": "and",
    "field": "date_added",
    "object": "lead",
    "type": "datetime",
    "operator": "gte",
    "properties": {
        "filter": "2023-01-01 00:00:00"
    }
}

Behavior action filter

{
    "glue": "and",
    "field": "url_title",
    "object": "behaviors",
    "type": "text",
    "operator": "startsWith",
    "properties": {
        "filter": "acme"
    }
}