SDK
Leden
`members.list`, `get`, `add`, `update`, `remove`, `grantAddress` en `revokeAddress`.
Elke methode
const people = await openemail.members.list()const member = await openemail.members.get(people[0]!.userId) const sam = await openemail.members.add({ email: '[email protected]', roleId: support.id, addressIds: ['2b81de07-…'], access: 'member',}) await openemail.members.update(sam.userId, { roleId: viewerRoleId }) await openemail.members.grantAddress(sam.userId, { addressId: 'c40a95f2-…', access: 'viewer',})await openemail.members.revokeAddress(sam.userId, 'c40a95f2-…') await openemail.members.remove(sam.userId)Twee toekenningen per persoon, en ze mogen niet samengevoegd worden. role bepaalt wat iemand mag doen; addresses bepaalt waarop. Beide moeten het eens zijn: een rol met emails:send en access: "viewer" op invoices@ hoort bij iemand die e-mail mag versturen, maar niet vanaf dat adres.
Elke methode neemt de userId, niet het e-mailadres. add is de enige uitzondering, en daar is precies de reden voor de uitzondering te vinden: de aanroeper heeft wel een e-mailadres en nog geen user id, en dat is de hele eerste helft van wat die aanroep doet.
implied: true betekent dat niemand de rol gekozen heeft. De persoon heeft adressen en geen rolrij, dus de rol is afgeleid uit de ruimste toekenning die hij heeft. Lees het als “nog niet beslist”; met update wordt de afleiding een beslissing. Tot die tijd verruimt elke uitbreiding van zijn adrestoegang stilzwijgend wat hij mag doen.
De eigenaar van de workspace is de eerste rij, gemarkeerd met isOwner: true, terwijl add, update en remove hem alsnog weigeren met member_is_owner. Een niet-gedeelde workspace meldt één lid in plaats van geen, dus sluit isOwner uit wanneer je seats telt.
remove pakt beide assen aan, de rol ÉN elke adrestoekenning op deze workspace, en rapporteert addressesRevoked. revokeAddress is de smalle variant, voor iemand die van team wisselt in plaats van iemand die vertrekt.
Parameters
emailstringverplicht- Wie je uitnodigt, getrimd en omgezet naar kleine letters. Er hoeft nog geen account te bestaan: iedereen wordt uitgenodigd, en de rol en de toekenningen landen zodra de uitnodiging wordt aangenomen. Iemand die al in de workspace zit, levert `member_is_owner` (422) op.
roleIdstringverplicht- De rol die deze persoon krijgt, 1 tot 128 tekens, en het moet een rol op deze workspace zijn: een onbekend id levert `role_not_found` (404) op. De owner-rol kan niet worden uitgedeeld en komt terug als `role_immutable` (409), want iemand tot eigenaar maken is een overdracht van de workspace en daar bestaat hier geen aanroep voor.
addressIdsstring[]- Adressen die je in dezelfde aanroep meegeeft, maximaal 64 ids van elk 1 tot 128 tekens; een id dat geen adres op deze workspace is, wordt geweigerd. De rol wordt als eerste weggeschreven en de toekenningen volgen één voor één, dus een fout id laat het lid achter met minder adressen dan je gevraagd hebt. Dezelfde body opnieuw posten is de oplossing, want beide schrijfacties zijn upserts.
access'member' | 'viewer'- Wat de persoon mag met elk id in `addressIds`: `member` leest het adres en verstuurt er ook vanaf, `viewer` leest het alleen. Standaard `member`, het niveau dat de console en het oudere deelpad altijd al gebruikt hebben, zodat dezelfde aanroep hetzelfde betekent vanuit een script en vanuit een scherm; wil je een mix, roep dan achteraf `grantAddress` aan voor de adressen die afwijken.
Antwoord
object'member'- Altijd `member`. Een verwijdering antwoordt met dezelfde waarde, hun `userId`, `deleted: true` en `addressesRevoked`, en geen van de andere velden hieronder.
userIdstring- Hun account-id, en de sleutel die elke andere member-aanroep in het pad verwacht: get, update, remove en beide adresaanroepen. Iemand toevoegen is de enige aanroep die in plaats daarvan vanaf een e-mailadres werkt, omdat wie een collega toevoegt wel diens adres kent en niet diens id.
emailstring- Het e-mailadres op hun account, teruggegeven zoals die rij het opslaat. Deze resource schrijft het nooit, en het omzetten naar kleine letters bij `add` geldt voor het adres dat je meestuurt om op te zoeken, niet voor wat er terugkomt. Na de eigenaar is de ledenlijst hierop gesorteerd en niet op het moment van toetreden, omdat de lijst gelezen wordt om één persoon te vinden en niet om te zien wat er veranderd is.
namestring | null- Hun weergavenaam, overgenomen uit hun account, waar de kolom NOT NULL is. De null in het type is defensief en geen toestand die deze API ooit is zien produceren. De naam hoort bij de persoon en niet bij de workspace, dus niets op deze resource kan hem zetten.
imagestring | null- Hun avatar, overgenomen uit hun account, en null wanneer ze er geen hebben ingesteld.
role.idstring | null- Het id van de rol die ze hebben, of null wanneer niemand die gekozen heeft. Zie `implied`. Een null hier is het enige geval waarin `role` een afleiding rapporteert in plaats van een beslissing die iemand genomen heeft.
role.namestring- De naam van de rol. Bij een impliciet lid is het de naam van de ingebouwde template waar hun toegang naartoe herleid is, niet van een rij op deze workspace.
role.builtin'owner' | 'admin' | 'member' | 'viewer' | 'developer' | 'billing' | null- Welke ingebouwde rol dit is, of null bij een eigen rol. `owner` verschijnt alleen op de rij van de eigenaar zelf, naast `isOwner: true`; die rol aan wie dan ook toekennen wordt geweigerd met `role_immutable` (409).
isOwnerboolean- True op precies één rij: het account waarop de workspace gesleuteld is. Deze persoon heeft elke permissie, wat zijn rolrij ook zegt, staat als eerste in de sortering, en `add`, `update` en `remove` weigeren hem allemaal met `member_is_owner`. Sluit hem uit wanneer je seats telt.
impliedboolean- True wanneer deze persoon adrestoekenningen heeft en geen memberrij, zodat zijn rol is afgeleid in plaats van gekozen: elke toekenning van `member` herleidt naar de ingebouwde Member, anders naar Viewer. Nooit true voor de eigenaar. Toon het als "afgeleid uit toegang". Tot een PATCH van de afleiding een beslissing maakt, verruimt elke uitbreiding van zijn adrestoegang stilzwijgend wat hij mag doen.
permissionsPermission[]- De permissies van de rol, platgeslagen op het lid, zodat één read de vraag "mag deze persoon dit?" beantwoordt zonder de rol op te halen. Bij een impliciet lid komen ze uit de ingebouwde TEMPLATE en niet uit de rolrij van deze workspace, dus de ingebouwde Member-rol aanpassen verandert niets aan wat een impliciet lid heeft.
addressesMemberAddress[]- De adressen die aan deze persoon zijn toegekend, gesorteerd op adres, elk met zijn eigen toegangsniveau. Leeg voor iemand met een rol en zonder toekenningen: zo ziet een nieuw lid eruit tot er een adres is toegekend, en dat is precies de juiste manier om te falen zolang je nog beslist wat iemand mag zien.
addresses[].addressIdstring- Het id van het adres, en wat `grantAddress` en `revokeAddress` verwachten. Een id dat geen adres op deze workspace is, wordt door beide geweigerd, in plaats van dat er een intrekking wordt gemeld die nooit heeft plaatsgevonden.
addresses[].addressstring- Het volledige adres, in kleine letters, opgebouwd uit het lokale deel en het domein.
addresses[].access'member' | 'viewer'- Wat de persoon met dit ene adres mag: `member` leest het en verstuurt er ook vanaf, `viewer` leest het alleen. Dit én de rol moeten allebei een verzending toestaan voordat die plaatsvindt, dus een rol met `emails:send` bovenop een `viewer`-toekenning verstuurt vanaf niets; de opgeslagen kolom heet `role` en is hier hernoemd, zodat één object niet twee keer `role` draagt uit twee verschillende vocabulaires.
createdAtstring | null- Wanneer hun memberrij is weggeschreven, ISO-8601, en null wanneer er helemaal geen memberrij is. Die null beschrijft dezelfde groep als `implied: true`: mensen die adressen hebben van vóór het bestaan van rollen en aan wie sindsdien niemand een rol heeft gegeven.