Tags

---

使用此端点来操作并获取 Mautic 的标签的详细信息。

使用 Mautic API 库

您可以使用 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();
$tagApi   = $api->newApi("tags", $auth, $apiUrl);

获取标签

检索单个标签。

<?php

//...
$tag = $tagApi->get($id);

HTTP 请求

GET /tags/ID

响应

• 当请求成功检索到标签时，返回 200 OK。

{
    "tag": {
        "id": 34,
        "tag": "tagA",
        "description": "A tag for grouping contacts"
    }
}

标签属性

名称	类型	描述
id	int	标签的 ID
tag	string	标签的标题
description	string/null	标签的描述

列出标签

检索标签列表。

<?php

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

HTTP 请求

GET /tags

查询参数

名称	描述
search	用于过滤实体的字符串或搜索命令
start	返回实体的起始行 - 默认为 0
limit	要返回的最大实体数量 - 默认为 30
orderBy	排序的列。响应中的任何列都有效。
orderByDir	排序方向 - asc 或 desc
publishedOnly	只返回当前已发布的实体
minimal	只返回简单的映射对象，不包含其他列表

响应

• 当请求成功检索到标签列表时，返回 200 OK。

{
    "total": 1,
    "tags": [
        {
            "id": 34,
            "tag": "tagA",
            "description": "A tag for grouping contacts"
        }
    ]
}

属性

名称	类型	描述
total	integer	标签的总数
tags	array	按其 ID 索引的标签集合

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

Create Tag

Creates a new Tag.

<?php

$data = [
    'tag' => 'Tag A',
    'description' => 'Description of Tag A',
];

$tag = $tagApi->create($data);

HTTP request

POST /tags/new

POST parameters

Name	Type	Description
tag	string	Required. Title of the Tag
description	string	Description of the Tag

Response

• Returns 201 Created when the request successfully creates a Tag.

Properties

Refer to Tag properties.

Edit Tag

Edits a Tag.

This operation supports PUT or PATCH depending on the desired behavior:

• PUT: full replacement. The request creates a new Tag if the ID doesn’t exist. If the ID exists, the request clears all existing data and replaces it with the provided values.

• PATCH: partial update. The request only updates field values based on the request data. The request fails when the Tag ID doesn’t exist.

<?php

$id   = 1;
$data = [
    'tag' => 'Tag B',
    'description' => 'Updated description',
];

// Create new Tag if ID 1 isn't found?
$createIfNotFound = true;

$tag = $tagApi->edit($id, $data, $createIfNotFound);

HTTP request

• PUT /tags/ID/edit: updates an existing Tag or creates a new one when the ID doesn’t exist.

• PATCH /tags/ID/edit: updates an existing Tag. The request fails when the ID doesn’t exist.

POST parameters

Name	Type	Description
tag	string	Title of the Tag
description	string	Description of the Tag

Response

• PUT: returns 200 OK when the request successfully updates the Tag or 201 Created when the request creates a Tag.

• PATCH: returns 200 OK when the request successfully updates the Tag or 404 Not Found error when the Tag ID doesn’t exist.

The response is a JSON object similar to Get Tag.

Properties

Refer to Tag properties.

Delete Tag

Deletes a Tag.

<?php

$tag = $tagApi->delete($id);

HTTP request

DELETE /tags/ID/delete

Response

• Returns 200 OK when the request successfully deletes the Tag.

Properties

Refer to Tag properties.