دامنه‌ها و نشانی‌ها

دو فضای نام دامنه‌های شما را پوشش می‌دهند. openemail domains دامنه‌های متصل به فضای کاری را مدیریت می‌کند: افزودن و برداشتنشان، رکوردهای DNS که هر کدام لازم دارد، اینکه آیا می‌تواند دریافت کند و بفرستد، catch-all آن، دامنه‌های ردیابی و فایل‌هایش، و نشانی‌های روی آن. openemail addresses به پرسشی محدودتر پاسخ می‌دهد: کلید یا ورودی که به کار می‌برید با کدام نشانی‌ها مجاز به فرستادن است.

• —فرمان دامنه شناسهٔ دامنه را می‌گیرد، یک UUID از domains list یا domains create. نام میزبان به جای آن پذیرفته نمی‌شود، پس openemail domains get acme.com یک 404 است و با کد 5 خارج می‌شود.
• —فرمان نشانی شناسهٔ دامنه و سپس شناسهٔ نشانی را می‌گیرد، یک UUID از domains list-addresses یا domains create-address.
• —domain و address هم به‌عنوان نام فضای نام کار می‌کنند. فعل‌های دامنه به نام‌های مستعار معمول پاسخ می‌دهند، مانند ls، show، new، edit و rm، و addresses list هم همین‌طور. پنج فعلِ نشانی‌های روی یک دامنه، مانند create-address، نام مستعاری ندارند.
• —openemail <command> --help هر آرگومان و پرچم را با نوعش، دامنهٔ مجوزی که فراخوانی لازم دارد، متد و مسیرش و آنچه برمی‌گردد فهرست می‌کند. برای همان صفحه به‌صورت داده، --json را اضافه کنید.

یک دامنه دو واقعیت مستقل را گزارش می‌دهد. receiving.verified وقتی true می‌شود که DNS عمومی با رکوردهای MX و رکورد TXT _openemail-challenge آن پاسخ دهد، و از آن پس نامه دریافت می‌کند. sending.status وضعیت امضا است همان‌طور که آخرین بررسی دید: verified، pending، failed، no_identity یا unknown. sending.canSend می‌گوید آیا ارسالی از آن دامنه همین حالا پذیرفته می‌شود، و حکم منفیِ قدیمی‌تر از یک روز نامعلوم شمرده می‌شود، پس اسکریپت باید روی canSend شاخه بزند نه روی status. تا وقتی false است، ارسال از آن دامنه با 409 domain_not_sendable رد می‌شود.

• —domains create نخستین بررسی DNS را در طول فراخوانی اجرا می‌کند، پس هر درایه در records از پیش یک status دارد: found، missing، یا null وقتی هنوز بررسی نشده است. هر رکورد را دقیقاً همان‌طور که داده شده منتشر کنید، چون مقدارها مختص آن دامنه‌اند.
• —domains verify بی‌درنگ بررسی می‌کند. تا 10 ثانیه پس از آخرین بررسی چیز تازه‌ای بررسی نمی‌کند و دامنه را همان‌طور که هست برمی‌گرداند. روی دامنهٔ تأییدشده رکوردهای امضا را دوباره بررسی می‌کند، پس sending تازه است.
• —domains get روی دامنهٔ تأییدنشده وقتی آخرین بررسی بیش از 20 ثانیه قدمت داشته باشد دوباره بررسی می‌کند، پس پرسیدن پیاپی get هم کار می‌کند و فقط domains:read لازم دارد، در حالی که verify به domains:write نیاز دارد.
• —رکوردی که همین لحظه منتشر شده ممکن است چند دقیقه طول بکشد تا در DNS عمومی دیده شود.

در ترمینال، get، create و verify در هر سطر یک فیلد چاپ می‌کنند، و بلوک‌های تودرتو مانند receiving، sending و records به‌صورت JSON فشرده. --json را اضافه کنید و آن‌ها را با ابزاری مانند jq بخوانید، همان‌طور که نمونه‌های زیر می‌کنند.

domains update سه تنظیم را تغییر می‌دهد که به هم وابسته نیستند. پرچمی که نگذارید دست‌نخورده می‌ماند، و بدون هیچ پرچمی دامنه بدون تغییر برمی‌گردد.

• —میزبان تازه در همان فراخوانی ذخیره و بررسی می‌شود. یک رکورد CNAME با نام record.name و مقدار record.value از بلوک tracking یا storage پاسخ منتشر کنید، با هر پروکسی‌ای خاموش. راه‌اندازی دوبارهٔ یک میزبان ممکن است مقدار دیگری به آن بدهد، پس همان مقداری را منتشر کنید که آخرین پاسخ گزارش می‌دهد.
• —تا وقتی بررسی‌ای موفق نشود، میزبان pending است و نامه‌های تازه با میزبان پیش‌فرض OpenEmail می‌روند. به‌محض موفقیت یک بررسی، active می‌شود. OpenEmail خودش به بررسی ادامه می‌دهد، و میزبان فعالی که سه بررسی پیاپی را رد کند، یا از آخرین بررسی موفقش 2 ساعت گذشته باشد، failed می‌شود و نامه‌های تازه به میزبان پیش‌فرض برمی‌گردند.
• —میزبان را با null بردارید، مانند --tracking-host null. مقدار خالی مانند --tracking-host= در CLI خطای کاربرد است و با کد 2 خارج می‌شود.
• —میزبان تازه به دامنهٔ تأییدشده نیاز دارد، یا دست‌کم به انتشار رکورد TXT _openemail-challenge آن. در غیر این صورت فراخوانی با 409 domain_not_verified رد می‌شود.
• —پرچم‌ها به ترتیب اعمال می‌شوند: catch-all، سپس دامنهٔ ردیابی، سپس دامنهٔ فایل‌ها. پرچمِ بعدی‌ای که رد شود ممکن است تغییرِ پیشین را ذخیره‌شده باقی بگذارد، پس وقتی هر کدام باید مستقل باشد آن‌ها را در فراخوانی‌های جداگانه بفرستید.

یک دامنه نشانی‌هایی را دارد که دستی یا از طریق API ساخته شده‌اند، و آن‌هایی را که catch-all هنگام رسیدن نخستین نامه‌شان گرفته است. list-addresses هر دو نوع را نشان می‌دهد، از جمله غیرفعال‌ها. خود catch-all یک ردیف نیست: receiving.catchAll روی دامنه است.

• —create-address پرچم --local-part را می‌گیرد، یعنی بخش پیش از @، و یک --label اختیاری. لازم نیست دامنه هنوز تأیید شده باشد، اما نشانی تا آن زمان چیزی دریافت نمی‌کند. * به‌تنهایی رد می‌شود، چون catch-all این‌طور نوشته می‌شود.
• —ساختن نشانی‌ای که از پیش وجود دارد، یا نشانی‌ای که برداشته شده، خطا نیست. فعال برمی‌گردد، با برچسبی که فرستادید یا بی‌برچسب، و شناسه‌اش را نگه می‌دارد. نشانی‌ای که catch-all گرفته بود به نشانی دستی تبدیل می‌شود، پس پس از خاموش شدن catch-all هم دریافت می‌کند.
• —با روشن بودن catch-all، نشانی تازه با تنظیمات مخصوص نشانیِ catch-all آغاز می‌شود، مانند امضا و ردیابی آن، به جز تنظیمات حریم خصوصی. این‌ها یک بار کپی می‌شوند و هماهنگ نگه داشته نمی‌شوند.
• —update-address --no-enabled دریافت نامه در آن نشانی را متوقف می‌کند، پس فرستندگان برگشت می‌گیرند، و از آن هم نمی‌توان فرستاد. نامه‌ها، تنظیمات و کسانی که به آن دسترسی دارند را نگه می‌دارد، و --enabled از همان جایی که مانده بود ادامه می‌دهد. --label نامش را تغییر می‌دهد و --label null نام را برمی‌دارد.
• —delete-address فراتر می‌رود. نامه به آن نشانی حتی با catch-all روشن رد می‌شود، بازارسالش متوقف می‌شود، تنظیماتش حذف می‌شوند، کسانی که به آن دسترسی داشتند آن دسترسی را از دست می‌دهند، و ورود با گذرواژه‌اش ابطال می‌شود. نامه‌هایی که پیش‌تر دریافت کرده در صندوق پستی می‌مانند. ساختن دوباره‌اش همان شناسه را برمی‌گرداند، بدون تنظیمات یا دسترسی‌های قدیمی.

openemail addresses list به پرسشِ پشت یک 403 from_address_forbidden پاسخ می‌دهد: کلید یا ورودی که با آن فراخوانی می‌کنید مجاز است کدام نشانی‌ها را در From بگذارد. به جای یک دامنهٔ مجوز خواندن به emails:send نیاز دارد، چون آنچه را یک ارسال می‌پذیرد شرح می‌دهد.

• —در ترمینال دو جدول چاپ می‌کند: نشانی‌ها، هر کدام با اینکه فعال است یا نه و اینکه می‌توانید از آن بفرستید یا نه، سپس دامنه‌ها، هر کدام با اینکه برای دریافت و ارسال تأیید شده یا نه، و catch-all آن.
• —unrestricted وقتی true است که هیچ چیز اعتبارنامه را محدود نکند. آنگاه از هر local-part روی دامنه‌های فضای کاری می‌توان فرستاد، حتی آن‌هایی که کسی نساخته است. در غیر این صورت canSend فقط برای نشانی فعالی true است که اعتبارنامه آن را پوشش دهد، از طریق دامنهٔ کاملی که دارد یا فهرست نشانی‌های خودش.
• —canSend برای نشانی غیرفعال، برای نشانی‌ای که اعتبارنامه پوششش نمی‌دهد، و برای نشانی‌ای که دامنه‌اش هنوز نمی‌تواند امضا کند false است.
• —فقط نشانی‌های ساخته‌شده فهرست می‌شوند. اعتبارنامه‌ای که یک دامنهٔ کامل دارد همچنان می‌تواند با هر local-part روی آن بفرستد، و از نشانی‌ای در فهرستش که صندوق پستی پشتش نیست می‌توان فرستاد بی‌آنکه اینجا دیده شود.
• —با --json برای یک صفحه { unrestricted, addresses, domains, hasMore, nextCursor } و با --all مقدار { unrestricted, addresses, domains } را چاپ می‌کند، به جای سند { items, hasMore, nextCursor } که فهرست‌های دیگر چاپ می‌کنند. با --all در یک لوله، یا با --ndjson، در هر سطر یک نشانی چاپ می‌کند.

openemail status ورود شما، addresses list و domains list را هم‌زمان می‌خواند و با هم چاپ می‌کند. جدول نشانی‌های فرستنده‌اش هر نشانی را با اینکه می‌تواند بفرستد یا نه و فعال است یا نه نشان می‌دهد. جدول دامنه‌هایش هر دامنه را با verified یا not verified برای دریافت، وضعیت ارسالش و catch-all آن نشان می‌دهد. 100 مورد نخست هر کدام را نشان می‌دهد و فرمان --all را برای بقیه نام می‌برد.

• —بخشی که اعتبارنامهٔ شما اجازهٔ خواندنش را ندارد، مانند دامنه‌ها بدون domains:read یا نشانی‌ها بدون emails:send، «در دسترس نیست» را با دلیلش می‌گوید و بقیه همچنان چاپ می‌شود.
• —وقتی هنوز نشانی‌ای نباشد، openemail domains create --domain example.com را پیشنهاد می‌کند.
• —openemail status --json یک شیء با account، addresses، domains و unavailable چاپ می‌کند، که در آن unavailable دلیل هر بخشی را که خوانده نشد می‌دهد.

اتصال یک ارائه‌دهندهٔ DNS، تا رکوردهای دامنهٔ تازه برایتان نوشته شوند، در 0.0.2 فقط در برنامهٔ وب انجام می‌شود. openemail open providers، یا open dns، آن صفحه را باز می‌کند. open domains دامنه‌ها و رکوردهای DNS آن‌ها را باز می‌کند و open addresses نشانی‌ها را. بازارسال هم در برنامهٔ وب است و open forwarding <address> آن را برای یک نشانی باز می‌کند. --print به جای باز کردن مرورگر پیوند را چاپ می‌کند.

openemail domains create --domain acme.com --json > acme.jsonjq -r '.records[] | [.type, .name, .value, (.priority // "")] | @tsv' acme.jsonopenemail domains verify "$(jq -r .id acme.json)"

id=b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6funtil openemail domains get "$id" --json | jq -e .receiving.verified > /dev/null; do  sleep 30doneopenemail domains get "$id" --json | jq '.sending | {status, canSend, error}'

openemail domains list-addresses "$id" --allopenemail domains create-address "$id" --local-part invoices --label Invoicesopenemail domains update "$id" --no-catch-all --dry-runopenemail domains update "$id" --no-catch-all

ساختن دستی invoices آن را پس از خاموش شدن catch-all در حال دریافت نگه می‌دارد، در حالی که نامه به هر نشانی دیگری که catch-all گرفته بود رد می‌شود. اجرای آزمایشی PATCH و بدنه‌اش را بدون فرستادن چاپ می‌کند.

openemail domains update "$id" --tracking-host links.acme.com --json | jq '.tracking | {status, record, error}'openemail domains update "$id" --tracking-host null

address_id=$(openemail domains list-addresses "$id" --all | jq -r 'select(.address == "[email protected]") | .id')openemail domains update-address "$id" "$address_id" --no-enabledopenemail domains delete-address "$id" "$address_id" --yes

خاموش کردن نشانی در گام نخست با --enabled برگشت‌پذیر است. حذف برگشت‌پذیر نیست و در اسکریپت به --yes نیاز دارد. با ورود از طریق مرورگر کد تأیید هویت هم می‌خواهد که --yes هرگز از آن نمی‌گذرد.

openemail domains list --all | jq -r 'select(.sending.canSend | not) | [.domain, .sending.status] | @tsv'openemail addresses list --all --json | jq -r '.addresses[] | select(.canSend) | .address'

• —ورود یا کلیدی که آن دامنهٔ مجوز را ندارد با کد خروج 4 متوقف می‌شود، دامنهٔ مجوزِ ناموجود را نام می‌برد و می‌گوید چطور آن را به دست آورید.
• —domains delete و domains delete-address از شما تأیید می‌خواهند. پاسخ منفی با کد 10 خارج می‌شود و چیزی را تغییر نمی‌دهد. بدون نظارت و بدون --yes، پیش از فرستادن هر چیزی با کد خروج 2 متوقف می‌شوند.
• —با ورود از طریق مرورگر، این دو حذف کد تأیید هویت هم می‌خواهند، همان‌طور که برنامهٔ وب. بدون نظارت کسی نمی‌تواند آن را تایپ کند، پس فرمان با کد خروج 4 متوقف می‌شود. نخست openemail verify را اجرا کنید تا 60 دقیقهٔ بعد کدی لازم نباشد. از کلید API هرگز پرسیده نمی‌شود.
• —--dry-run درخواستی را که یک تغییر می‌فرستاد، با بدنه‌اش، چاپ می‌کند و بدون فرستادن یا خواستن تأیید با کد 0 خارج می‌شود.
• —یک فهرست یک صفحه می‌خواند: --limit از 1 تا 100 می‌گیرد و وقتی نباشد سرور 25 می‌فرستد، و --cursor مقدار nextCursor صفحهٔ پیشین را می‌گیرد. --all همهٔ صفحه‌ها را می‌خواند، --max <n> پس از همان تعداد مورد می‌ایستد، و --ndjson، یا --all در یک لوله، در هر سطر یک شیء JSON چاپ می‌کند. با --json، domains list و list-addresses یک سند { items, hasMore, nextCursor } چاپ می‌کنند.
• —کلید یا ورودی که به دامنه‌ها یا نشانی‌های مشخصی محدود است همچنان همهٔ دامنه‌ها و نشانی‌ها را می‌بیند. نمی‌تواند دامنه‌ای اضافه کند، و هر تغییر دیگری نیاز دارد که کل آن دامنه میان دامنه‌هایی باشد که دارد، وگرنه فراخوانی با 422 capability_unsupported رد می‌شود.
• —هر رد با کدِ وضعیتش خارج می‌شود: 4 برای 403، مانند domain_allowance_reached وقتی طرح اجازهٔ دامنهٔ بیشتری نمی‌دهد، 5 برای 404، 6 برای 409، مانند domain_already_added یا domain_claimed، و 7 برای 422، مانند invalid_tracking_host یا workspace_limit_reached.
• —آخرین دامنهٔ یک فضای کاری را نمی‌توان از CLI برداشت. این یک 409 last_domain است، چون برداشتنش کل صندوق پستی را حذف می‌کند و برنامهٔ وب نخست برای آن تأیید می‌گیرد. دامنه‌ای که نشانی‌های رزروشدهٔ حساب را دارد یک 409 domain_holds_reserved_addresses است.
• —domains create و دو حذف پس از خرابی شبکه هرگز دوباره تلاش نمی‌شوند. یک 409 domain_already_added، یا یک 404 در تلاش دوم خودتان پس از گم شدن پاسخ، یعنی اولی کار کرده است. verify، update، create-address و update-address خودکار دوباره تلاش می‌شوند، چون دو بار فرستادنشان همان نتیجه را می‌گذارد.