Archivos, importaciones y configuración

Cinco espacios de nombres cubren lo que rodea al correo en sí. openemail files es la página Archivos: cada adjunto enviado y recibido y cada archivo subido, con sus bytes y los enlaces de descarga con los que salió. openemail imports trae un buzón antiguo a una dirección, y openemail provider-imports trae una cuenta de Resend. openemail calendar lee los eventos que se encuentran en el correo, y openemail settings lee y cambia las preferencias del buzón y la firma y el seguimiento de cada dirección.

• —Un id dice lo que nombra: file_ para un archivo, imp_ para una importación de buzón, pimp_ para una importación de Resend y cal_ para un evento de calendario, cada uno seguido de 24 caracteres hexadecimales. Un enlace de descarga tiene su propio id, de files list-links o files create-link.
• —--address-id en una importación es el id de una dirección, de openemail domains list-addresses <id>, no la dirección en sí.
• —Los espacios de nombres responden también a file, import, provider-import o providerImports, y setting. Los verbos aceptan los alias habituales cuando los tienen: ls para list, show y view para get, new y add para create, edit para settings update, y rm, del y remove para files delete.
• —Ninguno de estos comandos pide un código de verificación a un inicio de sesión con el navegador. Los que cambian algo para siempre piden que confirmes, y --yes responde por un script.
• —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.

openemail files lee y gestiona cada archivo que guarda el buzón: los adjuntos que llegaron, los adjuntos que salieron y los archivos subidos a la página Archivos. openemail open files abre la misma página en la app web.

• —files list filtra con --q (el nombre y el tipo), --kind (image, pdf, audio, video o text), --direction (inbound, outbound o uploaded), --address, --since y --until, y ordena con --sort (newest, oldest, largest o name). --since y --until aceptan una fecha o fecha y hora ISO 8601: --since incluye su momento y --until se detiene antes de él.
• —Solo se puede eliminar un archivo subido del que no depende nada, y deletable lo indica de antemano. usage dice qué retiene cualquier otro archivo: received, sent, linked para un archivo subido cuyo enlace de descarga sigue funcionando, o scheduled para uno adjunto a un mensaje que aún no ha salido. delete los rechaza con 409 file_in_use. delete-many elimina lo que puede, lista el resto en kept con un motivo para cada uno, y lista los ids desconocidos en missing.
• —upload lee el archivo de la ruta que das y lo guarda con el nombre de ese archivo, con el tipo que implica su extensión. --filename y --content-type los sustituyen. Desde stdin, - necesita --filename, y sin --content-type el tipo es application/octet-stream. La subida espera hasta 10 minutos, lo que cambia --timeout-ms.
• —El id que devuelve upload adjunta el archivo a un envío como { "fileId": "…" } en openemail emails send --attachments, que es como sale un archivo que supera el límite de 5 MB en línea.
• —Un archivo vacío da 400 upload_empty, un programa o script (juzgado por su nombre) da 400 upload_dangerous, y un archivo de más de 100 MB da 413 upload_too_large. Un espacio de trabajo guarda hasta 10 GB de archivos subidos y acepta 500 subidas por hora.
• —download necesita --out <file> en un terminal y sin él se detiene con el código de salida 2. Redirigido, los bytes van a stdout, y --out - también pide stdout. El archivo entero se mantiene en memoria.
• —create-link crea un enlace nuevo en cada llamada, con su propio recuento de descargas, y el enlace funciona hasta que se revoca o se elimina el archivo. Vive en el dominio de archivos de --domain cuando ese dominio tiene uno, como files.acme.com, si no en el dominio de archivos de la dirección del archivo, y si no en la dirección de la API. Un programa o script se rechaza con 422 file_unshareable.
• —revoke-link se puede repetir sin riesgo: un enlace ya revocado vuelve sin cambios.
• —Una clave o un inicio de sesión limitados a determinadas direcciones o dominios solo ven los archivos que les llegaron, nunca los archivos subidos para todo el espacio de trabajo, y sus propias subidas pertenecen a la primera dirección que tienen.
• —El índice de archivos empieza el día en que se publicó. Los adjuntos más antiguos siguen en sus mensajes, donde los lee openemail threads list-attachments <id>.

openemail imports trae un buzón antiguo a una dirección: archivos de Google Takeout, archivos .mbox de Apple Mail, Thunderbird y la mayoría de las apps de escritorio, archivos .eml, y archivos .zip o .tgz que contengan cualquiera de ellos, de hasta 100 GB por archivo y 50 archivos por importación. Los hilos, las fechas y las etiquetas se conservan. El correo importado es silencioso: no ejecuta reglas, reenvíos, notificaciones, resúmenes ni webhooks.

import-files es el que necesita casi todo el mundo: crea la importación, sube cada archivo por partes con una línea de progreso y la inicia. Los demás verbos son esos pasos uno a uno, para terminar una subida que se detuvo o para dirigirla tú mismo. create devuelve el plan, chunkBytes y los chunks de cada archivo, upload-chunk envía una parte, upload-state dice qué partes llegaron, y start pone la importación en cola. openemail open imports muestra las mismas importaciones en la app web.

• —La dirección tiene que ser una de los dominios propios del espacio de trabajo para la que pueda actuar la clave o el inicio de sesión. Solo se ejecuta una importación por dirección: otra mientras una está en cola o en curso da 409 already_running.
• —import-files acepta --files una vez por archivo, o varias rutas separadas por comas, y envía cada uno con su propio nombre de archivo. --options acepta JSON como {"keepInbox":false,"includeSpam":true}. En create esos mismos tres son interruptores: --options-keep-inbox, --options-include-spam y --options-include-trash, cada uno desactivado con --no- delante, como en --no-options-keep-inbox.
• —keepInbox está activado por defecto, así que el correo de la bandeja de entrada antigua llega a la Bandeja de entrada con su estado de no leído. Desactivado, lo archiva todo en Archivo. El spam y la papelera se quedan fuera salvo que los incluyas.
• —create acepta --files como JSON, en línea o desde un archivo con @path, y cada bytes debe ser el tamaño exacto del archivo que subas después.
• —Cada parte mide exactamente chunkBytes, salvo la última parte de un archivo, y una parte de longitud incorrecta da 400 bad_chunk. start rechaza un archivo al que le faltan partes con 412 missing_chunks, y uno que no es un archivo comprimido ni un buzón con 400 unsupported_file. En una importación que ya salió de uploading, devuelve la importación sin cambios.
• —Si una parte sigue fallando tras sus reintentos, import-files se detiene con la importación en uploading. El bloque de abajo envía las partes que faltan del primer archivo y la inicia.
• —Una importación informa de processedBytes sobre totalBytes, y de counts con seen, imported, duplicate, filtered, failed y threads. lastError solo se define cuando status es failed.
• —list-failures da a cada fallo un reason: too-large (más de 50 MB), unparseable, no-date, storage-error, unreadable-entry, encrypted-entry o archive-limit, con el asunto y el remitente cuando se pudieron leer.
• —cancel sobre una importación terminada da 409 not_cancellable. delete-upload cancela una importación que aún se está subiendo, y rechaza una que está en cola o en curso con 409 still_running, así que cancélala primero.

openemail imports get "$import_id" --json > import.jsonopenemail imports upload-state "$import_id" --json > state.jsonchunk=$(jq .chunkBytes import.json)chunks=$(jq '.files[0].chunks' import.json)for i in $(seq 0 $((chunks - 1))); do  jq -e --argjson i "$i" '.received[0] | any(. == $i)' state.json > /dev/null && continue  dd if=takeout-001.zip bs="$chunk" skip="$i" count=1 2> /dev/null |    openemail imports upload-chunk "$import_id" 0 "$i" -doneopenemail imports start "$import_id"

openemail provider-imports trae un espacio de trabajo desde Resend con una clave de API de Resend con acceso completo. Las supresiones conservan su motivo, los segmentos se convierten en audiencias, los contactos suscritos llegan con sus nombres, y las plantillas llegan como plantillas HTML con sus variables declaradas. Los webhooks se registran desactivados, porque aquí las entregas se firman de otra forma. Una clave de firma o un token no pueden salir de Resend, así que los dominios y las claves de API vuelven como una lista de comprobación en el informe.

• —Pasa la clave de Resend como @path para leerla de un archivo, o como - para leerla de stdin, así queda fuera del historial de tu shell y de la lista de procesos. Una clave escrita en la línea de comandos sigue funcionando, con un aviso. --dry-run muestra el cuerpo con la clave ocultada.
• —--resources acepta cualquiera de suppressions, audiences, contacts, templates, webhooks, domains y api-keys, separados por comas o repetidos.
• —Una clave solo de envío da 400 restricted_key. Crea en Resend una clave con acceso completo para la importación, y revócala después.
• —inspect lee la primera página de cada recurso y devuelve counts, un { count, more } por recurso, con more definido cuando un recurso va más allá de su primera página.
• —Se ejecuta una importación por espacio de trabajo a la vez, y una segunda da 409 already_running. Ejecutar la misma importación dos veces no duplica nada. La clave se guarda cifrada solo mientras se ejecuta la importación, y se borra cuando termina, falla o se cancela.
• —Los contactos que se dieron de baja en Resend se dejan fuera y se cuentan en report.contacts.unsubscribed.
• —report.domains lista cada dominio de Resend con un state: absent cuando no está en este espacio de trabajo, added cuando está pero no verificado, y verified, con los registros que tenía en Resend. Añade uno que falte con openemail domains create. report.apiKeys nombra las claves que hay que volver a crear con openemail keys create.
• —Con un inicio de sesión con el navegador solo el propietario del espacio de trabajo puede usar estos comandos, y un miembro recibe 403 owner_only. Una clave de API no está sujeta a eso. Una clave o un inicio de sesión limitados a determinadas direcciones o dominios no pueden inspeccionar ni crear una importación, ya que las audiencias, las supresiones y las plantillas pertenecen a todo el espacio de trabajo.
• —create también necesita el scope de cada recurso que importa: audiences:write para las audiencias, contacts:write y audiences:write para los contactos, templates:write para las plantillas, webhooks:write para los webhooks y domains:read para los dominios.

openemail calendar lee los eventos de calendario que se encuentran en el correo. Los tres comandos solo leen. list-events expande cada evento en sus repeticiones dentro de un periodo que indicas, así que una reunión semanal es una fila por semana, y get-event y get-event-ics leen un evento entero. openemail open calendar abre el calendario en la app web.

• —--from y --to son fechas y horas ISO 8601 como 2026-10-01T00:00:00Z. --to debe ser posterior a --from y como mucho 366 días después, ya que una serie que se repite no tiene un final hasta el que listar. Un límite que falta da 422 invalid_parameter. Un límite que no se puede interpretar, un periodo invertido o demasiado largo, o una zona desconocida da 400 invalid_parameter.
• —--timezone es una zona IANA como Europe/London, UTC si se omite. Expande los eventos guardados sin zona propia, lo que decide el día en el que cae un evento de todo el día.
• —get-event y get-event-ics aceptan el eventId de una repetición, no el uid de iCalendar. Una serie que se repite es un solo evento, así que su start y su end describen la primera instancia.
• —Los eventos cancelados también se listan, con status en CANCELLED. myPartstat es la respuesta registrada para cualquier dirección que el espacio de trabajo tiene en sus propios dominios, y null cuando ninguna de ellas es asistente.
• —La paginación sigue con --cursor y el mismo periodo. Una clave o un inicio de sesión limitados a determinadas direcciones solo ven los eventos que una de ellas organiza o a los que asiste, y cualquier otro evento da 404.
• —get-event-ics declara METHOD:PUBLISH, así que al importarlo se muestra el evento tal como está en lugar de ofrecer aceptarlo o rechazarlo. Los eventos con hora se escriben como instantes UTC y los de todo el día como fechas. DTSTAMP es la hora de la descarga, así que dos descargas de un evento sin cambios difieren en esa línea.

openemail settings lee y cambia las preferencias del buzón, como la zona horaria, el idioma, el formato de hora y las listas de bloqueo. Cuatro ajustes pertenecen a una dirección y no al espacio de trabajo: signature, openEmailSignature (el pie de OpenEmail), trackOpens y trackClicks. Nombra la dirección con --address, o *@acme.com para el catch-all de un dominio.

• —Sin --address, get lee los cuatro ajustes por dirección como los valores predeterminados integrados: sin firma, el pie de OpenEmail activado, y el seguimiento de aperturas y de enlaces activado. Con ella, salen de los valores propios de la dirección, después del catch-all de su dominio cuando el catch-all recogió esa dirección, y después de los valores predeterminados. Una dirección con signo más sin ajustes propios lee los de su dirección base.
• —Sin --address, update rechaza --signature, --open-email-signature, --track-opens y --track-clicks con 422 address_required y no escribe nada. Con ella, update acepta solo esos cuatro, y cualquier otra cosa da 422 not_per_address. La dirección tiene que estar en este espacio de trabajo, o ser *@domain para un dominio verificado aquí con su catch-all activado.
• —Los interruptores se desactivan con --no- delante: --no-open-email-signature, --no-track-opens y --no-track-clicks.
• —--signature es HTML de como mucho 150.000 caracteres, saneado al escribirse, así que lo que vuelve es lo que se enviará. Una cadena vacía la quita. Que un envío la añada depende del envío: consulta --signature en openemail emails send --help.
• —Las opciones cubren los campos habituales. --data acepta cualquier ajuste guardado como JSON, en línea, desde un archivo con @path o desde stdin con -, como timeFormat, weekStart, undoSendEnabled, blockedSenders o blockedDomains. Las claves que los ajustes no conocen se descartan sin error, y una clave conocida con el tipo incorrecto da 422 invalid_parameter.
• —Una lista como blockedDomains se sustituye entera, así que léela primero y devuélvela con tu cambio, como hace el ejemplo de abajo. Una entrada de la lista de bloqueo demasiado corta para ser una regla da 422 blocklist_entry_too_broad.
• —--timezone y --language se guardan tal cual, sin comprobarlos, así que comprueba una zona o un código de idioma antes de enviarlo.
• —Los campos de privacidad, externalImages, trustedSenders, blockedSenders, blockedDomains, blockedWords y useDefaultBlockedWords, pertenecen al espacio de trabajo. Una clave o un inicio de sesión limitados a determinadas direcciones o dominios no pueden cambiarlos, y en --address solo pueden nombrar una dirección que tengan, o un catch-all de un dominio que tengan entero. Cualquiera de los dos rechazos da 422 capability_unsupported.
• —Una actualización sin nada no cambia nada y devuelve los ajustes actuales. defaultEmailAlias solo preselecciona la dirección From en el editor de la app web, y la API nunca la usa para elegir un remitente.

file_id=$(openemail files upload ./price-list.pdf --json | jq -r .id)openemail files create-link "$file_id" --domain acme.com --json | jq -r .urlopenemail files list-links "$file_id"openemail files download "$file_id" --out copy.pdf

Cada create-link crea un enlace nuevo, así que ejecútalo una vez y vuelve a leer el enlace con list-links. revoke-link lo detiene más tarde, también en el correo que ya salió.

openemail files list --direction uploaded --all | jq -r 'select(.deletable) | .id' > deletable.txtwc -l < deletable.txtxargs -r -n 100 openemail files delete-many --yes --json < deletable.txt | jq -c '.kept[]'

Con --all en un pipe, files list muestra un archivo por línea. xargs -n 100 pasa a delete-many como mucho 100 ids por llamada, y cualquier archivo que haya pasado a usarse entretanto vuelve en kept con su motivo en lugar de hacer fallar la llamada.

domain_id=$(openemail domains list --all | jq -r 'select(.domain == "acme.com") | .id')address_id=$(openemail domains list-addresses "$domain_id" --all | jq -r 'select(.address == "[email protected]") | .id')openemail imports import-files --address-id "$address_id" --files ~/Downloads/takeout-001.zip --files ~/Downloads/takeout-002.zip --json > import.jsonimport_id=$(jq -r .id import.json)until openemail imports get "$import_id" --json | jq -e '.status != "queued" and .status != "running"' > /dev/null; do  sleep 60doneopenemail imports get "$import_id" --json | jq '{status, counts, lastError}'openemail imports list-failures "$import_id" --json | jq -r '.data[] | [.reason, .subject] | @tsv'

--dry-run en import-files muestra el POST /imports que enviaría, con el nombre y el tamaño de cada archivo, y no sube nada. list-failures lee 100 cada vez: pasa el nextCursor que mostró como --after para la página siguiente.

openemail provider-imports inspect @resend-key.txtopenemail provider-imports create --resend-key @resend-key.txt --resources suppressions,audiences,contacts,templates,webhooks,domains,api-keys --json > resend.jsonpimp_id=$(jq -r .id resend.json)until openemail provider-imports get "$pimp_id" --json | jq -e '.status != "queued" and .status != "running"' > /dev/null; do  sleep 10doneopenemail provider-imports get "$pimp_id" --json | jq '.report | {contacts, domains: [.domains[] | {name, state}], apiKeys: [.apiKeys[].name]}'

openemail calendar list-events --from 2026-10-01T00:00:00Z --to 2026-11-01T00:00:00Z --timezone Europe/London --all |  jq -r 'select(.status != "CANCELLED") | [.start, .summary, .myPartstat] | @tsv'openemail calendar get-event cal_8d3f0a2b9c4e41f7a6b5c2d1 --json | jq '.attendees[] | {email, partstat}'openemail calendar get-event-ics cal_8d3f0a2b9c4e41f7a6b5c2d1 --out standup.ics

openemail settings get --address [email protected] --json | jq '{signature, openEmailSignature, trackOpens, trackClicks}'openemail settings update --address [email protected] --signature "$(cat signature.html)" --no-track-clicks --dry-runopenemail settings update --address [email protected] --signature "$(cat signature.html)" --no-track-clicksopenemail settings update --address '*@acme.com' --no-track-opensopenemail settings update --timezone Europe/London --language enopenemail settings get --json | jq -c '{blockedDomains: ((.blockedDomains + ["spam.example"]) | unique)}' |  openemail settings update --data -

La simulación muestra el PATCH /settings?address=sales%40acme.com y su cuerpo sin enviarlo. La línea del catch-all define el seguimiento para cada dirección que recoge el catch-all de acme.com, y la última línea añade un dominio a la lista de bloqueo sin quitar los demás.

• —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.
• —files revoke-link, files delete, files delete-many, imports cancel, imports delete-upload y provider-imports cancel piden que confirmes. 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.
• —Ningún comando de esta página pide un código de verificación, ni con un inicio de sesión con el navegador ni con una clave de API, así que --yes es todo lo que necesita un script.
• —--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. El cuerpo de un archivo se muestra como su tamaño y su tipo.
• —files list, files list-links, imports list, provider-imports list y calendar list-events leen una página: --limit acepta de 1 a 100 y el servidor envía 25 cuando se omite, y --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 muestran un único documento { items, hasMore, nextCursor }.
• —imports list-failures pagina a su manera: --after acepta el nextCursor de la página anterior, --limit es como mucho 100, el valor por defecto, y no hay --all. Con --json muestra { object, data, nextCursor }.
• —Las lecturas y los cambios que tienen el mismo efecto dos veces se reintentan tras un fallo de red: files revoke-link, imports upload-chunk, imports start y settings update. Cualquier otro cambio se envía una vez. Tras perder una respuesta, mira antes de volver a intentarlo: un segundo upload guarda una segunda copia y un segundo create-link crea un segundo enlace, un 404 en tu segundo files delete significa que el primero funcionó, y un segundo delete-many lista en missing lo que eliminó el primero.
• —Un rechazo sale con el código de su estado: 4 para un 403, 5 para un 404, 6 para un 409, 7 para un 400 o un 422, y 8 para un 429.