Users & Roles

Users API

Manage user accounts and permissions through the users API.

Get All Users

Retrieve a list of all users in the system.

curl -u 'username:password' http://localhost:9000/api/users

Response:

{
  "data": {
    "results": [
      {
        "id": 1,
        "created_at": "2024-01-01T00:00:00Z",
        "updated_at": "2024-01-01T00:00:00Z",
        "email": "admin@example.com",
        "name": "Admin User",
        "type": "user",
        "status": "enabled",
        "role": {
          "id": 1,
          "name": "Super Admin",
          "permissions": ["*"]
        }
      }
    ],
    "total": 1,
    "per_page": 20,
    "page": 1
  }
}

integer

Unique user ID

string

User email address (used for login)

name

string

Display name

type

string

User type: user (regular user with 2FA support) or api (API-only user without 2FA)

status

string

Account status: enabled or disabled

role

object

Assigned role with permissions

Get Single User

Retrieve details for a specific user.

GET /api/users/:id

cURL

curl -u 'username:password' http://localhost:9000/api/users/1

Required Permission: users:get

Create User

Create a new user account.

POST /api/users

string

required

User email address

name

string

required

Display name

password

string

required

User password (minimum 8 characters recommended)

type

string

default:"user"

User type: user or api

status

string

default:"enabled"

Account status: enabled or disabled

role_id

integer

required

ID of the role to assign to this user

Example Request:

curl -u 'admin:password' -X POST http://localhost:9000/api/users \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "newuser@example.com",
    "name": "New User",
    "password": "secure-password",
    "type": "user",
    "status": "enabled",
    "role_id": 2
  }'

Required Permission: users:manage

Update User

Update an existing user’s details.

PUT /api/users/:id

string

User email address

name

string

Display name

password

string

New password (optional, only provide if changing)

type

string

User type: user or api

status

string

Account status: enabled or disabled

role_id

integer

Role ID to assign

Example Request:

curl -u 'admin:password' -X PUT http://localhost:9000/api/users/2 \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Updated Name",
    "status": "enabled",
    "role_id": 3
  }'

Required Permission: users:manage

Delete User

Delete a user account.

DELETE /api/users/:id

cURL

curl -u 'admin:password' -X DELETE http://localhost:9000/api/users/5

Required Permission: users:manage

Deleting a user is permanent and cannot be undone. Ensure you have backups if needed.

Bulk Delete Users

Delete multiple users by ID.

DELETE /api/users?id=1&id=2&id=3

cURL

curl -u 'admin:password' -X DELETE 'http://localhost:9000/api/users?id=5&id=6'

Required Permission: users:manage

User Profile

Get Current User Profile

Get the authenticated user’s profile information.

GET /api/profile

cURL

curl -u 'username:password' http://localhost:9000/api/profile

Response:

{
  "data": {
    "id": 1,
    "email": "user@example.com",
    "name": "User Name",
    "type": "user",
    "status": "enabled",
    "role": {
      "id": 1,
      "name": "Admin",
      "permissions": ["*"]
    }
  }
}

Update Current User Profile

Update the authenticated user’s own profile.

PUT /api/profile

name

string

Display name

password

string

New password

current_password

string

Current password (required when changing password)

Example Request:

curl -u 'username:password' -X PUT http://localhost:9000/api/profile \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Updated Name",
    "password": "new-secure-password",
    "current_password": "old-password"
  }'

Two-Factor Authentication (2FA)

Generate TOTP QR Code

Generate a QR code for setting up TOTP 2FA.

GET /api/users/:id/twofa/totp

cURL

curl -u 'username:password' http://localhost:9000/api/users/1/twofa/totp

Response:

{
  "data": {
    "secret": "BASE32_ENCODED_SECRET",
    "url": "otpauth://totp/listmonk:user@example.com?secret=..."
  }
}

The url can be encoded as a QR code for scanning with authenticator apps.

Enable TOTP 2FA

Enable TOTP 2FA for a user account.

PUT /api/users/:id/twofa

secret

string

required

The TOTP secret from the QR code generation step

token

string

required

6-digit verification code from the authenticator app

Example Request:

curl -u 'username:password' -X PUT http://localhost:9000/api/users/1/twofa \
  -H 'Content-Type: application/json' \
  -d '{
    "secret": "BASE32_ENCODED_SECRET",
    "token": "123456"
  }'

2FA is only available for regular users (type: user). API users (type: api) cannot enable 2FA.

Disable TOTP 2FA

Disable TOTP 2FA for a user account.

DELETE /api/users/:id/twofa

cURL

curl -u 'username:password' -X DELETE http://localhost:9000/api/users/1/twofa

Roles API

Manage role-based access control (RBAC) for users and lists.

Get User Roles

Retrieve all user roles and their permissions.

GET /api/roles/users

cURL

curl -u 'username:password' http://localhost:9000/api/roles/users

Response:

{
  "data": [
    {
      "id": 1,
      "name": "Super Admin",
      "type": "user",
      "permissions": ["*"],
      "lists": []
    },
    {
      "id": 2,
      "name": "Campaign Manager",
      "type": "user",
      "permissions": ["campaigns:get", "campaigns:manage", "subscribers:get"],
      "lists": []
    }
  ]
}

Required Permission: roles:get

Get List Roles

Retrieve all list roles (for list-level permissions).

GET /api/roles/lists

cURL

curl -u 'username:password' http://localhost:9000/api/roles/lists

Required Permission: roles:get

Create User Role

Create a new user role with specified permissions.

POST /api/roles/users

name

string

required

Role name

permissions

array

required

Array of permission strings (e.g., ["subscribers:get", "campaigns:manage"])

lists

array

Array of list IDs this role can access (empty array for all lists)

Example Request:

curl -u 'admin:password' -X POST http://localhost:9000/api/roles/users \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Newsletter Editor",
    "permissions": [
      "campaigns:get",
      "campaigns:manage",
      "templates:get",
      "templates:manage",
      "subscribers:get"
    ],
    "lists": []
  }'

Required Permission: roles:manage

Create List Role

Create a new list role for list-level permissions.

POST /api/roles/lists

name

string

required

Role name

permissions

array

required

Array of list-specific permission strings

lists

array

required

Array of list IDs this role applies to

Example Request:

curl -u 'admin:password' -X POST http://localhost:9000/api/roles/lists \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Newsletter A Manager",
    "permissions": ["subscribers:manage", "campaigns:manage"],
    "lists": [1, 2]
  }'

Required Permission: roles:manage

Update User Role

Update an existing user role.

PUT /api/roles/users/:id

name

string

Role name

permissions

array

Updated permissions array

lists

array

Updated list IDs array

Example Request:

curl -u 'admin:password' -X PUT http://localhost:9000/api/roles/users/3 \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Senior Editor",
    "permissions": ["campaigns:get", "campaigns:manage", "templates:get", "templates:manage", "media:get", "media:manage"]
  }'

Required Permission: roles:manage

Update List Role

Update an existing list role.

PUT /api/roles/lists/:id

Required Permission: roles:manage

Delete Role

Delete a user or list role.

DELETE /api/roles/:id

cURL

curl -u 'admin:password' -X DELETE http://localhost:9000/api/roles/5

Required Permission: roles:manage

Cannot delete a role that is currently assigned to users. Reassign users to a different role first.

Permission Reference

Common permissions used in roles:

Permission	Description
`*`	Super admin - all permissions
`subscribers:get`	View subscribers
`subscribers:get_all`	View all subscribers across all lists
`subscribers:manage`	Create, update, delete subscribers
`subscribers:import`	Import subscribers
`lists:get`	View lists
`lists:manage`	Create, update, delete lists
`lists:manage_all`	Manage all lists (bypass list role restrictions)
`campaigns:get`	View campaigns
`campaigns:get_all`	View all campaigns
`campaigns:manage`	Create, update, delete campaigns
`campaigns:manage_all`	Manage all campaigns
`campaigns:get_analytics`	View campaign analytics
`templates:get`	View templates
`templates:manage`	Create, update, delete templates
`media:get`	View media files
`media:manage`	Upload, delete media files
`bounces:get`	View bounces
`bounces:manage`	Delete bounces, blocklist subscribers
`settings:get`	View settings
`settings:manage`	Update settings
`settings:maintain`	Run maintenance operations
`users:get`	View users
`users:manage`	Create, update, delete users
`roles:get`	View roles
`roles:manage`	Create, update, delete roles
`tx:send`	Send transactional emails
`webhooks:post_bounce`	Post to bounce webhooks

Use Cases

Create a Campaign Manager Role

Create a role for users who can manage campaigns but not subscribers or settings:

curl -u 'admin:password' -X POST http://localhost:9000/api/roles/users \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Campaign Manager",
    "permissions": [
      "campaigns:get",
      "campaigns:manage",
      "templates:get",
      "templates:manage",
      "media:get",
      "media:manage",
      "subscribers:get"
    ]
  }'

Create a Read-Only Analyst Role

Create a role for analytics and reporting without edit permissions:

curl -u 'admin:password' -X POST http://localhost:9000/api/roles/users \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Analyst",
    "permissions": [
      "campaigns:get",
      "campaigns:get_all",
      "campaigns:get_analytics",
      "subscribers:get",
      "subscribers:get_all",
      "lists:get"
    ]
  }'

Create an API User for Integrations

Create an API-only user for external integrations:

curl -u 'admin:password' -X POST http://localhost:9000/api/users \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "integration@example.com",
    "name": "External Integration",
    "password": "api-key-here",
    "type": "api",
    "status": "enabled",
    "role_id": 5
  }'

Best Practices

Principle of Least Privilege

Assign users only the permissions they need for their role. Start with minimal permissions and add more as needed.

Separate API Users

Create dedicated API users (type: api) for integrations rather than using regular user accounts.

Regular Audits

Periodically review user accounts and permissions to ensure they’re still appropriate.

Document Custom Roles

Maintain documentation of your custom roles and their intended use cases.

API Overview

Endpoints

Users API

Get All Users

Get Single User

Create User

Update User

Delete User

Bulk Delete Users

User Profile

Get Current User Profile

Update Current User Profile

Two-Factor Authentication (2FA)

Generate TOTP QR Code

Enable TOTP 2FA

Disable TOTP 2FA

Roles API

Get User Roles

Get List Roles

Create User Role

Create List Role

Update User Role

Update List Role

Delete Role

Permission Reference

Use Cases

Best Practices

Principle of Least Privilege

Separate API Users

Regular Audits

Document Custom Roles

Build docs developers (and LLMs) love

API Overview

Endpoints

​Users API

​Get All Users

​Get Single User

​Create User

​Update User

​Delete User

​Bulk Delete Users

​User Profile

​Get Current User Profile

​Update Current User Profile

​Two-Factor Authentication (2FA)

​Generate TOTP QR Code

​Enable TOTP 2FA

​Disable TOTP 2FA

​Roles API

​Get User Roles

​Get List Roles

​Create User Role

​Create List Role

​Update User Role

​Update List Role

​Delete Role

​Permission Reference

​Use Cases

​Best Practices

Principle of Least Privilege

Separate API Users

Regular Audits

Document Custom Roles

Build docs developers (and LLMs) love

Users API

Get All Users

Get Single User

Create User

Update User

Delete User

Bulk Delete Users

User Profile

Get Current User Profile

Update Current User Profile

Two-Factor Authentication (2FA)

Generate TOTP QR Code

Enable TOTP 2FA

Disable TOTP 2FA

Roles API

Get User Roles

Get List Roles

Create User Role

Create List Role

Update User Role

Update List Role

Delete Role

Permission Reference

Use Cases

Best Practices