# List accounts

`GET https://api.mailmasker.org/api/v1/admin/users`

Every account with its roles and whether it can sign in, or a quick search by address.

- Who can use it: Site admins
- Area: Users and roles
- Answers 200 OK when it works
- Page: https://developer.mailmasker.org/admin-list-users

Without a search, every account comes back, oldest first. `active` is 1 for an account that can sign in and 0 for a suspended one. The list includes the system's own non-person accounts too: one for each node's agent and one the api uses itself, all with the `system_agent` role.

## Parameters

| Name | In | Required | What it is | Example |
|---|---|---|---|---|
| `q` | query | no | Only accounts whose address starts with this text, ignoring case. At least 3 characters. |  |
| `limit` | query | no | With q, the most accounts to return, from 1 to 100. The default is 20. |  |

## Good to know

- A search comes back in address order. One shorter than 3 characters answers an empty list.

## Examples

cURL:

```bash
curl -s 'https://api.mailmasker.org/api/v1/admin/users' \
  -H "Authorization: Bearer $TOKEN"
```

Perl:

```perl
use Mojo::Base -strict;
use Mojo::UserAgent;

my $ua  = Mojo::UserAgent->new;
my $res = $ua->get('https://api.mailmasker.org/api/v1/admin/users',
    { Authorization => "Bearer $ENV{TOKEN}" })->result;
die $res->code, ' ', ($res->json('/error') // $res->message), "\n" unless $res->is_success;
print $res->body, "\n";
```

homelab-cli:

```bash
homelab-cli admin users list
```

## Response

200 OK:

```json
[
  {
    "id": 1,
    "email": "you@example.com",
    "active": 1,
    "created_at": "2026-10-12 14:03:51.402117-05",
    "roles": ["user", "site_admin"]
  },
  {
    "id": 7,
    "email": "alice@example.com",
    "active": 1,
    "created_at": "2026-10-20 09:15:02.551873-05",
    "roles": ["user", "auditor"]
  },
  {
    "id": 9,
    "email": "bob@example.com",
    "active": 0,
    "created_at": "2026-10-28 18:40:37.004512-05",
    "roles": ["user"]
  }
]
```