파일, 가져오기, 설정

다섯 네임스페이스가 메일 자체를 둘러싼 것들을 다룹니다. openemail files는 파일 페이지에 해당합니다. 주고받은 모든 첨부 파일과 업로드한 모든 파일을 바이트와, 그 파일이 나갈 때 쓰인 다운로드 링크와 함께 다룹니다. openemail imports는 옛 메일함을 주소 하나로 가져오고, openemail provider-imports는 Resend 계정을 옮겨 옵니다. openemail calendar는 메일에서 찾은 일정을 읽고, openemail settings는 메일함 환경설정과 각 주소의 서명과 추적을 읽고 바꿉니다.

• —ID는 무엇을 가리키는지 알려 줍니다. 파일은 file_, 메일함 가져오기는 imp_, Resend 가져오기는 pimp_, 캘린더 일정은 cal_이며, 각각 뒤에 16진수 문자 24개가 붙습니다. 다운로드 링크에는 files list-links나 files create-link에서 얻는 자체 ID가 있습니다.
• —가져오기의 --address-id는 주소 자체가 아니라 openemail domains list-addresses <id>에서 얻는 주소의 ID입니다.
• —네임스페이스는 file, import, provider-import 또는 providerImports, setting으로도 응답합니다. 동사는 별칭이 있는 경우 흔한 별칭을 받습니다. list에는 ls, get에는 show와 view, create에는 new와 add, settings update에는 edit, files delete에는 rm, del, remove입니다.
• —이 명령들은 어느 것도 브라우저 로그인에 인증 코드를 요구하지 않습니다. 영구히 무언가를 바꾸는 명령은 확인을 요청하며, 스크립트에서는 --yes가 답합니다.
• —openemail <command> --help는 모든 인수와 플래그를 타입, 호출에 필요한 범위, 메서드와 경로, 반환값과 함께 나열합니다. --json을 붙이면 같은 페이지를 데이터로 받습니다.

openemail files는 메일함이 가진 모든 파일을 읽고 관리합니다. 들어온 첨부 파일, 나간 첨부 파일, 파일 페이지에 업로드한 파일입니다. openemail open files는 웹 앱에서 같은 페이지를 엽니다.

• —files list는 --q(이름과 형식), --kind(image, pdf, audio, video, text), --direction(inbound, outbound, uploaded), --address, --since, --until로 좁히고, --sort(newest, oldest, largest, name)로 정렬합니다. --since와 --until은 ISO 8601 날짜나 날짜와 시각을 받습니다. --since는 그 순간을 포함하고 --until은 그 직전에 멈춥니다.
• —아무것도 의존하지 않는 업로드만 삭제할 수 있으며, deletable이 이를 미리 알려 줍니다. usage는 다른 파일이 남는 이유를 알려 줍니다. received, sent, 다운로드 링크가 아직 작동하는 업로드의 linked, 아직 나가지 않은 메시지에 첨부된 파일의 scheduled입니다. delete는 이런 파일을 409 file_in_use로 거부합니다. delete-many는 삭제할 수 있는 것은 삭제하고, 나머지는 각각 이유와 함께 kept에, 알 수 없는 ID는 missing에 나열합니다.
• —upload는 지정한 경로의 파일을 읽어 그 파일 이름으로, 확장자가 뜻하는 형식으로 저장합니다. --filename과 --content-type으로 이를 덮어씁니다. stdin에서 받는 -에는 --filename이 필요하며, --content-type이 없으면 형식은 application/octet-stream입니다. 업로드는 최대 10분 기다리며, --timeout-ms로 바꿉니다.
• —upload가 반환하는 ID는 openemail emails send --attachments에서 { "fileId": "…" }로 파일을 보내기에 첨부하며, 5 MB 인라인 한도를 넘는 파일은 이렇게 나갑니다.
• —빈 파일은 400 upload_empty, 이름으로 판단한 프로그램이나 스크립트는 400 upload_dangerous, 100 MB를 넘는 파일은 413 upload_too_large입니다. 워크스페이스는 업로드를 최대 10 GB까지 보관하며, 한 시간에 500개까지 업로드를 받습니다.
• —download는 터미널에서 --out <file>이 필요하며, 없으면 종료 코드 2로 멈춥니다. 파이프로 보내면 바이트는 stdout으로 가고, --out -도 stdout을 요청합니다. 파일 전체를 메모리에 올립니다.
• —create-link는 호출할 때마다 자체 다운로드 수를 가진 새 링크를 만들며, 링크는 폐기되거나 파일이 삭제될 때까지 작동합니다. 링크는 --domain의 도메인에 files.acme.com 같은 파일 도메인이 있으면 그곳에, 없으면 파일 주소의 파일 도메인에, 그것도 없으면 API 주소에 놓입니다. 프로그램이나 스크립트는 422 file_unshareable로 거부됩니다.
• —revoke-link는 반복해도 안전합니다. 이미 폐기된 링크는 그대로 돌아옵니다.
• —특정 주소나 도메인으로 제한된 키나 로그인은 그곳에 도착한 파일만 보며, 워크스페이스 전체를 위해 업로드된 파일은 보지 못하고, 자신이 업로드한 파일은 자신이 가진 첫 주소에 속합니다.
• —파일 색인은 출시된 날부터 시작합니다. 더 오래된 첨부 파일은 여전히 메시지에 있으며, openemail threads list-attachments <id>로 읽습니다.

openemail imports는 옛 메일함을 주소 하나로 가져옵니다. Google Takeout 아카이브, Apple Mail, Thunderbird와 대부분의 데스크톱 앱에서 나온 .mbox 파일, .eml 파일, 그리고 이들을 담은 .zip이나 .tgz 아카이브이며, 파일당 최대 100 GB, 가져오기당 파일 50개까지입니다. 스레드, 날짜, 라벨이 함께 옵니다. 가져온 메일은 조용합니다. 규칙, 전달, 알림, 요약, 웹훅을 실행하지 않습니다.

대부분의 사람에게 필요한 것은 import-files입니다. 가져오기를 만들고, 진행 줄을 보여 주며 모든 파일을 부분으로 나눠 업로드한 뒤 시작합니다. 다른 동사들은 그 단계를 하나씩 하는 것으로, 멈춘 업로드를 마무리하거나 직접 진행할 때 씁니다. create는 계획, chunkBytes, 각 파일의 chunks를 반환하고, upload-chunk는 부분 하나를 보내며, upload-state는 어느 부분이 도착했는지 알려 주고, start는 가져오기를 대기열에 넣습니다. openemail open imports는 웹 앱에서 같은 가져오기를 보여 줍니다.

• —주소는 워크스페이스 자체 도메인에 있으면서 키나 로그인이 대신 행동할 수 있는 주소여야 합니다. 주소마다 가져오기는 하나만 실행됩니다. 하나가 대기 중이거나 실행 중일 때 또 하면 409 already_running입니다.
• —import-files는 파일마다 --files를 한 번씩, 또는 쉼표로 구분한 여러 경로를 받으며, 각 파일을 자기 파일 이름으로 보냅니다. --options는 {"keepInbox":false,"includeSpam":true} 같은 JSON을 받습니다. create에서는 같은 세 가지가 스위치입니다. --options-keep-inbox, --options-include-spam, --options-include-trash이며, --no-options-keep-inbox처럼 앞에 --no-를 붙이면 꺼집니다.
• —keepInbox는 기본으로 켜져 있어서 옛 받은편지함의 메일은 읽지 않음 상태와 함께 받은편지함에 들어옵니다. 끄면 모든 것이 보관함에 정리됩니다. 스팸과 휴지통은 포함하지 않으면 남겨집니다.
• —create는 --files를 JSON으로, 인라인이나 @path로 파일에서 받으며, 각 bytes는 이후 업로드할 파일의 정확한 크기여야 합니다.
• —각 부분은 파일의 마지막 부분을 제외하면 정확히 chunkBytes 길이이며, 길이가 틀린 부분은 400 bad_chunk입니다. start는 부분이 빠진 파일을 412 missing_chunks로, 아카이브나 메일함이 아닌 파일을 400 unsupported_file로 거부합니다. 이미 uploading을 벗어난 가져오기에서는 가져오기를 그대로 반환합니다.
• —재시도 후에도 부분이 계속 실패하면 import-files는 가져오기를 uploading 상태로 둔 채 멈춥니다. 아래 블록은 첫 파일의 빠진 부분을 보내고 가져오기를 시작합니다.
• —가져오기는 totalBytes 중 processedBytes와, seen, imported, duplicate, filtered, failed, threads가 있는 counts를 보고합니다. lastError는 status가 failed일 때만 설정됩니다.
• —list-failures는 각 실패에 reason을 줍니다. too-large(50 MB 초과), unparseable, no-date, storage-error, unreadable-entry, encrypted-entry, archive-limit이며, 읽을 수 있었다면 제목과 보낸 사람도 함께 나옵니다.
• —끝난 가져오기에 cancel을 하면 409 not_cancellable입니다. delete-upload는 아직 업로드 중인 가져오기를 취소하고, 대기 중이거나 실행 중인 가져오기는 409 still_running으로 거부하므로, 그런 경우 먼저 취소하세요.

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는 전체 권한을 가진 Resend API 키 하나로 워크스페이스를 Resend에서 옮겨 옵니다. 발송 차단 항목은 사유를 유지하고, 세그먼트는 오디언스가 되며, 구독 중인 연락처는 이름과 함께 들어오고, 템플릿은 변수가 선언된 HTML 템플릿으로 들어옵니다. 웹훅은 여기서는 전달 서명 방식이 다르기 때문에 꺼진 상태로 등록됩니다. 서명 키나 토큰은 Resend 밖으로 나올 수 없으므로, 도메인과 API 키는 대신 보고서의 체크리스트로 돌아옵니다.

• —Resend 키를 @path로 넘기면 파일에서, -로 넘기면 stdin에서 읽으므로 셸 기록과 프로세스 목록에 남지 않습니다. 명령줄에 직접 입력한 키도 경고와 함께 동작합니다. --dry-run은 키를 가린 채 본문을 출력합니다.
• —--resources는 suppressions, audiences, contacts, templates, webhooks, domains, api-keys 중 어느 것이든 쉼표로 구분하거나 반복해서 받습니다.
• —발송 전용 키는 400 restricted_key입니다. 가져오기용으로 Resend에서 전체 권한 키를 만들고, 끝난 뒤 폐기하세요.
• —inspect는 각 리소스의 첫 페이지를 읽어 counts를 반환합니다. 리소스마다 { count, more } 하나이며, 리소스가 첫 페이지를 넘으면 more가 설정됩니다.
• —워크스페이스마다 한 번에 가져오기 하나만 실행되며, 두 번째는 409 already_running입니다. 같은 가져오기를 두 번 실행해도 아무것도 중복되지 않습니다. 키는 가져오기가 실행되는 동안에만 암호화되어 보관되고, 끝나거나 실패하거나 취소되면 지워집니다.
• —Resend에서 구독을 해지한 연락처는 빠지며, report.contacts.unsubscribed에 집계됩니다.
• —report.domains는 각 Resend 도메인을 state와 함께 나열합니다. 이 워크스페이스에 없으면 absent, 있지만 확인되지 않았으면 added, 그리고 verified이며, Resend에서 쓰던 레코드도 함께 나옵니다. 빠진 도메인은 openemail domains create로 추가하세요. report.apiKeys는 openemail keys create로 다시 만들 키를 알려 줍니다.
• —브라우저 로그인에서는 워크스페이스 소유자만 이 명령들을 쓸 수 있으며, 멤버는 403 owner_only를 받습니다. API 키에는 이 제한이 없습니다. 특정 주소나 도메인으로 제한된 키나 로그인은 가져오기를 살펴보거나 만들 수 없습니다. 오디언스, 발송 차단, 템플릿은 워크스페이스 전체에 속하기 때문입니다.
• —create에는 가져오는 각 리소스의 범위도 필요합니다. 오디언스에는 audiences:write, 연락처에는 contacts:write와 audiences:write, 템플릿에는 templates:write, 웹훅에는 webhooks:write, 도메인에는 domains:read입니다.

openemail calendar는 메일에서 찾은 캘린더 일정을 읽습니다. 세 명령 모두 읽기만 합니다. list-events는 지정한 기간 안에서 모든 일정을 발생 건으로 펼치므로 매주 회의는 주마다 한 행이 되며, get-event와 get-event-ics는 일정 하나를 통째로 읽습니다. openemail open calendar는 웹 앱에서 캘린더를 엽니다.

• —--from과 --to는 2026-10-01T00:00:00Z 같은 ISO 8601 날짜와 시각입니다. 반복 일정에는 나열을 끝낼 지점이 없으므로 --to는 --from보다 뒤여야 하며 최대 366일 뒤까지입니다. 경계가 빠지면 422 invalid_parameter입니다. 해석할 수 없는 경계, 뒤집히거나 너무 긴 기간, 알 수 없는 시간대는 400 invalid_parameter입니다.
• —--timezone은 Europe/London 같은 IANA 시간대이며, 빼면 UTC입니다. 자체 시간대 없이 저장된 일정을 펼칠 때 쓰이며, 종일 일정이 어느 날에 놓일지를 정합니다.
• —get-event와 get-event-ics는 iCalendar uid가 아니라 발생 건의 eventId를 받습니다. 반복 시리즈는 일정 하나이므로 start와 end는 첫 인스턴스를 나타냅니다.
• —취소된 일정도 status가 CANCELLED인 채로 나열됩니다. myPartstat은 워크스페이스가 자체 도메인에 가진 주소에 대해 기록된 응답이며, 그중 어느 것도 참석자가 아니면 null입니다.
• —페이지는 --cursor와 같은 기간으로 이어 갑니다. 특정 주소로 제한된 키나 로그인은 그 주소 중 하나가 주최하거나 참석하는 일정만 보며, 다른 일정은 404입니다.
• —get-event-ics는 METHOD:PUBLISH를 선언하므로, 가져오면 수락이나 거절을 제안하는 대신 일정을 있는 그대로 보여 줍니다. 시각이 있는 일정은 UTC 시각으로, 종일 일정은 날짜로 씁니다. DTSTAMP는 내려받은 시각이므로, 바뀌지 않은 일정을 두 번 내려받으면 그 줄만 다릅니다.

openemail settings는 시간대, 언어, 시간 형식, 차단 목록 같은 메일함 환경설정을 읽고 바꿉니다. 설정 네 가지는 워크스페이스가 아니라 주소에 속합니다. signature, openEmailSignature(OpenEmail 푸터), trackOpens, trackClicks입니다. 주소는 --address로 지정하며, 도메인의 catch-all은 *@acme.com입니다.

• —--address가 없으면 get은 주소별 설정 네 가지를 기본 제공값으로 읽습니다. 서명 없음, OpenEmail 푸터 켜짐, 열람과 링크 추적 켜짐입니다. --address를 주면 먼저 그 주소 자체의 값에서, 그다음 catch-all이 그 주소를 받아들였다면 도메인의 catch-all에서, 그다음 기본값에서 가져옵니다. 자체 설정이 없는 플러스 주소는 기본 주소의 설정을 읽습니다.
• —--address가 없으면 update는 --signature, --open-email-signature, --track-opens, --track-clicks를 422 address_required로 거부하고 아무것도 쓰지 않습니다. --address를 주면 update는 그 네 가지만 받으며, 그 밖의 것은 422 not_per_address입니다. 주소는 이 워크스페이스에 있어야 하며, 또는 catch-all이 켜진 여기의 확인된 도메인에 대한 *@domain이어야 합니다.
• —스위치는 앞에 --no-를 붙이면 꺼집니다. --no-open-email-signature, --no-track-opens, --no-track-clicks입니다.
• —--signature는 최대 150,000자의 HTML이며 쓸 때 정리되므로, 돌아오는 것이 보내질 내용입니다. 빈 문자열은 서명을 없앱니다. 보내기가 서명을 붙일지는 보내기가 정합니다. openemail emails send --help의 --signature를 보세요.
• —플래그는 흔한 필드를 다룹니다. --data는 저장된 어떤 설정이든 JSON으로 받습니다. 인라인, @path로 파일에서, -로 stdin에서 줄 수 있으며, 예를 들면 timeFormat, weekStart, undoSendEnabled, blockedSenders, blockedDomains입니다. 설정이 모르는 키는 오류 없이 버려지며, 아는 키에 타입이 틀리면 422 invalid_parameter입니다.
• —blockedDomains 같은 목록은 통째로 교체되므로, 아래 예제처럼 먼저 읽고 변경을 더해 다시 보내세요. 규칙이 되기에는 너무 짧은 차단 목록 항목은 422 blocklist_entry_too_broad입니다.
• —--timezone과 --language는 확인 없이 받은 그대로 저장되므로, 보내기 전에 시간대나 언어 코드를 확인하세요.
• —개인정보 필드인 externalImages, trustedSenders, blockedSenders, blockedDomains, blockedWords, useDefaultBlockedWords는 워크스페이스에 속합니다. 특정 주소나 도메인으로 제한된 키나 로그인은 이를 바꿀 수 없으며, --address에는 자신이 가진 주소나 자신이 통째로 가진 도메인의 catch-all만 지정할 수 있습니다. 어느 거부든 422 capability_unsupported입니다.
• —아무것도 없는 업데이트는 아무것도 바꾸지 않고 현재 설정을 반환합니다. defaultEmailAlias는 웹 앱 작성기에서 From 주소를 미리 선택할 뿐이며, API는 보내는 사람을 고르는 데 절대 쓰지 않습니다.

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

create-link는 호출할 때마다 새 링크를 만드므로, 한 번만 실행하고 list-links로 링크를 다시 읽으세요. revoke-link는 나중에 이미 나간 메일에서도 링크를 멈춥니다.

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[]'

파이프에서 --all을 주면 files list는 한 줄에 파일 하나를 출력합니다. xargs -n 100은 delete-many에 호출마다 최대 100개의 ID를 넘기며, 그 사이에 쓰이게 된 파일은 호출을 실패시키지 않고 이유와 함께 kept로 돌아옵니다.

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'

import-files에서 --dry-run은 보낼 POST /imports를 각 파일의 이름과 크기와 함께 출력하고, 아무것도 업로드하지 않습니다. list-failures는 한 번에 100개씩 읽습니다. 다음 페이지를 보려면 출력된 nextCursor를 --after로 넘기세요.

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 -

드라이 런은 PATCH /settings?address=sales%40acme.com과 그 본문을 보내지 않고 출력합니다. catch-all 줄은 acme.com의 catch-all이 받아들이는 모든 주소의 추적을 설정하고, 마지막 줄은 다른 도메인을 지우지 않고 차단 목록에 도메인 하나를 더합니다.

• —범위가 없는 로그인이나 키는 종료 코드 4로 멈추고, 빠진 범위와 그것을 얻는 방법을 알려 줍니다.
• —files revoke-link, files delete, files delete-many, imports cancel, imports delete-upload, provider-imports cancel은 확인을 요청합니다. 아니라고 답하면 종료 코드 10으로 끝나고 아무것도 바뀌지 않습니다. 무인 실행에서 --yes가 없으면 아무것도 보내기 전에 종료 코드 2로 멈춥니다.
• —여기의 어떤 명령도 브라우저 로그인이든 API 키든 인증 코드를 요구하지 않으므로, 스크립트에는 --yes만 있으면 됩니다.
• —--dry-run은 변경이 보낼 요청을 본문과 함께 출력하고, 보내거나 확인을 묻지 않고 코드 0으로 종료합니다. 파일 본문은 크기와 형식으로 표시됩니다.
• —files list, files list-links, imports list, provider-imports list, calendar list-events는 한 페이지를 읽습니다. --limit는 1에서 100을 받으며 빼면 서버가 25개를 보내고, --cursor는 이전 페이지의 nextCursor를 받습니다. --all은 모든 페이지를 읽고, --max <n>은 그만큼 읽고 멈추며, --ndjson이나 파이프에서의 --all은 한 줄에 JSON 객체 하나를 출력합니다. --json을 주면 { items, hasMore, nextCursor } 문서 하나를 출력합니다.
• —imports list-failures는 자기 방식으로 페이지를 넘깁니다. --after는 이전 페이지의 nextCursor를 받고, --limit는 기본값인 100이 최대이며, --all은 없습니다. --json을 주면 { object, data, nextCursor }를 출력합니다.
• —읽기와, 두 번 해도 결과가 같은 변경은 네트워크 실패 후 재시도합니다. files revoke-link, imports upload-chunk, imports start, settings update입니다. 그 밖의 모든 변경은 한 번만 보냅니다. 응답을 잃은 뒤에는 다시 시도하기 전에 확인하세요. 두 번째 upload는 두 번째 사본을 저장하고 두 번째 create-link는 두 번째 링크를 만들며, 두 번째 files delete에서 404가 나면 첫 번째가 성공한 것이고, 두 번째 delete-many는 첫 번째가 삭제한 것을 missing에 나열합니다.
• —거부는 상태에 맞는 코드로 종료합니다. 403이면 4, 404면 5, 409면 6, 400이나 422면 7, 429면 8입니다.