رشته‌ها، پیش‌نویس‌ها و برچسب‌ها

فرمان‌های نامه، مانند inbox، read، archive و label add، برای آدم‌ها نوشته شده‌اند: چند شناسهٔ رشته را یک‌جا می‌گیرند، خروجی‌شان را قالب‌بندی می‌کنند و شناسه‌های برچسب را از چشم دور نگه می‌دارند. هر کدام فرمان‌هایی از این صفحه را اجرا می‌کند، که متدهای SDK برای رشته‌ها، پیش‌نویس‌ها و برچسب‌ها هستند، یک فرمان برای هر متد، پس threads.listAttachments می‌شود openemail threads list-attachments.

وقتی به چیزی نیاز دارید که فرمان‌های نامه کنار می‌گذارند از این‌ها استفاده کنید: رشته‌ای دقیقاً همان‌طور که API برمی‌گرداند، فایل‌های یک پیام، پیش‌نویس‌ها، و ساختن، تغییر نام، تغییر رنگ یا حذف برچسب‌ها.

• —openemail thread و openemail draft هم مانند نام‌های جمع کار می‌کنند. openemail labels شکل مفرد ندارد: openemail label فرمان نامه‌ای است که برچسب‌ها را روی رشته‌ها می‌گذارد.
• —فعل‌ها نام‌های مستعار معمول را می‌پذیرند: ls به جای list، show و view به جای get، new و add به جای create، edit به جای update، و rm، del و remove به جای delete.
• —همهٔ پرچم‌ها در openemail <namespace> <verb> --help هستند، مانند openemail threads list --help.

گفت‌وگوهای صندوق پستی. شناسهٔ رشته‌ای مانند CAHk7pQ2x9LmZ4 از threads list، openemail inbox یا openemail search می‌آید.

• —پیش‌فرض --folder برابر inbox است و به‌عنوان شناسهٔ برچسب تطبیق داده می‌شود، پس sent، archive، spam، trash، draft، snoozed، starred و unread کار می‌کنند، bin به‌صورت trash خوانده می‌شود، و شناسهٔ برچسب کاربری مانند USER_RECEIPTS هم کار می‌کند. پوشه‌ای که با چیزی جور نشود صفحه‌ای خالی برمی‌گرداند، نه خطا.
• —--query نحو جست‌وجوی برنامه را می‌پذیرد و in:anywhere در همهٔ پوشه‌ها جست‌وجو می‌کند. --label-ids بیشتر محدود می‌کند، چون رشته باید پوشه و همهٔ شناسه‌هایی را که می‌دهید داشته باشد. --date-from و --date-to تازه‌ترین پیام هر رشته را می‌خوانند و هر دو سر بازه را شامل می‌شوند.
• —threads get پاسخ‌های پیش‌نویسِ فرستاده‌نشده را با علامت isDraft: true میان پیام‌ها می‌آورد، و شناسهٔ پیش‌نویس را هم باز می‌کند.
• —threads update به --read، --no-read یا برچسبی برای افزودن یا برداشتن نیاز دارد. برداشتن‌ها پیش از افزودن‌ها اعمال می‌شوند. شناسهٔ برچسبی که به هیچ برچسبی اشاره نکند با label_not_found رد می‌شود و چیزی در رشته تغییر نمی‌کند، پس نخست برچسب را بسازید. TRASH، SNOOZED و DRAFT با label_not_directly_settable رد می‌شوند: از threads trash و threads snooze استفاده کنید.
• —threads trash چیزی را حذف نمی‌کند و رشته با threads get خواندنی می‌ماند، اما هیچ فرمانی رشته را از سطل زباله بیرون نمی‌آورد. بردن رشتهٔ به‌تعویق‌افتاده به زباله، بیدار شدنش را هم لغو می‌کند.
• —threads snooze مقدار <wake-at> را همان‌طور که هست می‌فرستد، پس لحظه‌ای در آینده به قالب ISO 8601 با Z یا یک آفست به آن بدهید، چون زمانی که هیچ‌کدام را ندارد در منطقهٔ زمانی سرور خوانده می‌شود. تأخیری مانند 3h نامعتبر شمرده و رد می‌شود. openemail snooze --until 3h تأخیر می‌پذیرد. رشته‌ها در یک پیمایش ساعتی بیدار می‌شوند، تا حدود یک ساعت دیرتر، و همیشه به صندوق ورودی برمی‌گردند.
• —threads list-attachments همهٔ فایل‌ها را کامل در یک پاسخ برمی‌گرداند. شناسهٔ پیام را از messages در threads get بگیرید. وقتی بایت‌های ذخیره‌شده پیدا نشوند content رشته‌ای خالی است، پس پیش از رمزگشایی طولش را بررسی کنید.

پیام‌های فرستاده‌نشده‌ای که در صندوق پستی ذخیره شده‌اند. شناسهٔ پیش‌نویس با draft- آغاز می‌شود.

• —drafts list --query در موضوع، فرستنده و آغاز متن جست‌وجو می‌کند و هرگز از پیش‌نویس‌ها بیرون نمی‌رود. older_than:30d و دیگر عملگرهای تاریخ زمان آخرین ذخیرهٔ پیش‌نویس را می‌خوانند، و to:، cc: و bcc: روی پیش‌نویس با چیزی جور نمی‌شوند.
• —پیش‌نویس به‌صورت رشته‌ای با برچسب DRAFT ذخیره می‌شود، پس threads get آن را باز می‌کند و openemail inbox draft پیش‌نویس‌ها را فهرست می‌کند. drafts get، update و delete شناسهٔ رشتهٔ معمولی را با 404 رد می‌کنند.
• —openemail drafts create خالی یک پیش‌نویس خالی ذخیره می‌کند. فقط طول‌ها بررسی می‌شوند: موضوع تا 998 نویسه، و --html و --text هر کدام تا 1,000,000، و وقتی هر دو تنظیم شوند --html نگه داشته می‌شود. پرچمی برای پیوست‌ها وجود ندارد.
• —drafts update هر فیلدی را که بفرستید جایگزین می‌کند. یک فهرست کل فهرست ذخیره‌شده را جایگزین می‌کند، پس --to با یک نشانی بقیه را کنار می‌گذارد، و هر به‌روزرسانی فهرست پیوست‌های پیش‌نویس را خالی می‌کند.
• —--thread-id رشته‌ای را که پیش‌نویس به آن پاسخ می‌دهد ثبت می‌کند، اما پیش‌نویس همچنان به‌صورت رشته‌ای جداگانه ذخیره می‌شود.
• —اجرای دوبارهٔ drafts create پیش‌نویس دومی ذخیره می‌کند، چون کلید idempotency نمی‌گیرد. نام نمایشی‌ای که ویرگول دارد به دو گیرندهٔ خراب تقسیم می‌شود، پس ویرگول را حذف کنید.
• —openemail send --draft <id> --to <address> یک پیش‌نویس را می‌فرستد. متن از پیش‌نویس می‌آید، و موضوع هم مگر اینکه --subject بدهید، در حالی که گیرندگان همان‌هایی هستند که نام می‌برید. نمی‌توان آن را با متن، --template یا --translate ترکیب کرد.

برچسب‌هایی که یک رشته می‌تواند داشته باشد. شناسهٔ برچسب کاربری USER_ است و پس از آن نامی که با آن ساخته شده، با حروف بزرگ، و هر رشته فاصله به _ تبدیل می‌شود، پس Big Clients می‌شود USER_BIG_CLIENTS.

• —شناسه هرگز تغییر نمی‌کند، حتی پس از تغییر نام، پس به جای نام‌ها شناسه‌ها را ذخیره کنید.
• —برچسب‌های سیستمی مانند INBOX، STARRED و UNREAD فهرست نمی‌شوند و نمی‌توان آن‌ها را تغییر داد یا حذف کرد، هرچند threads update آن‌ها را می‌پذیرد. labels get روی یکی از آن‌ها 404 است.
• —هر فضای کاری تا 50 برچسب کاربری دارد. نامی که برچسب دیگری از پیش دارد، بدون توجه به بزرگی و کوچکی حروف، با label_name_taken رد می‌شود.
• —رنگ یک مقدار هگز مانند #3B82F6 یا یک نشانهٔ گرادیان مانند gradient:sunset است. --label-color کل رنگ را به‌صورت JSON می‌گیرد و --label-color null آن را پاک می‌کند.
• —برچسب از آنِ فضای کاری است، پس تغییر نام، تغییر رنگ یا حذف آن برای همهٔ اعضای آن تغییرش می‌دهد.
• —labels delete بازگشت ندارد. ساختن دوبارهٔ برچسبی با همان نام همان شناسه را می‌دهد، اما رشته‌ها آن را پس نمی‌گیرند. threadCount آن در labels get می‌گوید چند گفت‌وگو آن را از دست می‌دهند.

• —یک فرمان نامه چند شناسهٔ رشته می‌گیرد و دربارهٔ هر کدام گزارش می‌دهد، و با --json مقدار { results, succeeded, failed } را چاپ می‌کند. فرمانی در این صفحه یک شناسه می‌گیرد و آنچه API برمی‌گرداند را چاپ می‌کند.
• —openemail inbox هر رشته‌ای را که فهرست می‌کند می‌خواند تا نشان دهد آخرین بار چه کسی نوشته و موضوع چیست. threads list برای هر صفحه یک درخواست می‌فرستد و فقط شناسه‌ها را چاپ می‌کند، که تمام نیاز یک خط لوله است.
• —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

یک فایل را از یک پیام ذخیره کنید. شناسه‌های پیام در messages خروجی threads get هستند:

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 یک صفحه می‌خوانند، 25 مگر اینکه --limit چیز دیگری بگوید، تا 100. --cursor از نشانگری که یک صفحه چاپ کرده ادامه می‌دهد. نشانگر رشته‌ها ترتیبی را که با آن صادر شده نگه می‌دارد، پس همان فیلترها را همراهش بفرستید.
• —--all همهٔ صفحه‌ها را می‌خواند و --max <n> پس از همان تعداد می‌ایستد. وقتی به لوله داده شود یا با --ndjson در هر سطر یک شیء JSON چاپ می‌کند، و با --json یک سند { items, hasMore, nextCursor }.
• —hasMore ممکن است روی صفحه‌ای که آخرین صفحه از آب درمی‌آید true باشد، و فراخوانی بعدی آنگاه هیچ موردی برنمی‌گرداند. رشته‌ای که هنگام ورق زدن شما نامهٔ تازه می‌گیرد از نشانگر جلو می‌افتد و صفحه‌های بعدی آن را برنمی‌گردانند، و پیش‌نویسی که هنگام ورق زدن ذخیره شود هم همین‌طور.
• —threads trash، drafts delete و labels delete از شما تأیید می‌خواهند. بدون نظارت، با --json، --no-input یا بدون ترمینال، با کد خروج 2 متوقف می‌شوند و چیزی را تغییر نمی‌دهند مگر اینکه --yes بدهید.
• —--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 را اضافه کنید.