Users

使用此端点来操作并获取有关 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();
$userApi  = $api->newApi("users", $auth, $apiUrl);

获取用户

检索单个用户。

<?php

//...
$user = $userApi->get($id);

HTTP 请求

GET /users/ID

响应

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

{
   "user": {
       "isPublished": true,
       "dateAdded": "2026-02-21T05:19:56+00:00",
       "dateModified": "2026-02-21T05:20:13+00:00",
       "createdBy": 1,
       "createdByUser": "Admin Mautic",
       "modifiedBy": 1,
       "modifiedByUser": "Admin Mautic",
       "id": 3,
       "username": "r.green",
       "firstName": "Rachel",
       "lastName": "Green",
       "email": "rachel.green@acme.com",
       "position": "Marketing Staff",
       "role": {
           "createdByUser": "Admin Mautic",
           "modifiedByUser": null,
           "id": 2,
           "name": "Email Permissions",
           "description": null,
           "isAdmin": false,
           "rawPermissions": {
               "email:categories": [
                   "full"
               ],
               "email:emails": [
                   "full"
               ]
           }
       },
       "timezone": "Europe/Paris",
       "locale": null,
       "lastLogin": "2026-02-22T04:28:00+00:00",
       "lastActive": "2026-02-22T04:28:00+00:00",
       "signature": "Best regards, \r\nRachel Green"
   }
}

用户属性

- Name
  - Type
  - Description
- - isPublished
  - boolean
  - 用户发布状态
- - dateAdded
  - datetime
  - 用户记录创建日期和时间
- - dateModified
  - datetime
  - 用户记录上次修改日期和时间
- - createdBy
  - integer
  - 创建用户记录的用户的 ID
- - createdByUser
  - string
  - 创建用户记录的用户姓名
- - modifiedBy
  - integer
  - 最后修改用户记录的用户的 ID
- - modifiedByUser
  - string
  - 最后修改用户记录的用户姓名
- - id
  - integer
  - 用户的 ID
- - username
  - string
  - 用于登录的用户名 - 唯一
- - firstName
  - string
  - 用户的姓氏
- - lastName
  - string
  - 用户的名
- - email
  - string
  - 用户的电子邮件地址 - 唯一
- - position
  - string
  - 用户的职位或职称
- - role
  - object
  - 分配给用户的角色和权限。请参阅用户角色属性以获取详细信息
- - timezone
  - string
  - 用户的时区偏好
- - locale
  - string
  - 用户的语言或地区偏好
- - lastLogin
  - datetime
  - 上次登录的日期和时间
- - lastActive
  - datetime
  - 上次活动的时间
- - signature
  - string
  - HTML 格式的电子邮件签名

用户角色属性

Name	Type	Description
`isPublished`	boolean	角色发布状态
`dateAdded`	datetime	角色记录创建日期和时间
`dateModified`	datetime	角色记录上次修改日期和时间
`createdBy`	integer	创建角色记录的用户的 ID
`createdByUser`	string	创建角色记录的用户姓名
`modifiedBy`	integer	最后修改角色记录的用户的 ID
`modifiedByUser`	string	最后修改角色记录的用户姓名
`id`	integer	角色的 ID
`name`	string	角色的名称
`description`	string	角色的描述
`isAdmin`	boolean	管理员状态 - 如果角色具有完全系统访问权限，则为 `true`
`rawPermissions`	object	用于 Mautic 模块的细粒度权限集合

列出用户

检索用户列表。

<?php

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

HTTP 请求

GET /users

查询参数

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。

{
   "total": 3,
   "users": [
       {
           "isPublished": true,
           "dateAdded": "2026-02-21T05:19:56+00:00",
           "dateModified": "2026-02-21T05:20:13+00:00",
           "createdBy": 1,
           "createdByUser": "Admin Mautic",
           "modifiedBy": 1,
           "modifiedByUser": "Admin Mautic",
           "id": 3,
           "username": "r.green",
           "firstName": "Rachel",
           "lastName": "Green",
           "email": "rachel.green@acme.com",
           "position": "Marketing Staff",
           "role": {
               "createdByUser": "Admin Mautic",
               "modifiedByUser": null,
               "id": 2,
               "name": "Email Permissions",
               "description": null,
               "isAdmin": false,
               "rawPermissions": {
                   "email:categories": [
                       "full"
                   ],
                   "email:emails": [
                       "full"
                   ]
               }
           },
           "timezone": "Europe/Paris",
           "locale": null,
           "lastLogin": "2026-02-22T04:28:00+00:00",
           "lastActive": "2026-02-22T04:28:00+00:00",
           "signature": "Best regards, \r\nRachel Green"
       },
       // ...
   ]
}

属性

Name	Type	Description
`total`	integer	用户总数
`users`	array	用户数组

对于其他属性，请参阅 User properties.

创建用户

创建一个新用户。

<?php

$data = array(
    'firstName'     => 'John',                 // Required
    'lastName'      => 'Doe',                  // Required
    'username'      => 'newuser',              // Required
    'email'         => 'john.doe@example.com', // Required
    'plainPassword' => array(                  // Required
        'password' => 'SecurePassword123!',
        'confirm'  => 'SecurePassword123!'
    ),
    'role'          => 1,                      // Required
    'timezone'      => 'America/New_York',     // Required
    'locale'        => 'en_US',                // Required
    'position'      => 'Marketing Specialist',
);

$user = $userApi->create($data);

HTTP request

POST /users/new

POST 参数

Name	Type	Description
`firstName`	string	Required. 用户的姓氏
`lastName`	string	Required. 用户的名
`username`	string	Required. Must be unique. 用于登录的用户名
`email`	string	Required. Must be unique. 用户的电子邮件地址
`plainPassword`	array	Required. 包含 password 和 confirm 键的数组
`role`	integer	Required. 分配给用户的角色的 ID
`timezone`	string	Required. 用户的时区偏好
`locale`	string	Required. 用户的语言或区域设置偏好
`isPublished`	boolean	用户发布状态。设置为 0 或 false 以禁用用户帐户，默认为 1
`position`	string	职位或职称
`signature`	string	HTML 格式的电子邮件签名

Response

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

响应是一个类似于 Get User 的 JSON 对象。

Properties

请参阅 User properties.

Edit User

编辑用户。

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

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

$id = 1;

$data = array(: ‘firstName’ => ‘John Updated’, ‘position’ => ‘Senior Marketing Specialist’, ‘timezone’ => ‘Europe/London’

);

// Create a new User if ID 1 isn’t found $createIfNotFound = true;

$user = $userApi->edit($id, $data, $createIfNotFound);

HTTP request

PUT /users/ID/edit: updates an existing User or creates a new one when the ID doesn’t exist.
PATCH /users/ID/edit: updates an existing User. The request fails when the ID doesn’t exist.

POST parameters

Accepts the same parameters as those described in Create User. All parameters are optional.

Response

PUT: returns 200 OK when the request successfully updates the User or 201 Created when the request creates a User.
PATCH: returns 200 OK when the request successfully updates the User or 404 Not Found error when the User ID doesn’t exist.

The response is a JSON object similar to Get User.

Properties

Refer to User properties.

Delete User

Deletes a User.

<?php

$user = $userApi->delete($id);

HTTP request

DELETE /users/ID

Response

Returns 200 OK when the request successfully deletes the User.

The response is a JSON object containing the data of the deleted User, similar to Get User.

Properties

Refer to User properties.

Get current User

Retrieves the profile data of the User associated with the current API credentials.

<?php

$currentUser = $userApi->getSelf();

HTTP request

GET /users/self

Response

Returns 200 OK when the request successfully retrieves the User’s information.

{

“isPublished”: true, “dateAdded”: “2026-02-21T05:19:56+00:00”, “dateModified”: “2026-02-21T05:20:13+00:00”, “createdBy”: 1, “createdByUser”: “Admin Mautic”, “modifiedBy”: 1, “modifiedByUser”: “Admin Mautic”, “id”: 3, “username”: “r.green”, “firstName”: “Rachel”, “lastName”: “Green”, “email”: “rachel.green@acme.com”, “position”: “Marketing Staff”, “role”: {

“isPublished”: true, “dateAdded”: “2026-02-21T05:18:04+00:00”, “dateModified”: “2026-02-23T04:02:22+00:00”, “createdBy”: 1, “createdByUser”: “Admin Mautic”, “modifiedBy”: 1, “modifiedByUser”: “John Doe”, “id”: 2, “name”: “Email Permissions”, “isAdmin”: false, “rawPermissions”: {

“asset:categories”: [
“view”, “edit”, “create”, “delete”

], “asset:assets”: [

“viewown”, “editown”, “create”, “deleteown”

], “email:categories”: [

“full”

], “email:emails”: [

“full”

], “mauticSocial:categories”: [

“full”

], “mauticSocial:monitoring”: [

“full”

], “mauticSocial:tweets”: [

“viewown”, “editown”, “create”, “deleteown”, “publishown”

]

}

}, “timezone”: “Europe/Paris”, “lastLogin”: “2026-02-25T08:24:46+00:00”, “lastActive”: “2026-02-25T08:24:46+00:00”, “signature”: “Best regards, rnRachel Green”

}

当前用户属性

- Name
  - Type
  - Description
- - isPublished
  - boolean
  - 用户发布状态
- - dateAdded
  - datetime
  - 用户记录创建日期和时间
- - dateModified
  - datetime
  - 用户记录上次修改日期和时间
- - createdBy
  - integer
  - 创建用户记录的用户的 ID
- - createdByUser
  - string
  - 创建用户记录的用户姓名
- - modifiedBy
  - integer
  - 上次修改用户记录的用户的 ID
- - modifiedByUser
  - string
  - 上次修改用户记录的用户姓名
- - id
  - integer
  - 用户的 ID
- - username
  - string
  - 用于登录的用户名 - 唯一
- - firstName
  - string
  - 用户的姓氏
- - lastName
  - string
  - 用户的名
- - email
  - string
  - 用户的电子邮件地址 - 唯一
- - position
  - string
  - 用户的职位或职称
- - role
  - object
  - 分配给用户的角色和权限
- - timezone
  - string
  - 用户的时区偏好
- - lastLogin
  - datetime
  - 上次登录的日期和时间
- - lastActive
  - datetime
  - 上次活动的时间
- - signature
  - string
  - HTML 格式的电子邮件签名

当前用户角色属性

Name	Type	Description
`isPublished`	boolean	角色的发布状态
`dateAdded`	datetime	角色记录创建日期和时间
`dateModified`	datetime	角色记录上次修改日期和时间
`createdBy`	integer	创建角色记录的用户的 ID
`createdByUser`	string	创建角色记录的用户姓名
`modifiedBy`	integer	上次修改角色记录的用户的 ID
`modifiedByUser`	string	上次修改角色记录的用户姓名
`id`	integer	角色的 ID
`name`	string	角色的名称
`description`	string	角色的描述
`isAdmin`	boolean	管理员状态 - 如果角色具有完全系统访问权限，则为 `true`
`rawPermissions`	object	用于 Mautic 模块的细粒度权限集合

验证用户权限

验证用户是否具有特定权限。

<?php

$permissions = array('user:users:view', 'user:users:edit'); // Required
$result = $userApi->checkPermission($userId, $permissions);

HTTP 请求

POST /users/ID/permissioncheck

POST 参数

Name

Type

Description

permissions

array

Required.

用于验证的权限字符串数组。

Response

当请求成功验证用户时，返回 200 OK。

{
   "user:users:view": true,
   "user:users:edit": true
}

Properties

Name	Type	Description
`bundle:group:action`	boolean	权限状态 - `true` 表示用户具有该权限。

Note

bundle: Mautic bundle 的名称，例如：user、email、asset 等。
group: bundle 中的功能组，例如：users、roles、forms 等。
action: 具体的操作，例如：view、edit、create、delete 或 full。

列出用户角色

检索所有可用的用户角色。

<?php

$roles = $userApi->getRoles();

HTTP 请求

GET /users/list/roles

查询参数

Name	Description
`filter`	用于按名称过滤角色的字符串。
`limit`	返回的角色数量限制。

Response

当请求成功检索用户角色列表时，返回 200 OK。

[
   {
       "id": 1,
       "name": "Administrator"
   },
   {
       "id": 2,
       "name": "Email Permissions"
   }
]

Properties

Name	Type	Description
`id`	integer	角色的 ID。
`name`	string	分配给角色的名称。

错误响应

常见错误响应

HTTP code	Error status	Description
`400`	Bad Request	表示无效的 JSON 语法或字段验证失败。例如：缺少必需字段、密码强度不足或用户名重复。
`401`	Unauthorized	需要身份验证，或者检测到密码强度不足。
`403`	Forbidden	没有执行此操作的权限。
`404`	Not Found	未找到具有指定 ID 的用户。
`500`	Internal server error	发生意外错误，通常是由于请求正文中存在无效的数据格式。

密码验证错误

在创建或更新用户时发生的密码验证错误：

{

“errors”: [

{
“code”: 400, “message”: “password: Please enter a stronger password. Your password must use a combination of upper and lower case, special characters and numbers.”, “details”: {

“password”: [
“Please enter a stronger password. Your password must use a combination of upper and lower case, special characters and numbers.”

]

}

}

]

}

Permission error

Permission error for non-existent Users:

{
   "errors": [
       {
           "code": 404,
           "message": "Item was not found.",
           "details": []
       }
   ]
}

Role assignment error

Error when assigning User’s Role:

{
   "errors": [
       {
           "code": 400,
           "message": "role: This value is not valid.",
           "details": {
               "role": [
                   "This value is not valid."
               ]
           }
       }
   ]
}