Claves, miembros y roles

Estos comandos deciden quién y qué puede llegar al espacio de trabajo. openemail keys gestiona las claves de API y lee lo que hizo cada una, openemail members gestiona las personas del espacio de trabajo y sus invitaciones, y openemail roles define lo que puede hacer un miembro o una clave. openemail me describe la clave o el inicio de sesión con el que llamas, y openemail languages lista los idiomas que acepta un envío traducido. Las bandejas desechables no necesitan ningún inicio de sesión: openemail temp es la forma cotidiana de usar una, y openemail temp-mail es cada llamada de la API que hay detrás. openemail api llega a cualquier endpoint al que no lleguen los demás comandos.

• —Un comando de clave acepta el id de la clave, los 24 caracteres hexadecimales que van después de oe_live_, tal como lo muestra keys list. Un comando de miembro acepta el id de cuenta, userId en members list, nunca una dirección de correo. Un comando de rol acepta un id role_ de roles list, porque los roles no se buscan por nombre.
• —Los espacios de nombres responden también a key, member, role, language y tempMail. Funcionan los alias de verbo habituales, como ls, show, new, edit y rm. En members, cuyos verbos son add y remove, new y create llevan a add, y rm, del y delete llevan a remove.
• —openemail <command> --help lista cada argumento y opción con su tipo, el scope que necesita la llamada, su método y ruta, y lo que devuelve. Añade --json para obtener la misma página como datos.

Leer claves necesita keys:read, y cada cambio necesita keys:manage. A un inicio de sesión con el navegador nunca se le conceden keys:write ni keys:manage, así que crear, cambiar, rotar, revocar y eliminar claves requiere una clave de API que tenga keys:manage, o la app web (openemail open api-keys). Un inicio de sesión con el navegador con keys:read solo lee claves para el propietario del espacio de trabajo, y el inicio de sesión de un miembro se rechaza con 403 owner_only.

• —keys create, keys rotate y me rotate muestran el secreto de la clave, en token, una vez, y luego la CLI avisa de que no se volverá a mostrar. Cada lectura muestra maskedKey en su lugar.
• —Si se omiten, una clave nueva tiene solo emails:send, y toma el rol, el alcance de envío y la caducidad de la clave que la crea. --domain-allowlist y --address-allowlist definen desde qué direcciones puede enviar, y --expires-in-minutes acepta de 5 a 5.256.000, que son diez años.
• —Una clave nunca crea ni alcanza una clave más amplia que ella misma. Los scopes, el rol, la caducidad, el modo y el alcance de envío tienen que caber dentro de la clave que llama, o la llamada se rechaza con 403 beyond_caller_authority, y param nombra lo que era demasiado amplio. Una clave limitada a algunos dominios o direcciones solo ve las claves dentro de su propio alcance de envío, y cualquier otra da 404.
• —keys update sustituye lo que envías: --scopes, --address-allowlist y --domain-allowlist aceptan cada uno la lista nueva entera, y una opción que omitas se queda como estaba. --no-enabled desactiva una clave, así que cada llamada con ella se rechaza con inactive_api_key, y --enabled la restaura exactamente. Así se detiene una clave de una forma que puedes deshacer.
• —keys revoke es para siempre: la clave no se puede volver a activar, rotar ni cambiar. keys delete solo quita una clave revocada, y cualquier otra se rechaza con 409 not_revoked. El registro de solicitudes y la actividad de una clave eliminada se quedan, bajo Clave eliminada.
• —keys rotate no tiene periodo de solapamiento, así que el secreto anterior deja de funcionar en cuanto vuelve el nuevo. Cuando la clave es la que usa tu perfil guardado, la CLI guarda el secreto nuevo en ese perfil, para que siga funcionando. Una clave de OPENEMAIL_API_KEY o --api-key no se puede guardar, así que la CLI te indica que guardes el token nuevo donde tuvieras la clave anterior.

El registro de solicitudes guarda cada llamada que hizo una clave: método, ruta, estado, código de error, duración, IP y agente de usuario, nunca un cuerpo ni una cadena de consulta. No se purga nada, así que llega hasta la primera llamada de una clave, y las llamadas hechas con un inicio de sesión con el navegador no están en él. El registro de actividad guarda cada cambio de una clave, y cada llamada que presentó la clave y se rechazó, como auth_failed, con quién hizo cada cambio en actor.

• —list-requests y list-activity leen una clave. list-workspace-requests y list-workspace-activity leen cada clave que puedes ver, o hasta 50 que nombre --key-ids, incluidas las claves eliminadas.
• —--since y --until acotan un periodo y aceptan una hora ISO 8601 como 2026-09-01T00:00:00Z. --failed-only deja las llamadas respondidas con un estado 400 o superior.

openemail me get es el primer comando que hay que ejecutar cuando se rechaza una llamada. No necesita scope, así que cualquier clave o inicio de sesión válidos pueden describirse a sí mismos.

• —scopes es lo que la credencial puede hacer ahora mismo: los scopes con los que se creó, recortados por el rol con el que se emitió, calculados en cada solicitud. grantedScopes es con lo que se creó, y roleId nombra el rol. Un scope que está en grantedScopes y falta en scopes lo quitó el rol. Esa es la razón habitual de un 403 insufficient_scope en una clave que parece tener el scope, y la solución es cambiar el rol en lugar de crear otra clave.
• —domainAllowlist y addressAllowlist dicen desde qué direcciones puede enviar. Ambos a null significa cualquier dirección que tenga el espacio de trabajo.
• —Con un inicio de sesión con el navegador describe el inicio de sesión: object es oauth_token, clientId nombra la app conectada de esta CLI, y expiresAt es cuándo termina tu aprobación, o null cuando no termina nunca.
• —me ping responde ok: true con el mismo detalle de scopes pero sin las listas de permitidos, lo que va bien para una comprobación de estado. Una clave revocada, caducada, desactivada o mal escrita falla con un 401 y el código de salida 3.
• —me rotate da a la clave con la que llamas un secreto nuevo. Necesita keys:write, que un inicio de sesión con el navegador nunca tiene, así que requiere una clave de API. Todo lo demás de la clave se queda, el secreto anterior deja de funcionar al momento, y un perfil guardado recibe el nuevo, como con keys rotate. Una respuesta perdida puede dejar la clave con un secreto que nadie vio, y entonces necesita uno nuevo desde la app web.
• —openemail whoami muestra la misma respuesta con formato para personas.

openemail languages list muestra la tabla de idiomas entera en una sola respuesta, unas doscientas filas, con el código de cada idioma, su nombre en inglés, su nombre propio, su bandera y si se escribe de derecha a izquierda. El código, el nombre en inglés o el nombre propio funcionan como destino de un envío traducido. Necesita un inicio de sesión pero ningún scope. openemail ai languages muestra la misma tabla con una opción --search, y sin sesión iniciada muestra la tabla incluida en la CLI.

Un miembro tiene dos cosas que nunca se mezclan. Su rol dice lo que puede hacer, y sus concesiones de direcciones y dominios dicen con qué correo puede hacerlo, cada concesión con su propio acceso: member lee y envía, y viewer solo lee. Un envío necesita las dos cosas, así que un rol con emails:send y una concesión viewer sobre una dirección sigue sin poder enviar desde ella. Un dominio entero cubre todas sus direcciones, incluidas las que se creen después.

• —members list pone primero al propietario del espacio de trabajo, marcado con isOwner, así que deja fuera esa fila al contar plazas. El propietario tiene todos los permisos y no se le puede invitar, cambiar ni quitar, y tampoco se puede volver a invitar a nadie que ya esté en el espacio de trabajo: ambos casos dan 422 member_is_owner.
• —Las personas que tienen concesiones de direcciones pero a las que nunca se les dio un rol vuelven con implied: true, y su rol se deduce de sus concesiones. members update les da uno real.
• —members add envía una invitación, incluso a alguien que ya tiene cuenta. No se concede nada hasta que acepta, y entonces exactamente el rol, las direcciones y los dominios que lleva. Volver a invitar a la misma dirección en diez minutos da 409 invitation_too_soon, y después de eso actualiza la invitación pendiente en lugar de enviar una segunda.
• —resend-invitation envía un enlace nuevo válido durante 14 días más y retira el anterior, lo que también renueva una invitación caducada. revoke-invitation retira una, y una invitación que ya se aceptó da 409 invitation_accepted, así que quita al miembro en su lugar.
• —members update cambia el rol y nada más. grant-address da una dirección o cambia el acceso a ella, así que volver a ejecutarlo con otro --access cambia la concesión en lugar de añadir una segunda. revoke-address retira una dirección y deja las demás. Revocar la última concesión de un miembro deducido lo quita del espacio de trabajo.
• —members remove termina el acceso de alguien al espacio de trabajo, su pertenencia y cada concesión, e informa en addressesRevoked de cuántas concesiones de direcciones se retiraron. Su cuenta y el correo que envió no se tocan.

Un rol es también un techo para las claves de API emitidas con él. Lo que puede hacer una clave son sus propios scopes recortados por los permisos de su rol, calculados en cada solicitud.

• —roles list muestra primero los roles predefinidos, en el orden Owner, Admin, Member, Viewer, Developer y Billing, y después los roles personalizados por nombre. Un espacio de trabajo tiene hasta 24 roles personalizados, y a partir de ahí roles create da 422 role_limit_reached.
• —Un rol guarda los permisos que implican sus permisos, así que templates:write guarda también templates:read, y roles:write trae roles:read y members:read. Lee la lista en la respuesta en lugar de suponerla.
• —roles update --permissions sustituye la lista entera, así que lee el rol, cambia la lista y envíala entera. --description null borra la nota. Un cambio se aplica en la siguiente llamada de cada miembro y clave que tenga el rol.
• —Todos los roles salvo Owner se pueden renombrar, reescribir y eliminar, incluidos los predefinidos, y un rol predefinido eliminado no vuelve. El rol de propietario responde a una edición con 409 role_immutable y a una eliminación con 409 role_undeletable.
• —Mientras algún miembro, clave de API o invitación pendiente tenga un rol, roles delete necesita --reassign-to con el rol que los recibe, o se rechaza con 409 role_in_use. Las claves revocadas siguen apuntando a su rol, así que un rol cuyo recuento de apiKeys es 0 todavía puede necesitarlo. La respuesta informa de las personas reassigned y de las claves keysReassigned.
• —roles list-permissions lista el vocabulario entero con una etiqueta y un grupo para cada uno. Unos pocos, como billing:write y workspace:manage, vuelven con scope: false: un rol puede tenerlos, pero ninguna clave.

Una bandeja desechable no necesita cuenta ni inicio de sesión. Se accede a ella con su propio token de bandeja, que empieza por oe_inbox_ y vuelve una sola vez, cuando se crea la bandeja. Usa openemail temp en el día a día, y openemail temp-mail cuando necesites un campo o un paso que temp no muestra, como las prórrogas que quedan, una prórroga o los bytes de un adjunto.

• —Ambos guardan el token en ~/.openemail/temp-mail.json, que solo tú puedes leer. temp new y temp-mail create lo guardan, temp list muestra las bandejas creadas de cualquiera de las dos formas, y ambas eliminaciones lo olvidan. Una bandeja guardada se puede nombrar por su dirección siempre que un comando pida su id.
• —Para una bandeja que no creó esta CLI, pasa el token con --inbox-token. Sin token guardado ni pasado, el comando se detiene con el código de salida 3 antes de enviar nada.
• —Los dos comandos de creación nombran sus opciones de forma distinta: temp new acepta --name, --domain y --ttl, y temp-mail create acepta --local-part, --domain y --ttl-minutes. Una parte local tiene de 3 a 32 letras, dígitos, puntos, guiones o guiones bajos, empieza y termina con una letra o un dígito, y nombres como postmaster se rechazan. La cesión dura de 1 a 1440 minutos, 60 por defecto.
• —Cada dirección IP puede crear 6 bandejas por hora y 30 al día, y la siguiente da 429 too_many_inboxes, código de salida 8. Prorrogar una bandeja que ya tienes no cuenta, así que temp-mail extend es la respuesta a ese límite.
• —temp-mail extend añade hasta una hora, nunca más allá de 24 horas después de crear la bandeja, y como mucho 23 veces. Lee extensionsLeft en la respuesta. En 0, da 409 extension_limit para siempre.
• —temp-mail list-messages lee de 1 a 50 mensajes por página, 50 por defecto, cada uno con un snippet en texto plano de hasta 400 caracteres que a menudo contiene un código de un solo uso. No se pierde nada más allá de una página, y --all recorre todas las páginas.
• —Leer un mensaje con temp read, temp-mail get-message o temp-mail list-attachments lo marca como visto. Un cuerpo de más de 2 MB se recorta, como indica truncated, y un adjunto de más de 8 MB nunca se guardó, así que su content es null.
• —Eliminar una bandeja elimina su correo al momento, pero la dirección queda reservada hasta 7 días después de cuando habría terminado su cesión, y volver a pedirla antes da 409 address_taken.

openemail api <method> <path> envía una solicitud por el mismo transporte que cualquier otro comando, así que se aplican tu perfil o tu clave, la renovación del token, los códigos de verificación y las confirmaciones. Una ruta sola es un GET, y una respuesta JSON se muestra con formato. openemail api /keys/self es la llamada que hay detrás de me get.

• —-d, --data toma el cuerpo como JSON en línea, desde un archivo con @path o desde stdin con -. -q, --query y -H, --header toman key=value y se pueden repetir, y -o, --out guarda la respuesta tal cual en un archivo.
• —Un DELETE, y cualquier llamada que un comando de recurso confirmaría, como revocar o rotar una clave, pide primero que confirmes, y sin supervisión necesita --yes.
• —Una solicitud fallida muestra el error de la API y sale con el código correspondiente.

El espacio de nombres security no aparece en openemail --help, porque lo maneja openemail verify. Sus verbos step-up-status, begin-step-up y verify-step-up son las llamadas que hace verify: verify --status lee el estado, y verify pide un código, te lo solicita y lo comprueba. Existen para un inicio de sesión con el navegador. Con una clave de API cada uno se rechaza con 400 step_up_not_applicable, y openemail verify dice que una clave nunca necesita código.

openemail keys create --name 'Billing sender' --scopes emails:send \  --domain-allowlist billing.acme.com --expires-in-minutes 129600 --json \  | jq -r .token | openemail login --with-token --profile billingopenemail whoami --profile billing

Ejecútalo con una clave de API que tenga keys:manage, por ejemplo mediante OPENEMAIL_API_KEY. El secreto pasa de la respuesta directamente a un perfil nuevo, así que nunca aparece en pantalla ni en un archivo. La clave solo puede enviar desde billing.acme.com, y caduca en 90 días.

openemail keys list --all | jq -r 'select(.status != "active") | [.name, .status, .lastUsedAt] | @tsv'openemail keys list-workspace-requests --failed-only --since 2026-09-26T00:00:00Z --all \  | jq -r '[.createdAt, .keyName, .status, .errorCode, .method, .path] | @tsv'

id=4c1b257a66287fd113bd89d0openemail keys update "$id" --no-enabledopenemail keys list-activity "$id" --since 2026-09-27T00:00:00Z --all | jq -r 'select(.type == "auth_failed") | .createdAt'openemail keys revoke "$id" --reason 'Contractor offboarded' --yesopenemail keys delete "$id" --yes

Desactivar primero la clave se puede deshacer con --enabled. Cada llamada que aún la presente se rechaza y aparece en su actividad como auth_failed, lo que te dice qué sigue dependiendo de ella. Revocar no se puede deshacer, y solo se puede eliminar una clave revocada.

openemail roles list-permissions --json | jq -r '.[] | [.group, .id, .label] | @tsv'role=$(openemail roles create --name Support --permissions threads:write,emails:send,templates:read \  --description 'Answers help@ and nothing else.' --json | jq -r .id)openemail members add --email [email protected] --role-id "$role" \  --domain-ids 93542ff8-2baa-4f2f-841d-5ceaa074ab0d --access memberopenemail members list-invitations

El rol vuelve con threads:read y emails:read también, porque los permisos que nombra los implican. Sam recibe el rol y el dominio entero solo cuando acepta. Con un inicio de sesión con el navegador, members add pide primero un código de verificación.

old=role_8b1f4c2e9a7d3b60e5f1a2c4new=role_2c7e9a1f4b8d3e60c5a7f1b9user=$(openemail members list --all | jq -r 'select(.email == "[email protected]") | .userId')openemail members update "$user" --role-id "$new"openemail roles get "$old" --json | jq '{name, members, apiKeys}'openemail roles delete "$old" --reassign-to "$new" --dry-runopenemail roles delete "$old" --reassign-to "$new" --yes

members y apiKeys se cuentan cuando los pides, así que muestran lo que moverá la eliminación. La simulación muestra el DELETE con reassignTo en su consulta sin enviarlo. Con un inicio de sesión con el navegador, la actualización y la eliminación piden cada una un código de verificación, así que ejecuta primero openemail verify cuando lo haga un script.

address=$(openemail temp new --ttl 15)openemail send --from [email protected] --to "$address" --subject 'Delivery check' --text 'Your code is 482913' --yesopenemail temp watch "$address" --first --json | jq -r .snippet | grep -oE '[0-9]{6}'openemail temp delete "$address" --yes

temp new muestra solo la dirección, así que cabe en una variable de shell, y temp watch --first se detiene en el primer mensaje. Apunta un formulario de registro a la dirección en lugar de openemail send para atrapar su código de confirmación de la misma forma.

• —Un inicio de sesión o una clave sin el scope se detiene con el código de salida 4, nombra el scope que falta y explica cómo obtenerlo.
• —Estos piden que confirmes: keys delete, rotate y revoke, me rotate, roles delete, members remove, revoke-address y revoke-invitation, temp delete, y temp-mail delete y delete-message. Responder que no sale con el código 10 y no cambia nada. Sin supervisión y sin --yes, se detienen con el código de salida 2 antes de enviar nada.
• —Con un inicio de sesión con el navegador, roles update y roles delete, y members add, update, remove, grant-address y revoke-address, también piden un código de verificación, salvo que este inicio de sesión haya verificado uno en los últimos 60 minutos. --yes nunca se lo salta, y sin supervisión nadie puede escribirlo, así que el comando se detiene con el código de salida 4. Ejecuta primero openemail verify. A una clave de API nunca se le pide.
• —--dry-run muestra la solicitud que enviaría un cambio, con su cuerpo, y sale con el código 0 sin enviarla ni pedirte que confirmes.
• —Una lista lee una página. --limit acepta de 1 a 100 y el servidor envía 25 cuando se omite, salvo en temp-mail list-messages, que acepta de 1 a 50 y envía 50. --cursor acepta el nextCursor de la página anterior. --all lee todas las páginas, --max <n> se detiene tras esa cantidad de elementos, y --ndjson, o --all en un pipe, muestra un objeto JSON por línea. Con --json, una lista muestra un único documento { items, hasMore, nextCursor }.
• —roles list-permissions, languages list, temp-mail list-domains y temp-mail list-attachments lo devuelven todo de una vez, como un array simple, sin páginas.
• —Un rechazo sale con el código de su estado: 3 para un 401, como una clave revocada, 4 para un 403, como beyond_caller_authority u owner_only, 5 para un 404, 6 para un 409, como not_revoked, role_in_use o invitation_too_soon, 7 para un 400 o un 422, como member_is_owner o role_limit_reached, y 8 para un 429, como too_many_inboxes.
• —Un cambio que haría algo dos veces nunca se reintenta tras un fallo de red: keys create y rotate, me rotate, roles create y delete, members add, remove, revoke-address y resend-invitation, y temp-mail create, extend, delete y delete-message. Comprueba antes de volver a ejecutar uno. Las lecturas, y los cambios que tienen el mismo efecto dos veces, como keys update, keys revoke, roles update, members update y grant-address, se reintentan solos.