스레드, 초안, 라벨

inbox, read, archive, label add 같은 메일 명령은 사람을 위해 작성되었습니다. 스레드 ID를 한 번에 여러 개 받고, 출력을 보기 좋게 만들며, 라벨 ID를 드러내지 않습니다. 이 명령들은 각각 이 페이지의 명령을 실행하는데, 이 페이지의 명령은 스레드, 초안, 라벨에 대한 SDK 메서드이며 메서드마다 명령이 하나씩 있습니다. 그래서 threads.listAttachments는 openemail threads list-attachments입니다.

메일 명령이 빠뜨린 것이 필요할 때 이 명령을 쓰세요. API가 반환하는 그대로의 스레드, 메시지의 파일, 초안, 그리고 라벨 만들기, 이름 바꾸기, 색 바꾸기, 삭제입니다.

• —openemail thread와 openemail draft도 복수형 이름처럼 동작합니다. openemail labels에는 단수형이 없습니다. openemail label은 스레드에 라벨을 붙이는 메일 명령입니다.
• —동사는 흔히 쓰는 별칭을 받습니다. list에는 ls, get에는 show와 view, create에는 new와 add, update에는 edit, delete에는 rm, del, remove입니다.
• —모든 플래그는 openemail threads list --help처럼 openemail <namespace> <verb> --help에 있습니다.

메일함의 대화입니다. CAHk7pQ2x9LmZ4 같은 스레드 ID는 threads list, openemail inbox, openemail search에서 얻습니다.

• —--folder의 기본값은 inbox이며 라벨 ID로 대조됩니다. 그래서 sent, archive, spam, trash, draft, snoozed, starred, unread가 동작하고, bin은 trash로 읽히며, USER_RECEIPTS 같은 사용자 라벨 ID도 됩니다. 아무것도 맞지 않는 폴더는 오류가 아니라 빈 페이지를 반환합니다.
• —--query는 앱의 검색 문법을 받으며, in:anywhere는 모든 폴더를 검색합니다. 스레드는 폴더와 넘긴 모든 ID를 가지고 있어야 하므로 --label-ids는 결과를 더 좁힙니다. --date-from과 --date-to는 각 스레드의 최신 메시지를 기준으로 하며, 양 끝을 모두 포함합니다.
• —threads get은 보내지 않은 답장 초안도 메시지에 포함해 isDraft: true로 표시하며, 초안 ID도 엽니다.
• —threads update에는 --read, --no-read, 또는 붙이거나 뗄 라벨이 필요합니다. 떼기가 붙이기보다 먼저 적용됩니다. 존재하지 않는 라벨 ID는 label_not_found로 거부되며 스레드에는 아무 변화도 없으므로, 라벨을 먼저 만드세요. TRASH, SNOOZED, DRAFT는 label_not_directly_settable로 거부되니 threads trash와 threads snooze를 쓰세요.
• —threads trash는 아무것도 삭제하지 않으며 스레드는 threads get으로 계속 읽을 수 있지만, 휴지통에서 스레드를 꺼내는 명령은 없습니다. 다시 알림으로 미룬 스레드를 휴지통에 넣으면 깨어날 예정도 취소됩니다.
• —threads snooze는 <wake-at>을 그대로 보내므로 Z나 오프셋이 있는 미래의 ISO 8601 시각을 주세요. 둘 다 없는 시각은 서버의 시간대로 읽힙니다. 3h 같은 지연은 잘못된 값으로 거부됩니다. 지연은 openemail snooze --until 3h가 받습니다. 스레드는 매시간 도는 작업에서 깨어나므로 최대 약 한 시간 늦을 수 있고, 언제나 받은편지함으로 돌아옵니다.
• —threads list-attachments는 모든 파일을 응답 하나에 통째로 반환합니다. 메시지 ID는 threads get의 messages에서 가져오세요. 저장된 바이트를 찾을 수 없으면 content가 빈 문자열이므로, 디코딩하기 전에 길이를 확인하세요.

메일함에 저장된 보내지 않은 메시지입니다. 초안 ID는 draft-로 시작합니다.

• —drafts list --query는 제목, 보내는 사람, 본문 앞부분을 검색하며 초안 밖으로 나가지 않습니다. older_than:30d를 비롯한 날짜 연산자는 초안이 마지막으로 저장된 시점을 기준으로 하며, to:, cc:, bcc:는 초안에서는 아무것도 맞추지 않습니다.
• —초안은 DRAFT 라벨이 붙은 스레드로 저장되므로 threads get으로 열 수 있고 openemail inbox draft로 나열됩니다. drafts get, update, delete는 일반 스레드 ID를 404로 거부합니다.
• —인수 없는 openemail drafts create는 빈 초안을 저장합니다. 길이만 확인합니다. 제목은 최대 998자, --html과 --text는 각각 최대 1,000,000자이며, 둘 다 주면 --html이 남습니다. 첨부 파일용 플래그는 없습니다.
• —drafts update는 보낸 각 필드를 교체합니다. 목록은 저장된 목록을 통째로 바꾸므로 주소 하나만 준 --to는 나머지를 지우며, 업데이트는 초안의 첨부 파일 목록을 비웁니다.
• —--thread-id는 초안이 답장하는 스레드를 기록하지만, 초안 자체는 여전히 별도의 스레드로 저장됩니다.
• —drafts create는 멱등 키를 받지 않으므로 다시 실행하면 두 번째 초안이 저장됩니다. 쉼표가 들어간 표시 이름은 망가진 받는 사람 두 개로 나뉘므로 쉼표를 빼세요.
• —openemail send --draft <id> --to <address>는 초안을 보냅니다. 본문은 초안에서 가져오고, --subject를 주지 않으면 제목도 초안에서 가져오며, 받는 사람은 지정한 사람입니다. 본문, --template, --translate와 함께 쓸 수 없습니다.

스레드에 붙일 수 있는 라벨입니다. 사용자 라벨 ID는 USER_ 뒤에 만들 때의 이름을 대문자로 바꾸고 연속된 공백을 _로 바꾼 것이 붙습니다. 그래서 Big Clients는 USER_BIG_CLIENTS입니다.

• —ID는 이름을 바꾼 뒤에도 절대 바뀌지 않으므로, 이름 대신 ID를 저장하세요.
• —INBOX, STARRED, UNREAD 같은 시스템 라벨은 나열되지 않고 바꾸거나 삭제할 수 없지만, threads update는 이를 받습니다. 시스템 라벨에 대한 labels get은 404입니다.
• —워크스페이스에는 사용자 라벨을 최대 50개까지 둘 수 있습니다. 대소문자를 무시하고 비교해서 다른 라벨이 이미 가진 이름은 label_name_taken으로 거부됩니다.
• —색은 #3B82F6 같은 16진수 값이나 gradient:sunset 같은 그라데이션 토큰입니다. --label-color는 색 전체를 JSON으로 받으며, --label-color null은 색을 지웁니다.
• —라벨은 워크스페이스에 속하므로, 이름이나 색을 바꾸거나 삭제하면 워크스페이스의 모두에게 바뀝니다.
• —labels delete는 되돌릴 수 없습니다. 같은 이름으로 라벨을 다시 만들면 같은 ID가 나오지만, 스레드에 라벨이 다시 붙지는 않습니다. labels get의 threadCount가 몇 개의 대화에서 라벨이 사라질지 알려 줍니다.

• —메일 명령은 스레드 ID를 여러 개 받아 하나하나 결과를 보고하며, --json을 주면 { results, succeeded, failed }를 출력합니다. 이 페이지의 명령은 ID 하나를 받아 API가 반환하는 것을 출력합니다.
• —openemail inbox는 마지막 작성자와 제목을 보여 주려고 나열하는 모든 스레드를 읽습니다. threads list는 페이지마다 요청 하나를 보내고 ID만 출력하는데, 파이프라인에는 그것으로 충분합니다.
• —openemail read는 HTML 메시지를 텍스트로 바꾸고 스레드를 읽음으로 표시합니다. threads get은 API가 반환하는 그대로 스레드를 출력하며 아무것도 바꾸지 않습니다.

스레드를 읽음으로 표시하고, 보관하고, 라벨을 붙이는 일을 요청 하나로 합니다. mark read, archive, label add로는 요청 세 개가 필요합니다:

openemail threads update CAHk7pQ2x9LmZ4 --read --add-label-ids ARCHIVE,USER_RECEIPTS --remove-label-ids INBOX --json

라벨을 만들고 일치하는 모든 스레드에 붙입니다. 파이프로 보내면 --all은 한 줄에 JSON 객체 하나를 출력합니다:

openemail labels create --name Receipts --color-background-color gradient:meadowopenemail threads list --query "in:anywhere subject:receipt newer_than:1y" --all | jq -r .id | xargs openemail label add --label USER_RECEIPTS

메시지에서 파일 하나를 저장합니다. 메시지 ID는 threads get의 messages에 있습니다:

openemail threads get CAHk7pQ2x9LmZ4 --json | jq -r ".messages[].id"openemail threads list-attachments CAHk7pQ2x9LmZ4 message_4c1b257a --json | jq -r '.[] | select(.filename == "invoice.pdf") | .content' | base64 --decode > invoice.pdf

초안을 쓰고, 바꾸고, 다시 읽은 뒤 보냅니다:

DRAFT=$(openemail drafts create --to [email protected] --subject "Engine notes for Thursday" --html "<p>Agenda below.</p>" --json | jq -r .id)openemail drafts update "$DRAFT" --to [email protected],[email protected]openemail drafts get "$DRAFT"openemail send --draft "$DRAFT" --from [email protected] --to [email protected],[email protected]

30일 동안 아무도 저장하지 않은 초안을 정리합니다. 드라이 런은 각 DELETE를 보내지 않고 출력하며, --yes가 확인에 답합니다:

openemail drafts list --query older_than:30d --all | jq -r .id > stale.txtxargs -n 1 openemail drafts delete --dry-run < stale.txtxargs -n 1 openemail drafts delete --yes < stale.txt

팔레트에서 그라데이션을 고르고, 변경을 미리 보고, 적용한 뒤, 나중에 색을 다시 뗍니다:

openemail labels list-colors --json | jq -r '.[] | select(.kind == "gradient") | .value'openemail labels update USER_RECEIPTS --name "Receipts 2026" --color-background-color gradient:aurora --dry-runopenemail labels update USER_RECEIPTS --name "Receipts 2026" --color-background-color gradient:auroraopenemail labels update USER_RECEIPTS --label-color null

범위가 없으면 종료 코드 4로 멈춥니다. 이 명령들은 브라우저 로그인이든 API 키든 인증 코드를 요구하지 않습니다.

일부 주소로 제한된 로그인이나 키는 그 주소로 배달된 스레드만 보며, 다른 스레드는 존재하지 않는 것처럼 404입니다. 라벨은 워크스페이스에 속하므로 모든 라벨을 보지만, threadCount는 볼 수 있는 대화만 셉니다.

• —threads list, drafts list, labels list는 한 페이지를 읽습니다. --limit로 달리 정하지 않으면 25개이며 최대 100개입니다. --cursor는 페이지가 출력한 커서부터 이어 갑니다. 스레드 커서는 발급될 때의 순서를 유지하므로 같은 필터를 함께 보내세요.
• —--all은 모든 페이지를 읽고 --max <n>은 그만큼 읽고 멈춥니다. 파이프로 보내거나 --ndjson을 주면 한 줄에 JSON 객체 하나를, --json을 주면 { items, hasMore, nextCursor } 문서 하나를 출력합니다.
• —마지막 페이지로 드러나는 페이지에서도 hasMore가 true일 수 있으며, 그러면 다음 호출은 항목 없이 돌아옵니다. 페이지를 넘기는 동안 새 메일을 받은 스레드는 커서 앞으로 이동해 이후 페이지에 나오지 않으며, 페이지를 넘기는 동안 저장된 초안도 마찬가지입니다.
• —threads trash, drafts delete, labels delete는 확인을 요청합니다. --json, --no-input을 주었거나 터미널이 없는 무인 실행에서는 --yes를 주지 않는 한 종료 코드 2로 멈추고 아무것도 바꾸지 않습니다.
• —--dry-run은 명령이 보낼 요청을 자격 증명을 가린 채 출력하고, 보내거나 확인을 묻지 않고 코드 0으로 종료합니다. --json을 주면 { dryRun, request }를 출력합니다.

--data는 본문 전체를 JSON으로 받습니다. 인라인, @path로 파일에서, -로 stdin에서 줄 수 있으며, 함께 준 플래그는 해당 키를 덮어씁니다.

빈 플래그 값은 사용 오류이므로, 빈 값으로 비우는 필드는 대신 --data로 보냅니다. --label-color null은 라벨의 색을 지웁니다.

openemail drafts update draft-5f0c2a9e-8b1d-4e7a-a3c6-2d9f41b7e0c8 --data '{"from":""}'openemail drafts update draft-5f0c2a9e-8b1d-4e7a-a3c6-2d9f41b7e0c8 --data '{"threadId":""}'openemail drafts update draft-5f0c2a9e-8b1d-4e7a-a3c6-2d9f41b7e0c8 --data '{"to":[]}'openemail drafts create --data @draft.json --subject "Overrides the file"

첫 번째는 보내는 사람 없이 초안을 저장하고, 두 번째는 답장하던 스레드에서 초안을 떼어 내며, 세 번째는 받는 사람을 지웁니다.

openemail threads --helpopenemail threads list --helpopenemail drafts create --help --json

openemail <namespace> <verb> --help는 각 인수와 플래그의 타입, 호출에 필요한 범위, 메서드와 경로, 반환값, API 레퍼런스의 참고 사항을 보여 줍니다. --json을 붙이면 같은 도움말을 데이터로 받습니다.