Rolleri listele
Çalışma alanındaki her rol, önce yerleşikler; her birini kaç kişinin ve kaç anahtarın taşıdığıyla.
Gerçek çağrıyı kendi anahtarınızla çalışma alanınıza karşı çalıştırır.
GET /roles
Çalışma alanındaki her rol, önce yerleşikler; her birini kaç kişinin ve kaç anahtarın taşıdığıyla.
İki eksen var ve aynı soruyu sormuyorlar
export OE=https://api.openemail.ukexport AUTH="Authorization: Bearer $OPENEMAIL_API_KEY"Bir ROL, birinin bu çalışma alanında NE YAPABİLECEĞİNİ söyler: postayı okumak, göndermek, şablonları düzenlemek, alan adı eklemek. Bir YETKİ ise bunu hangi ADRESLERE yapabileceğini söyler ve hemen yanında, /members/{userId}/addresses üzerinde member (adresi okur ve onun adına gönderir) ya da viewer (yalnızca okur) olarak durur. Bir mesaj çıkmadan önce ikisinin de onay vermesi gerekir: emails:send taşıyan ama hiç yetkisi olmayan bir rol hiçbir adresten gönderemez; çalışma alanındaki tüm adreslere viewer yetkisiyle sahip olan biri de yine hiçbir adresten gönderemez.
Her çalışma alanı aynı altı rolle başlar. Owner, Admin, Member ve Viewer bir merdiven oluşturur. Her biri bir alttakinin sahip olduğu her şeye sahiptir; dolayısıyla birinin rolünü düşürmek erişimini farklı bir dilimle değiştirmez, daraltır. Developer ve Billing bu merdivenin basamakları değildir: Developer entegrasyonlar kurar (anahtarlar, webhook'lar, şablonlar, gönderim) ve çalışma alanının postasının hiçbirini okumaz; Billing ise planı ve faturaları görür, başka hiçbir şeyi görmez. İkisi de tamamen Admin'in içinde kalır. Çalışma alanı oluşturulurken değil ilk okumada oluşturulurlar; bu yüzden bu özellikten önce oluşturulmuş bir çalışma alanı, herhangi bir şey sorduğu anda bu rollere kavuşur. builtin bir satırın hangi şablondan geldiğini adlandırır ve adlandırdığı şey bundan ibarettir: bu altısı, bir çalışma alanının kendine göre şekillendirmesi beklenen bir başlangıç noktasıdır ve Owner dışında hepsi yeniden adlandırılabilir, izinleri değiştirilebilir ve silinebilir. Ada göre değil, editable ve deletable değerlerine göre dallanın: birinin yeniden adlandırdığı bir rol bu ikisini hâlâ doğru yanıtlar, ama adı size artık hiçbir şey söylemez.
Owner tek istisnadır ve her yönden bir istisnadır: editable: false, deletable: false ve PATCH /members/{userId} üzerinde hedef olarak reddedilir. Çalışma alanının bağlı olduğu hesabı tarif eder ve sonraki bir sürümde eklenenler dahil her izne sahiptir; listesinin saklanmak yerine hesaplanmasının nedeni budur. Başka birini sahip yapmak bir çalışma alanı devridir; burada bunu yapan bir uç nokta yoktur.
Diğer beşi her şeyi kabul eder: yeni bir izin listesi, yeni bir açıklama, yeni bir ad, bir DELETE. Bunlar sabit parçalar değil, hazır gelen varsayılanlardır: hiç entegrasyon kurmayan bir çalışma alanı Developer'dan kurtulabilmeli ve "Member"ın daha dar bir anlam taşıdığı bir çalışma alanı bunu kendi sözcükleriyle söyleyebilmelidir. Yalnızca owner reddeder ve hepsini tek bir kodla reddeder: PATCH ister bir ad ister bir izin listesi taşısın, param: "roleId" taşıyan bir 409, role_immutable. Artık hiçbir yeniden adlandırma tek başına reddedilmez; dolayısıyla ele alınacak bir param: "name" değişmezliği yoktur. Bir adın hâlâ yol açabileceği tek 409, çalışma alanındaki başka bir rol zaten o adı taşıdığında dönen role_name_taken'dır.
Bu altısının ötesinde bir çalışma alanı kendine ait 24 role kadar tanımlayabilir. Tavan yalnızca bunları sayar; dolayısıyla hazır gelen bir rolü silmek bu tavanın altında yer açmaz. İzinler harfiyen alınmak yerine girişte GENİŞLETİLİR (templates:write tek başına templates:read ve templates:write olarak saklanır); bu yüzden listenin gönderdiğinizle aynı olduğunu varsaymak yerine yanıttan geri okuyun.
Bir rol aynı zamanda bir API anahtarının tavanıdır. Bir role bağlı olarak verilen anahtar key.scopes ∩ role.permissions kadarını yapabilir, fazlasını değil; bu sınırda istek başına çözümlenir. Dolayısıyla bir rolü düzenlemek, anahtarlarının daha bir sonraki çağrıda ne yapabileceğini değiştirir ve rolü olmayan bir anahtarın hiç tavanı yoktur. Bunun tamamı Kapsamlar sayfasında.
Örnek
roles:read gerektirir. Cursor'suzdur. Zarf hasMore ve nextCursor taşır; böylece bir istemci bunu diğer her koleksiyonla aynı liste koduna verebilir ve asla ikinci bir sayfa olmaz.
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}API'nin geri kalanı gibi en yeniden eskiye değil, önce yerleşik sırasına sonra ada göre sıralanır (owner, admin, member, viewer, developer, billing, ardından alfabetik olarak geri kalanlar). Bir izin matrisi merdiven gibi okunur ve onu createdAt'e göre sıralamak en geniş rolü her hafta farklı bir satıra koyar.
Hiç rolü olmamış bir çalışma alanında altı rolü OLUŞTURAN şey bu listeyi okumaktır. Oluşturma benzersiz bir indekste çakışır ve ikinci seferde hiçbir şey yapmaz; dolayısıyla çağrı idempotenttir ve yalnızca ilki yazar. POST /members'ın her zaman var olan bir roleId adlandırabilmesinin nedeni de budur.
Yalnızca BİR KEZ oluşturur. Çalışma alanı oluşturmanın yapıldığını kaydeder; dolayısıyla bu okuma, özellikten eski bir çalışma alanını doldurur ve bir daha asla yazmaz. Hazır gelen bir rolü silmeyi kalıcı yapan da budur. Daha eski bir sürüm eksik olan şablon satırını her okumada yeniden ekliyordu; bu yüzden silinen bir Billing bir sonraki sayfa yüklemesinde yeni bir id ile geri geliyordu. Artık gelmiyor.
members ve apiKeys, rol silinebilmeden önce taşınması gerekenlerdir; bu da bir istemcinin 409'dan sonra değil, silmeyi sunmadan önce uyarabilmesini sağlar. Owner satırı genellikle members: 0 gösterir: sahip, kendi çalışma alanının üyesi değildir; çalışma alanının bağlı olduğu hesaptır.
Bunun tek bir yanıt olabilmesi için 24 özel rollük katı bir tavan vardır. Kırk rolü olan bir çalışma alanı "billing@ adına kim gönderebilir" sorusunu bakarak yanıtlayamaz ve bu özellik yalnızca bu soruyu yanıtlanabilir kılmak için vardır.