Miembros
`members->list`, `listAll`, `iterate`, `get`, `add`, `update`, `remove`, `grantAddress`, `revokeAddress`, `grantDomain`, `revokeDomain` y los métodos de invitaciones junto a ellos.
Todos los métodos
$supportRoleId = 'role_8b1f4c2e9a7d3b60e5f1a2c4';$viewerRoleId = 'role_2c7e9a1f4b8d3e60c5a7f1b9'; $invitation = $client->members->add([ 'email' => '[email protected]', 'roleId' => $supportRoleId, 'addressIds' => ['2b81de07-9c3f-4a61-b8e2-5d07f4c19a36'], 'access' => 'member',]);echo $invitation['id'], ' ', $invitation['expiresAt'], PHP_EOL; foreach ($client->members->listAll() as $person) { echo $person['email'], ' ', $person['userId'], PHP_EOL;} $samId = 'q7Vd3kX9mT2pLw8RzN4bYc6HfJ1sGa5E';$member = $client->members->get($samId);echo $member['role']['name'], $member['implied'] ? ' (implied)' : '', PHP_EOL; $client->members->update($samId, ['roleId' => $viewerRoleId]); $addressId = 'c40a95f2-1e7b-4d38-a6c9-82f05b3d7e14';$client->members->grantAddress($samId, ['addressId' => $addressId, 'access' => 'viewer']);$client->members->revokeAddress($samId, $addressId); $removed = $client->members->remove($samId);echo $removed['addressesRevoked'], PHP_EOL;Dos concesiones por persona, y no deben fusionarse. role es lo que puede hacer. addresses y domains son aquello sobre lo que puede hacerlo. Ambas tienen que coincidir: un rol con emails:send y access igual a viewer sobre invoices@ es alguien que puede enviar correo y no puede enviarlo desde esa dirección. La excepción es un rol con addresses:all, que llega a todas las direcciones liste lo que liste addresses, porque ese array solo contiene concesiones directas. Así que comprueba permissions antes de leer addresses como todo el alcance de alguien.
Cada llamada sobre una persona recibe su userId como primer argumento, no su correo, así que léelo de list o listAll como hace el ejemplo. add es la única excepción, porque invita a una dirección: la persona solo tiene un userId una vez que acepta, y listInvitations sigue la invitación hasta entonces. El cuerpo de add, update, grantAddress y grantDomain es un solo array con los nombres en camelCase de la API (roleId, addressIds, addressId).
list devuelve una OpenEmail\Result\Page, listAll devuelve todos los miembros en un solo array, e iterate devuelve un Generator que entrega un miembro cada vez. Un miembro vuelve como un array con claves en camelCase, y role es un array dentro de él, así que $member['role']['name'] lee el nombre del rol.
implied en true significa que nadie eligió el rol. La persona tiene direcciones o dominios y ninguna fila de rol, así que se dedujo a partir de la concesión más amplia que posee. Trátalo como «aún sin decidir»: update es lo que convierte la inferencia en una decisión. Hasta entonces, ampliar su acceso a direcciones amplía en silencio lo que puede hacer.
El propietario del espacio de trabajo es la primera fila, con isOwner en true, mientras que add, update y remove lo siguen rechazando con member_is_owner, un 422 lanzado como una ValidationException. Un espacio de trabajo sin compartir informa de un miembro y no de ninguno, así que excluye isOwner cuando cuentes puestos: count(array_filter($client->members->listAll(), fn(array $member): bool => !$member['isOwner'])).
remove actúa sobre los dos ejes: el rol Y todas las concesiones de direcciones y dominios en este espacio de trabajo, e informa en addressesRevoked de cuántas concesiones retiró, dominios incluidos. revokeAddress es el acotado, para alguien que cambió de equipo y no para alguien que se marchó, y revokeDomain hace lo mismo para un dominio entero.
add, update, remove y las cuatro llamadas de concesión y revocación piden un código de verificación a un token de acceso OAuth, y a una clave de API nunca. Hasta que el token tenga uno, lanzan una PermissionException cuyo isStepUpRequired() es true. add y grantDomain también necesitan un plan que incluya acceso de equipo, y en uno que no lo incluya lanzan una PermissionException con errorCode igual a plan_required.
Parámetros
emailstringobligatorio- A quién invitar, recortado y en minúsculas. Todavía no necesita una cuenta: se invita a cualquiera, y el rol y las concesiones se aplican cuando acepta. Alguien que ya está en el espacio de trabajo devuelve `member_is_owner` (422). Una dirección que inicia sesión con una contraseña propia no se puede invitar y devuelve `mailbox_login` (403), así que invita en su lugar al correo propio de la persona.
roleIdstringobligatorio- El rol que tendrá, de 1 a 128 caracteres, y debe ser un rol de este espacio de trabajo: un id desconocido es `role_not_found` (404), lanzado como una `NotFoundException`. El rol de propietario no se puede repartir y devuelve `role_immutable` (409), porque convertir a alguien en propietario es una transferencia del espacio de trabajo y aquí no hay ninguna llamada para eso.
addressIdsarray- Direcciones que lleva la invitación, como máximo 64 ids de 1 a 128 caracteres cada uno, concedidas cuando se acepta. Cada id se comprueba antes de escribir nada, así que uno que no corresponde a una dirección de este espacio de trabajo hace que se rechace toda la llamada con 422 `member_not_found` y no se envía nada. Invitar de nuevo a la misma dirección en menos de diez minutos es 409 `invitation_too_soon`.
domainIdsarray- Dominios enteros que lleva la invitación, como máximo 64 ids, concedidos cuando se acepta. Una concesión de dominio llega a todas las direcciones de ese dominio, incluidas las que se creen después. Un id que no corresponde a un dominio de este espacio de trabajo es 422 `member_not_found`, como con una dirección.
accessstring- Lo que puede hacer con cada id de `addressIds` y `domainIds`: `member` lee la dirección y envía desde ella, `viewer` solo la lee. El valor por defecto es `member`, el nivel que siempre han usado la consola y la antigua vía de compartición, de modo que la misma llamada significa lo mismo desde un script y desde una pantalla. Para conceder una combinación, llama después a `grantAddress` para las que difieran.
Respuesta
objectstring- Siempre `member`. Una eliminación responde con el mismo valor, su `userId`, `deleted` en true y `addressesRevoked`, y ninguno de los demás campos de abajo.
userIdstring- El id de su cuenta, y el identificador que todas las demás llamadas de miembros reciben como primer argumento: `get`, `update`, `remove` y las cuatro llamadas de concesión y revocación. Añadir a alguien es la única llamada que funciona en cambio a partir de un correo, porque quien añade a un compañero conoce su dirección y no su id.
emailstring- El correo de su cuenta, devuelto tal como lo guarda esa fila. Este recurso nunca lo escribe, y la conversión a minúsculas de `add` se aplica a la dirección que envías para la búsqueda, no a lo que vuelve. Después del propietario, la lista de miembros se ordena por él y no por la fecha de incorporación, porque la lista se lee para encontrar a una persona y no para ver qué cambió.
namestring or null- Su nombre visible, tomado de su cuenta, donde la columna siempre tiene un valor. El null del tipo es defensivo, no un estado que se haya visto producir a esta API. Pertenece a la persona y no al espacio de trabajo, así que nada de este recurso puede establecerlo.
imagestring or null- Su avatar, tomado de su cuenta, y null cuando no ha configurado ninguno.
role.idstring or null- El id del rol que tiene, que se lee con `$member['role']['id']`, o null cuando nadie lo eligió. Véase `implied`. Un null aquí es el único caso en el que `role` informa de una inferencia y no de una decisión que alguien tomó.
role.namestring- El nombre del rol. Para un miembro implícito es el nombre de la plantilla integrada a la que corresponde su acceso, no una fila de este espacio de trabajo.
role.builtinstring or null- Qué rol integrado es, `owner`, `admin`, `member`, `viewer`, `developer` o `billing`, o null si es personalizado. `owner` aparece únicamente en la fila del propio propietario, junto a `isOwner` en true. Asignar ese rol a alguien se rechaza con `role_immutable` (409).
isOwnerbool- True en exactamente una fila: la cuenta a la que está vinculado el espacio de trabajo. Tiene todos los permisos diga lo que diga su fila de rol, se ordena en primer lugar, y `add`, `update` y `remove` la rechazan con `member_is_owner`. Exclúyela cuando cuentes puestos.
impliedbool- True cuando esta persona tiene concesiones de direcciones o dominios y ninguna fila de miembro, de modo que su rol se dedujo en vez de elegirse. Cualquier concesión de `member` lo convierte en el rol integrado Member, y si no, en Viewer. Nunca es true para el propietario. Muéstralo como «implícito por acceso». Hasta que un `update` convierta la inferencia en una decisión, ampliar su acceso a direcciones amplía en silencio lo que puede hacer.
permissionsarray- Los permisos del rol aplanados sobre el miembro, de modo que una sola lectura responde a «¿puede hacerlo?» sin tener que obtener el rol. Para un miembro implícito provienen de la PLANTILLA integrada y no de la fila de rol de este espacio de trabajo, así que editar el rol Member integrado no cambia lo que tiene un miembro implícito.
addressesarray- Las direcciones que se le han dado, ordenadas por dirección, un array por cada una con su propio nivel de acceso. Vacío para alguien que tiene un rol y ninguna concesión, que es el aspecto de un miembro nuevo hasta que se le concede una dirección, y es el fallo correcto mientras todavía estás decidiendo qué debería ver.
addresses[].addressIdstring- El id de la dirección, y lo que reciben `grantAddress` y `revokeAddress`. Un id que no corresponde a una dirección de este espacio de trabajo se rechaza en ambos, en lugar de informar de una revocación que nunca ocurrió.
addresses[].addressstring- La dirección completa, en minúsculas, reconstruida a partir de su parte local y su dominio.
addresses[].accessstring- Lo que puede hacer con esta dirección concreta: `member` la lee y envía desde ella, `viewer` solo la lee. Tanto esto como el rol tienen que permitir un envío para que se produzca, así que un rol con `emails:send` sobre una concesión `viewer` no envía desde ninguna dirección. La columna almacenada se llama `role`, y aquí se renombra para que un mismo array no lleve dos claves `role` procedentes de dos vocabularios distintos.
domainsarray- Los dominios enteros que se le han dado, cada uno con `domainId`, `domain` y `access`. Una concesión de dominio llega a todas las direcciones del dominio, incluidas las que se creen después, así que léela junto a `addresses` antes de decidir que alguien no llega a una dirección. `grantDomain` y `revokeDomain` reciben el `domainId`.
createdAtstring or null- Cuándo se escribió su fila de miembro, como cadena ISO 8601, y null cuando no existe ninguna fila de miembro. Ese null describe el mismo grupo que `implied` en true: personas con concesiones de antes de que existieran los roles y a las que nadie ha asignado un rol desde entonces.
Invitaciones
$waiting = $client->members->listAllInvitations(); foreach ($waiting as $invitation) { if ($invitation['expired']) { $client->members->resendInvitation($invitation['id']); }} $client->members->revokeInvitation('winv_6bb640f5b99e47deb758f1f5');add responde con una invitación, y estas son las llamadas que le dan seguimiento. listInvitations devuelve una OpenEmail\Result\Page de las que nadie ha aceptado todavía, listAllInvitations las devuelve todas en un solo array, e iterateInvitations devuelve un Generator que entrega una cada vez. resendInvitation vuelve a enviar una con un enlace nuevo y catorce días más, y revokeInvitation la retira. Una invitación pendiente no concede nada hasta que se acepta.
Una invitación es un array con id, email, role, addresses, domains, expiresAt, expired, lastSentAt y createdAt. delivered y deliveryError informan de cómo le fue al último correo de invitación, de modo que un script puede distinguir una invitación que se escribió de una que llegó a alguien.
resendInvitation rechaza la misma dirección dos veces en diez minutos con 409 invitation_too_soon, y revokeInvitation rechaza una que se aceptó antes con 409 invitation_accepted. Ambos se lanzan como una ConflictException, así que isConflict() es true y errorCode los distingue.