API

فهرست اعضا

همهٔ افراد فضای کاری، نقشی که هر کس دارد، و نشانی‌هایی که به هر کس داده شده است.

GETapi.openemail.uk/members

فراخوانی واقعی را با کلید خودتان روی فضای کاری شما اجرا می‌کند.

GET /members

همهٔ افراد فضای کاری، نقشی که هر کس دارد، و نشانی‌هایی که به هر کس داده شده است.

یک عضو دو دسترسی است، نه یکی

shell

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

role می‌گوید او چه کاری می‌تواند بکند: یک سطر، یک نقش، همان شیئی که /roles توصیفش می‌کند. addresses می‌گوید آن کار را روی چه چیزی می‌تواند بکند: به ازای هر نشانی یک مدخل، که هر کدام access خودش را دارد. کلاینت نباید این دو را در هم بریزد: نقشی که emails:send دارد با آرایهٔ addresses خالی یعنی کسی که از هیچ‌جا می‌تواند ارسال کند، و آرایهٔ addresses پر زیر نقش viewer هم یعنی کسی که از هیچ‌جا می‌تواند ارسال کند. مسیر ارسال هر دو را بررسی می‌کند، و صفحه‌ای که یکی از آن‌ها را نشان دهد با اطمینان ردشدن اشتباهی را توضیح خواهد داد.

سطرهای نشانی access می‌گویند در حالی که ستون ذخیره‌شده role است، و این تغییر نام خودِ نکته است نه مرتب‌کاری: این شیء همین حالا فیلدی به نام role دارد که معنای کاملاً دیگری می‌دهد، و دو role با یک سطح تودرتویی فاصله که مقادیرشان از دو واژگان متفاوت می‌آید باگی است که منتظر نخستین کسی است که با عجله بخواندش. access یا member است، که نشانی را می‌خواند و با آن ارسال می‌کند، یا viewer، که تنها آن را می‌خواند.

implied: true یعنی هیچ‌کس این نقش را انتخاب نکرده است. اشتراک‌گذاری خیلی پیش از نقش‌ها عرضه شد، پس بیشتر کسانی که به یک صندوق پستی دسترسی دارند دسترسی‌های اعطاشدهٔ نشانی دارند و اصلاً سطر عضو ندارند؛ به جای آنکه تا اجرای یک backfill نامه‌شان از آن‌ها دریغ شود، سرویس از گسترده‌ترین دسترسی‌ای که دارند یک نقش داخلی استنباط می‌کند و آن را با role.id برابر null گزارش می‌کند. آن را به صورت «استنباط‌شده از دسترسی» نشان دهید نه نقشی که کسی برگزیده است. تا وقتی یک PATCH آن استنباط را به تصمیم بدل نکند، گسترده‌ترکردن دسترسی نشانی او بی‌صدا کارهایی را که می‌تواند بکند گسترده‌تر می‌کند.

مالک نخستین سطر است، با نشان isOwner: true و role.builtin برابر owner. او حسابی است که فضای کاری بر پایه‌اش کلید خورده، طبق تعریف همهٔ مجوزها را دارد، و POST، PATCH و DELETE هر سه او را با member_is_owner رد می‌کنند. پس فضای کاری‌ای که به اشتراک گذاشته نشده یک عضو گزارش می‌کند نه هیچ عضوی. برای شمردن صندلی‌ها isOwner را کنار بگذارید.

نمونه

نیازمند members:read است. مالک اول می‌آید، سپس بقیه بر اساس ایمیل و نه بر اساس زمان پیوستن، چون این فهرست برای یافتن یک شخص خوانده می‌شود نه برای دیدن آنچه تغییر کرده است.

curl

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

پاسخ

{  "object": "list",  "data": [    {      "object": "member",      "userId": "nQ8vBz1aRd4tYwKx7fQ2mN8vBz1aRd4t",      "email": "[email protected]",      "name": "Sam Okonjo",      "image": null,      "role": {        "id": "role_2b81de079c1f0a4b7e05d386",        "name": "Support",        "builtin": null      },      "implied": false,      "permissions": [        "emails:send",        "emails:read",        "threads:read",        "threads:write",        "labels:read",        "labels:write",        "contacts:read"      ],      "addresses": [        {          "addressId": "2b81de07-9c1f-4a4b-8e05-d3862c1f0a44",          "address": "[email protected]",          "access": "member"        },        {          "addressId": "c40a95f2-1cc6-4d31-82a8-9e075d31c2a8",          "address": "[email protected]",          "access": "viewer"        }      ],      "createdAt": "2026-08-12T14:20:00.000Z"    },    {      "object": "member",      "userId": "7fQ2mN8vBz1aRd4tYwKx7fQ2mN8vBz1a",      "email": "[email protected]",      "name": null,      "image": null,      "role": { "id": null, "name": "Viewer", "builtin": "viewer" },      "implied": true,      "permissions": [        "emails:read",        "drafts:read",        "threads:read",        "labels:read",        "contacts:read",        "calendar:read",        "templates:read",        "rules:read",        "connections:read",        "settings:read"      ],      "addresses": [        {          "addressId": "c40a95f2-1cc6-4d31-82a8-9e075d31c2a8",          "address": "[email protected]",          "access": "viewer"        }      ],      "createdAt": null    }  ],  "hasMore": false,  "nextCursor": null}

دو جمعیت در یک فهرست، و چاره‌ای هم نیست: کسی می‌تواند نقش داشته باشد و هیچ نشانی‌ای نداشته باشد، و کسی می‌تواند نشانی داشته باشد و هیچ سطر نقشی نداشته باشد. فهرست‌کردن تنها اشتراک آن دو هر دو را پنهان می‌کرد، و در بیشتر فضاهای کاری گروه دوم بزرگ‌تر است.

createdAt برای کسی که دسترسی‌های اعطاشده دارد اما هرگز سطر عضوی برایش نوشته نشده null است، همان کسانی که implied برایشان true است. این زمانی است که به او یک نقش داده شده، نه زمانی که نخستین بار نشانی‌ای با او به اشتراک گذاشته شده است.

permissions فهرست مسطح و حل‌شده است نه مجموعه‌ای از بولین‌ها. کلاینتی که می‌پرسد «آیا این شامل templates:write هست» نمی‌تواند از واژگان عقب بماند؛ کلاینتی که { canEditTemplates: true } تحویلش می‌دهید بی‌صدا می‌تواند.

بدون cursor، با همان پاکت استاندارد. اعضای یک فضای کاری به تعداد کسانی محدود است که مالکش واقعاً آن را با آن‌ها به اشتراک گذاشته، و صفحه‌بندی آن تشریفاتی می‌بود جلوی چیزی که کلاینت یک بار می‌گیرد و یکجا رندر می‌کند.