Liệt kê vai trò

Mọi vai trò trên không gian làm việc, vai trò dựng sẵn trước, kèm số người và số khóa đang giữ mỗi vai trò.

export OE=https://api.openemail.ukexport AUTH="Authorization: Bearer $OPENEMAIL_API_KEY"

VAI TRÒ cho biết ai đó được LÀM gì trong không gian làm việc này: đọc thư, gửi thư, chỉnh sửa mẫu, thêm tên miền. QUYỀN CẤP cho biết họ được làm điều đó với những ĐỊA CHỈ nào, và nằm ngay bên cạnh tại /members/{userId}/addresses dưới dạng member (đọc địa chỉ và gửi thư với tư cách địa chỉ đó) hoặc viewer (chỉ đọc). Cả hai phải đồng ý trước khi thư được gửi đi: một vai trò có emails:send mà không có quyền cấp thì không thể gửi từ đâu cả, và mọi địa chỉ trong không gian làm việc dưới quyền cấp viewer cũng không thể gửi từ đâu cả.

Mọi không gian làm việc được seed cùng sáu vai trò. Owner, Admin, Member và Viewer tạo thành một bậc thang. Mỗi vai trò có mọi thứ mà vai trò kế tiếp có, nên hạ cấp ai đó sẽ thu hẹp quyền truy cập của họ thay vì đổi sang một phần khác. Developer và Billing không phải bậc trên thang đó: Developer xây dựng tích hợp (khóa, webhook, mẫu, gửi thư) và không đọc thư nào của không gian làm việc, còn Billing thấy gói và hóa đơn và không gì khác. Cả hai đều nằm hoàn toàn bên trong Admin. Chúng được seed ở lần đọc đầu tiên thay vì khi tạo không gian làm việc, nên một không gian làm việc được tạo trước khi tính năng này tồn tại sẽ có chúng ngay khi có bất kỳ thứ gì yêu cầu. builtin cho biết một hàng đến từ bản seed nào, và đó là toàn bộ những gì nó cho biết: sáu vai trò là điểm khởi đầu mà không gian làm việc được kỳ vọng sẽ điều chỉnh, và mọi vai trò trừ Owner đều có thể được đổi tên, đặt lại quyền và xóa. Hãy rẽ nhánh theo editable và deletable thay vì theo tên: một vai trò đã bị đổi tên vẫn trả lời đúng hai trường đó, còn tên của nó không còn cho bạn biết gì nữa.

Owner là ngoại lệ duy nhất, và là ngoại lệ theo mọi hướng: editable: false, deletable: false, và bị từ chối làm đích trên PATCH /members/{userId}. Nó mô tả tài khoản mà không gian làm việc gắn với và có mọi quyền, kể cả những quyền được thêm trong bản phát hành sau, đó là lý do danh sách của nó được tính toán thay vì lưu trữ. Đưa người khác trở thành chủ sở hữu là chuyển nhượng không gian làm việc; không có endpoint nào ở đây thực hiện điều đó.

Năm vai trò còn lại chấp nhận mọi thứ: danh sách quyền mới, mô tả mới, tên mới, lệnh DELETE. Chúng là mặc định được seed chứ không phải cố định: một không gian làm việc không bao giờ xây dựng tích hợp nên có thể loại bỏ Developer, và một nơi mà “Member” mang nghĩa hẹp hơn nên có thể nói điều đó bằng từ ngữ của riêng mình. Chỉ owner từ chối, và từ chối tất cả dưới một mã: role_immutable, mã 409 kèm param: "roleId", dù lệnh PATCH chứa tên hay danh sách quyền. Không còn việc đổi tên nào bị từ chối riêng lẻ nữa, nên không có trường hợp bất biến param: "name" nào cần xử lý; mã 409 duy nhất mà một tên còn có thể gây ra là role_name_taken, khi một vai trò khác trên không gian làm việc đã dùng tên đó.

Ngoài sáu vai trò đó, một không gian làm việc có thể tự tạo tối đa 24 vai trò. Mức trần chỉ đếm các vai trò này, nên xóa một vai trò được seed không tạo thêm chỗ. Quyền được MỞ RỘNG khi nhập vào thay vì được hiểu theo nghĩa đen (chỉ templates:write sẽ được lưu thành templates:read và templates:write), vì vậy hãy đọc lại danh sách từ phản hồi thay vì giả định đó là danh sách bạn đã gửi.

Cần roles:read. Không dùng cursor. Envelope mang hasMore và nextCursor để client có thể đưa nó vào cùng đoạn mã xử lý danh sách như mọi tập hợp khác, và không bao giờ có trang thứ hai.

curl "$OE/roles" -H "$AUTH"

{  "object": "list",  "data": [    {      "object": "role",      "id": "role_1c94e05d3862c1f0a44b7f3a",      "name": "Owner",      "description": "The person the workspace belongs to. Holds everything, including additions.",      "permissions": ["emails:send", "emails:read", "…", "workspace:manage"],      "builtin": "owner",      "editable": false,      "deletable": false,      "members": 0,      "apiKeys": 2,      "createdAt": "2026-08-01T09:00:00.000Z",      "updatedAt": "2026-08-01T09:00:00.000Z"    },    {      "object": "role",      "id": "role_c40a95f21cc65d31c2a89e07",      "name": "Viewer",      "description": "Reads the mail on the addresses they hold, and changes nothing.",      "permissions": [        "emails:read",        "drafts:read",        "threads:read",        "labels:read",        "contacts:read",        "calendar:read",        "templates:read",        "rules:read",        "connections:read",        "settings:read"      ],      "builtin": "viewer",      "editable": true,      "deletable": true,      "members": 3,      "apiKeys": 1,      "createdAt": "2026-08-01T09:00:00.000Z",      "updatedAt": "2026-08-01T09:00:00.000Z"    }  ],  "hasMore": false,  "nextCursor": null}