احراز هویت

openemail login را در یک ترمینال اجرا کنید تا بپرسد کدام را می‌خواهید. در هر دو حالت ورود به‌صورت یک نمایه ذخیره می‌شود و هر فرمان بعدی از نمایهٔ فعال استفاده می‌کند.

• —فقط یک ورود با مرورگر می‌تواند از ai compose، ai summarize و فرمان‌های MCP استفاده کند.
• —ورود با مرورگر تا وقتی تأییدی که انتخاب کرده‌اید منقضی شود یا خارج شوید معتبر است. کلید تا وقتی ابطال نشده کار می‌کند.

1. 1openemail login برای این ورود برنامهٔ تازه‌ای به نام OpenEmail CLI on <your computer> ثبت می‌کند و صفحهٔ تأیید OpenEmail را در مرورگرتان باز می‌کند. اگر مرورگر باز نشد، از پیوندی که چاپ می‌کند استفاده کنید.
2. 2در صورت نیاز وارد شوید، سپس فضای کاری، دسترسی CLI (خواندن، خواندن و فرستادن، کامل یا مجموعهٔ مجوزهای خودتان)، دامنه‌ها یا نشانی‌هایی که به آن‌ها می‌رسد و مدت تأیید را انتخاب کنید.
3. 3تأیید کنید. مرورگر تأیید را خودش به ترمینال برمی‌گرداند و می‌توانید زبانه را ببندید. CLI چاپ می‌کند با چه کسی وارد شده‌اید، فضای کاری را و اینکه تأیید کی منقضی می‌شود.

openemail loginopenemail login --scopes emails:send,threads:readopenemail login --profile work

• —CLI ده دقیقه منتظر تأیید شما می‌ماند. انتخاب «حالا نه» در صفحهٔ تأیید، ورود را با کد خروج 10 لغو می‌کند.
• —--scopes مجوزها را در صفحهٔ تأیید از پیش انتخاب می‌کند و هنوز می‌توانید آنجا تغییرشان دهید.
• —وقتی نمایه از قبل ورودی دارد، ترمینال پیش از جایگزینی آن می‌پرسد. بدون نظارت، رد می‌کند مگر اینکه --force یا --yes بدهید. جایگزین کردن یک ورود با مرورگر، ورود قبلی را ابطال می‌کند.

در زیر آن جریان OAuth است که سرور MCP به کار می‌برد: یک کلاینت عمومی با PKCE، یک کد یک‌بارمصرف و یک توکن دسترسی که یک ساعت اعتبار دارد و برای شما تمدید می‌شود. مرورگر روی یک درگاه تصادفی به 127.0.0.1 برمی‌گردد و آنجا فقط کد همین ورود پذیرفته می‌شود.

وقتی CLI نمی‌تواند روی این دستگاه مرورگری باز کند، به جای آن پیوند را چاپ می‌کند: از طریق SSH، در CI، در Linux بدون نمایشگر، یا وقتی --no-browser می‌دهید. پیوند را در مرورگری روی هر دستگاهی باز کنید و تأیید کنید. سپس صفحه یک کد ورود نشان می‌دهد که آن را در ترمینال می‌چسبانید.

$ openemail login --no-browserOpen this link in a browser on any device to sign in:  https://api.openemail.uk/auth/mcp/authorize?response_type=code&client_id=…Paste the code from your browser

• —هر کد فقط برای ورودی کار می‌کند که پیوند را چاپ کرده است، پس کد زبانهٔ دیگری رد می‌شود.
• —چسباندن کل نشانی‌ای که مرورگر به آن رسیده هم کار می‌کند.
• —بدون ترمینال، کد را از طریق stdin بدهید.

کلید API یک اسکریپت را بدون مرورگر وارد می‌کند و هرگز از آن کد خواسته نمی‌شود. یکی را در تنظیمات ← کلیدهای API (openemail open api-keys) فقط با دامنه‌های مجوزی که اسکریپت نیاز دارد بسازید. CLI پیش از ذخیرهٔ کلید آن را با GET /keys/self بررسی می‌کند و کلیدهای oe_live_ و oe_test_ را می‌پذیرد. نامه‌ای که با کلید آزمایشی فرستاده شود هرگز تحویل داده نمی‌شود.

openemail login --with-token < ~/.config/openemail/keyecho "$OPENEMAIL_KEY" | openemail login --with-token --profile ciopenemail login --token oe_live_…

--token هم کار می‌کند، اما کلید در تاریخچهٔ پوسته‌تان می‌ماند، پس CLI هشدار می‌دهد و --with-token را پیشنهاد می‌کند. دو راه برای استفاده از کلید بدون ذخیرهٔ آن هست:

• —OPENEMAIL_API_KEY در محیط را هر فرمانی که آن را ببیند، پیش از هر نمایهٔ ذخیره‌شده، به کار می‌برد.
• —--api-key <key> فقط برای همان یک فرمان به کار می‌رود.

وقتی بیش از یک اعتبارنامه باشد، نخستین مورد از این‌ها برنده است: --api-key، OPENEMAIL_API_KEY، نمایه‌ای که --profile نام می‌برد، نمایه‌ای که OPENEMAIL_PROFILE نام می‌برد، و سپس نمایهٔ فعال.

نمایه یک ورود ذخیره‌شده از هر یک از دو نوع است. نخستین آن‌ها default نام دارد. با --profile در نمایه‌های بیشتری وارد شوید و میانشان جابه‌جا شوید:

openemail login --profile workopenemail profile listopenemail profile use workopenemail inbox --profile defaultOPENEMAIL_PROFILE=work openemail statusopenemail profile currentopenemail profile remove work

• —profile list هر نمایه را با نوع، فضای کاری و کاربر یا کلیدش نشان می‌دهد و نمایهٔ فعال را علامت می‌زند. خروجی JSON آن هرگز توکن یا کلیدی ندارد.
• —profile current فقط نام را روی stdout چاپ می‌کند، پس $(openemail profile current) در یک اسکریپت کار می‌کند.
• —profile remove <name> همان openemail logout --profile <name> است.
• —نام نمایه تا 64 نویسه از حروف، ارقام، نقطه، خط تیره و زیرخط است.
• —profile use نام دیگری هم دارد: profile switch. برداشتن نمایهٔ فعال یا خروج از آن هیچ نمایه‌ای را فعال باقی نمی‌گذارد، و فرمان بعدی که به ورود نیاز دارد شما را به openemail profile use <name> راهنمایی می‌کند.

نمایهٔ ذخیره‌شده API‌ای را که در آن وارد شده به خاطر می‌سپارد، و اعتبارنامه‌اش فقط به همان‌جا فرستاده می‌شود. --base-url یا OPENEMAIL_BASE_URL که مبدأ دیگری را نام ببرد، پیش از فرستادن هر چیزی فرمان را با کد خروج 2 متوقف می‌کند و می‌گوید چطور با نمایه‌ای جداگانه به آن مبدأ وارد شوید.

openemail login --profile other --base-url https://api.example.comopenemail inbox --profile other

• —کلیدی که از OPENEMAIL_API_KEY یا --api-key می‌آید نمایهٔ ذخیره‌شده نیست، پس به مبدأ --base-url یا OPENEMAIL_BASE_URL می‌رود، یا اگر هیچ‌کدام تنظیم نشده باشد به https://api.openemail.uk.
• —فرمان‌هایی که اعتبارنامه‌ای نمی‌فرستند، هر نمایه‌ای که فعال باشد، از --base-url و OPENEMAIL_BASE_URL پیروی می‌کنند: صندوق‌های یک‌بارمصرف، متدهایی که کلید نمی‌خواهند، docs و open.
• —http ساده برای هر مبدأیی جز localhost، 127.0.0.1 و ::1 با کد خروج 2 رد می‌شود: API، برنامهٔ وب، درخواست‌های ورود، توکن و ابطال، و سرور MCP. برای همهٔ موارد دیگر از https استفاده کنید.
• —مسیر درخواستی که از مبدأ API بیرون برود، مانند openemail api //example.com/x، پیش از فرستادن هر چیزی با کد خروج 2 و invalid_path متوقف می‌شود.

ورود با مرورگر از طرف شما عمل می‌کند، اما برخی کارها هرگز برای یک برنامه تأیید نمی‌شوند، هر دسترسی‌ای را که انتخاب کنید:

• —مدیریت کلیدهای API. keys:write و keys:manage هرگز اعطا نمی‌شوند، پس ساختن، چرخاندن و ابطال کلیدها به کلید API‌ای با keys:manage یا به برنامهٔ وب نیاز دارد. openemail me rotate کلیدی را که با آن فراخوانی می‌کنید می‌چرخاند، پس به کلید API نیاز دارد.
• —صورت‌حساب، و خود فضاهای کاری. طرح‌ها، فاکتورها و ساختن، جابه‌جایی یا حذف یک فضای کاری در برنامهٔ وب می‌مانند.
• —نشانی رایگان شما. یک برنامه برای یک فضای کاری تجاری تأیید می‌شود و فضای شخصی‌ای که نشانی رایگان را دارد هرگز پیشنهاد نمی‌شود، همان قاعده‌ای که API دنبال می‌کند.
• —اعضا و نقش‌ها، مگر اینکه تأیید کل فضای کاری را پوشش دهد. members:write و roles:write از تأییدی که به برخی دامنه‌ها یا نشانی‌ها محدود است حذف می‌شوند.

کلید API هم محدودیت خودش را دارد. ai compose، ai summarize و هر فرمان openemail mcp جز config از سرور MCP می‌گذرند که ورود با مرورگر می‌خواهد، پس با یک کلید با کد خروج 4 متوقف می‌شوند و دلیلش را می‌گویند.

با ورود از طریق مرورگر، چند تغییر نخست کد تأیید هویت می‌خواهند، همان‌طور که در برنامهٔ وب. CLI وقتی لازم باشد می‌پرسد: یک کد شش‌رقمی برایتان ایمیل می‌کند یا، اگر ورود دومرحله‌ای روشن باشد، کدی از برنامهٔ احراز هویت یا یکی از کدهای پشتیبانتان می‌خواهد. وقتی کد درست باشد فرمان اجرا می‌شود و تا 60 دقیقه دیگر از آن ورود پرسیده نمی‌شود. از کلید API هرگز پرسیده نمی‌شود.

$ openemail webhooks create --url https://acme.com/hooks/openemailWe emailed a code to a•••@acme.com.Verification code: 482913Verified. You will not be asked again for 60 minutes.

• —برای فرستادن دوبارهٔ ایمیل، در اعلان r را تایپ کنید. کد نادرست می‌گوید چند تلاش باقی مانده است.
• —پس از پذیرفته شدن کد، فرمان یک بار دیگر اجرا می‌شود، هرگز دو بار.
• —--yes یک حذف را تأیید می‌کند اما هرگز از کد نمی‌گذرد.
• —بدون نظارت (با --json یا --no-input، در CI یا بدون ترمینال) کسی نمی‌تواند کد را تایپ کند، پس فرمان با کد خروج 4 متوقف می‌شود و چیزی را تغییر نمی‌دهد.
• —هر کد 5 تلاش دارد، و پس از پنجمین تلاش نادرست CLI کد تازه‌ای پیشنهاد می‌کند. هر ورود می‌تواند 5 کد در ساعت و 20 کد در روز بخواهد.
• —ده کد نادرست برای یک ورود در 24 ساعت تأیید هویت آن را متوقف می‌کند. آنگاه CLI می‌گوید کی از سر گرفته می‌شود و بدون پیشنهاد کد دیگری با کد خروج 4 و step_up_paused متوقف می‌شود، و ایمیلی که آن را توضیح می‌دهد نام برنامه را می‌آورد.

پیش از اینکه یک اسکریپت یا کلاینت هوش مصنوعی کاری حساس انجام دهد، openemail verify را اجرا کنید. همین حالا کد را می‌خواهد و در 60 دقیقهٔ بعد هر فرمان آن نمایه بدون کد اجرا می‌شود، از جمله openemail mcp call و پل MCP محلی.

openemail verifyopenemail verify --statusopenemail verify --status --jsonopenemail verify --force

• —توکن دسترسیِ پشت ورود با مرورگر یک ساعت اعتبار دارد. CLI پیش از انقضا آن را تمدید و توکن تازه را ذخیره می‌کند، پس هرگز متوجه آن نمی‌شوید.
• —هر توکن تازه‌سازی فقط یک بار کار می‌کند. توکن قدیمی‌ای که بیش از 30 ثانیه پس از جایگزینی‌اش به دست CLI به کار رود، مثلاً از یک رونوشت config.json روی دستگاهی دیگر، سرور را وادار می‌کند آن ورود را به‌طور کامل ابطال کند، پس به‌جای رونوشت گرفتن از فایل، روی هر دستگاه وارد شوید.
• —تأیید تا مدتی که در صفحهٔ تأیید انتخاب کرده‌اید معتبر است. وقتی تمام شود، یا وقتی برنامه در حساب ← برنامه‌های متصل حذف شود، CLI دیگر نمی‌تواند از طرف شما عمل کند و از شما می‌خواهد دوباره openemail login را اجرا کنید.
• —openemail logout ورود با مرورگر را روی سرور ابطال می‌کند، که آن را از برنامه‌های متصل برمی‌دارد، سپس آن را روی این دستگاه فراموش می‌کند، حتی اگر به سرور دسترسی نباشد. --all از همهٔ نمایه‌ها خارج می‌شود.
• —خروج از یک کلید API فقط آن را اینجا فراموش می‌کند. کلید تا وقتی آن را با openemail keys revoke <id> یا در برنامهٔ وب ابطال نکنید کار می‌کند.

همه چیز در ~/.openemail یا در پوشه‌ای است که OPENEMAIL_CONFIG_DIR نام می‌برد. پوشه را فقط شما می‌توانید بخوانید (0700)، و هر فایل درون آن را هم (0600). هر فایل نخست در یک فایل موقت نوشته و سپس با تغییر نام در جایش گذاشته می‌شود، تا یک خرابی هرگز نیمی از فایل را به جا نگذارد، و هر تغییر زیر یک فایل قفل انجام می‌شود، تا فرمان‌هایی که کنار هم اجرا می‌شوند هرگز نمایه‌ای را از دست ندهند.