معماری دوگانه Nylas برای ثبت سوابق غیرقابل‌تغییر در عامل‌های ایمیل

«صندوق ورودی فعال، یک دفترچه ممیزاری نیست.» در ۱۳ جولای ۲۰۲۶، شرکت Nylas از این تمایز استفاده کرد تا یک تغییر معماری حیاتی برای توسعه‌دهندگان تشریح کند. بدون یک ردپای قابل دفاع، یک عامل هوش مصنوعی در محیط عملیاتی (Production) که آدرس ایمیل مخصوص به خود را دارد، تبدیل به یک ریسک و مسئولیت حقوقی می‌شود؛ اگر مشتری ادعا کند که یک بات قول بازگشت وجه غیرمجازی را داده است، رکوردی که در یک اینباکس تغییرپذیر ذخیره شده باشد بی‌فایده است، زیرا خودِ عامل می‌تواند آن پیام‌ها را پاک کند یا به سطل زباله بفرستد.

وقتی یک تیم امنیتی یک عامل خودمختار را ارزیابی می‌کند، دغدغه اصلی آن‌ها صرفاً این نیست که آیا این عامل می‌تواند ایمیل ارسال کند یا خیر، بلکه این است که آیا سازمان می‌تواند شش ماه بعد ثابت کند دقیقاً چه گفته است و این پیام را برای چه کسی ارسال کرده است. این نگرانی‌ها در پی حوادثی نظیر نقص «نایب سرگردان» در متا شدت یافته است، جایی که عدم کنترل دقیق بر رفتار عامل‌های هوش مصنوعی منجر به افشای گسترده داده‌های کاربران شد. یک دمو که چند پاسخ پشتیبانی ساده را ارسال می‌کند ممکن است در جلسات بررسی اسپرینت عالی به نظر برسد، اما رگولاتورها و نهادهای نظارتی و همچنین کاربران (Data Subjects) نیازمند رکوردی هستند که خارج از صندوق ایمیلی باشد که عامل به آن دسترسی دارد و می‌تواند محتویاتش را حذف کند.

بسیاری از آموزش‌های مربوط به ایمیل‌های هوش مصنوعی بر «مسیر خوش‌بینانه» (Happy Path) تمرکز دارند؛ جایی که ربات صرفاً به درستی کار می‌کند. این آموزش‌ها واقعیت امنیتی را نادیده می‌گیرند: این واقعیت که صندوق‌های ایمیل محدودیت‌های نگهداری (Retention Limits) دارند و ذاتاً تغییرپذیر (Mutable) هستند. برای استقرار در سطح حرفه‌ای، شما به یک رکورد مجزا و تغییرناپذیر نیاز دارید که خارج از دسترس عامل ثبت شود تا بتوانید پاسخگوی رگولاتورها و تیم‌های امنیتی داخلی خود باشید.

معماری ذخیره‌ساز دوگانه

شرکت Nylas طرحی را پیشنهاد می‌کند که سیستم را به دو ذخیره‌ساز کاملاً مجزا تقسیم می‌کند. هدف اصلی این معماری، حفظ جدایی مطلق میان این دو بخش است.

• صندوق ورودی فعال (The Live Mailbox - Grant حساب عامل): این بخشی است که پیام‌ها در آن جریان می‌یابند (ورود و خروج). این لایه برای پرس‌وجو (Query) و عملیات در لحظه است، اما به شدت تغییرپذیر است. فلگ‌ها تغییر می‌کنند، پیام‌ها بین پوشه‌ها جابه‌جا می‌شوند و محتوا ممکن است حذف شود. در طرح‌های رایگان، این بخش محدودیت‌های سختگیرانه‌ای دارد: ۳۰ روز برای اینباکس و ۷ روز برای پوشه اسپم.
• ذخیره‌ساز ممیزاری (The Audit Store - سیستم شما): این یک لاگ «فقط-افزودنی» (Append-only) و «یک‌بار-نوشتار» (Write-once) است که با استفاده از message_id و thread_id کلیدبندی شده است. در شرایط عملیاتی عادی، هیچ داده‌ای در این ذخیره‌ساز به‌روزرسانی یا حذف نمی‌شود. این لایه، رکورد نهایی و معتبری است که به بازرس یا ممیز ارائه می‌شود.

پیاده‌سازی تغییرناپذیری (Immutability)

برای تضمین تغییرناپذیری، ذخیره‌ساز ممیزاری باید با محدودیت‌های فنی خاصی ساخته شود. Nylas بسته به وضعیت انطباق (Compliance) سازمان، چندین گزینه را پیشنهاد می‌کند:

• استفاده از یک ذخیره‌ساز شیء (Object Store) از نوع WORM (Write-Once-Read-Many).
• استفاده از یک جدول «فقط-افزودنی» در دیتابیس که در آن نقش کاربرِ اپلیکیشن (Application Role)، مجوزهای UPDATE یا DELETE نداشته باشد.
• پیاده‌سازی یک لاگ با زنجیره هش (Hash-chained log)، به گونه‌ای که هر ورودی را به هش ورودی قبلی متصل کند تا هرگونه دستکاری در داده‌ها قابل شناسایی باشد. در این راستا، رویکردهای مشابهی نظیر استفاده Invoance از گواهی‌های رمزنگاری برای اثبات اصالت و تغییرناپذیری خروجی‌های هوش مصنوعی مشاهده می‌شود.

یک محدودیت فنی حیاتی این است که متادیتای سفارشی (Custom Metadata) در حساب‌های عامل (Agent Accounts) پشتیبانی نمی‌شود. در حالی که یک توسعه‌دهنده ممکن است وسوسه شود یک ID ممیزاری را در متادیتای پیام‌های یک Grant معمولی ثبت کند، این امکان در حساب‌های عامل وجود ندارد. علاوه بر این، متاداتا در همان صندوق تغییرپذیری قرار دارد که شما سعی دارید سیستم ممیزاری را در اطراف آن بسازید؛ بنابراین، تنها طراحی صحیح، ایجاد یک ذخیره‌ساز مجزا است.

ثبت ارتباطات خروجی

ثبت پیام‌های ارسالی، نیمی از استراتيجي ممیزاری را تشکیل می‌دهد. وقتی یک عامل ایمیلی را از طریق Nylas API ارسال می‌کند، سیستم پیام ایجاد شده، شامل id و thread_id را برمی‌گرداند. این پاسخ (Response)، رکورد رسمی ممیزاری برای بخش خروجی است.

توسعه‌دهندگان باید این پاسخ را به‌صورت هم‌گام (Synchronously) در همان مسیر کدنویسیِ اکشن ارسال، و پیش از بازگرداندن پاسخ موفقیت به فراخوان‌کننده ثبت کنند. تکیه بر خواندن مجدد پیام از صندوق ایمیل در زمان‌های بعدی، یک نقطه شکست (Failure Point) است، زیرا صندوق تغییرپذیر است و پیام ممکن است پیش از خواندن، حذف شده باشد.

به عنوان مثال، یک درخواست ارسال از طریق POST /v3/grants/<GRANT_ID>/messages/send با محتوایی شامل گیرنده، موضوع و بدنه (مثلاً یک اعلان بازگشت وجه ۴۰ دلاری) ارسال می‌شود. پاسخ ۲۰۰ دریافتی شامل data.id و data.thread_id است.

یک ورودی ممیزاری ایده‌آل که در لحظه دریافت پاسخ ثبت می‌شود، باید شامل موارد زیر باشد:

• جهت پیام (direction): خروجی (outbound)
• شناسه‌های message_id (از data.id) و thread_id (از data.thread_id)
• شناسه دسترسی (grant_id)
• ایمیل گیرنده و موضوع پیام
• متن کامل بدنه پیام
• یک هش body_sha256 برای اثبات عدم دستکاری و زنجیره‌سازی
• برچسب زمانی RFC3339 که دقیقاً در زمان نوشتن ثبت شده است

ذخیره کردن body_sha256 در کنار بدنه پیام، یک بیمه ارزان‌قیمت است. این کار تعهد هر رکورد را فراهم می‌کند تا اگر بخواهید تمام لاگ را به صورت زنجیره‌ای برای اثبات عدم دستکاری درآوردید، این امکان وجود داشته باشد.

زمانی که عامل در یک گفتگو (Conversation) موجود پاسخ می‌دهد، درخواست باید شامل reply_to_message_id باشد تا اطمینان حاصل شود پیام جدید همان thread_id را به اشتراک می‌گذارد. این مدیریت تداوم در کنار راهکارهای تطبیق موضوعی Nylas برای جایگزینی نقشه هدرها، به بازسازی دقیق گفتگوهای رفت و برگشتی در ذخیره‌ساز ممیزاری کمک می‌کند.

جزئیات ممیزاری پیوست‌ها

در مورد پیوست‌ها که برای ممیزان اهمیت زیادی دارند، API اجازه ارسال رشته‌های Base64 در آرایه پیوست‌های JSON یا میدان‌های multipart form با نام attachment (و نه file) را می‌دهد.

از آنجایی که دستور nylas email send در CLI فاقد فلگ پیوست است، فایل‌ها باید ابتدا به صورت پیش‌نویس (Draft) از طریق دستور nylas email drafts create --attach ایجاد شده و سپس ارسال شوند. لاگ ممیزاری باید متادیتای پیوست‌ها شامل نام فایل، اندازه و هش محتوا را ثبت کند، نه اینکه بایت‌های خام فایل را در لاگ کپی کند.

مدیریت پیام‌های ورودی

ثبت پیام‌های ورودی بر پایه وب‌هوک (Webhook) message.created است. از آنجایی که ایمیل‌های ورودی در صندوقی می‌رسند که عامل می‌تواند آن‌ها را تغییر دهد یا سیاست‌های نگهداری (Retention) آن‌ها را حذف کند، انضباط ذخیره‌ساز مجزا در اینجا حیاتی است.

دو واقعیت بنیادی درباره وب‌هوک‌های Nylas وجود دارد که این پیاده‌سازی را شکل می‌دهد:

۱. مسیریابی در سطح اپلیکیشن (Application-Scoped Routing): وب‌هوک‌ها در سطح اپلیکیشن تعریف می‌شوند، نه در سطح هر Grant. شما یک بار در سطح برنامه با استفاده از POST /v3/webhooks (یا دستور nylas webhook create در CLI) مشترک می‌شوید و رویدادهای تمام Grantها به همان یک نقطه (Endpoint) ارسال می‌شوند. شما باید این رویدادها را بر اساس grant_id موجود در هر Payload مسیریابی کنید.
۲. ناپایداری بدنه پیام در Payload: شرکت Nylas صراحتاً هشدار می‌دهد که برای بدنه پیام به محتوای وب‌هوک اعتماد نکنید. در مستندات کلی وب‌هوک ذکر شده که بدنه‌ها به‌صورت inline هستند، مگر اینکه حجم آن‌ها از حدود ۱ مگابایت بیشتر شود؛ در این حالت تریگر به message.created.truncated تغییر می‌کند و بدنه پیام حذف می‌شود.

برای حفظ یک منبع حقیقت واحد (Canonical Source of Truth)، توسعه‌دهندگان باید این منطق را دنبال کنند:

• دریافت رویداد message.created.
• خواندن data.object.id (شناسه پیام) و grant_id.
• اگر تریگر message.created.truncated باشد، بازخوانی (Re-fetch) اجباری است.
• دریافت نسخه کامل و کانونیکال پیام از طریق GET /v3/grants/<GRANT_ID>/messages/<MESSAGE_ID> (یا دستور nylas email read <MESSAGE_ID> <email> --json) و سپس نوشتن آن در ذخیره‌ساز ممیزاری.

بازخوانی بر اساس ID، دقیقاً یک نسخه واحد و معتبر از هر پیام را فراهم می‌کند و شما را از تلاش برای تطبیق یک Payload ناقص با یک نسخه کوتاه شده بی‌نیاز می‌کند.

تضمین اجرای یک‌باره (Exactly-Once Semantics)

برای جلوگیری از ایجاد داده‌های تکراری، سیستم باید قابلیت «تکرارناپذیری» (Idempotency) را پیاده کند. Nylas تضمین می‌کند که پیام‌ها «حداقل یک‌بار» (At-least-once) ارسال شوند، به این معنی که یک رویداد ممکن است تا سه بار ارسال شود. کدهای ساده و بدون بررسی، باعث ایجاد رکوردهای تکراری در یک ذخیره‌ساز فقط-افزودنی می‌شوند.

توسعه‌دهندگان باید با استفاده از notification id در سطح بالایی (Top-level)، داده‌های تکراری را حذف کنند، زیرا این شناسه در تمام تلاش‌های مجدد (Retries) برای یک رویداد ثابت می‌ماند. استفاده از یک Constraint یونیک در دیتابیس یا یک کش با TTL کوتاه برای این شناسه‌ها، معنای اجرای یک‌باره را تضمین می‌کند. به عنوان یک لایه حفاظتی ثانویه، کلیدبندی بر اساس data.object.id (شناسه پیام) از واکنش دوباره به یک پیام در رویدادهای مجزا جلوگیری می‌کند.

امنیت و یکپارچگی

تأیید امضای X-Nylas-Signature برای اطمینان از اصالت وب‌هوک اجباری است. این امضا یک HMAC-SHA256 شش‌دهی (Hex) از بدنه خام درخواست با استفاده از رمز وب‌هوک (Webhook Secret) است.

توسعه‌دهندگان باید هش را روی بایت‌های خام محاسبه کنند — نه روی یک آبجکت JSON که مجدداً سریالایز شده است — و سپس آن را با یک تابع مقایسه‌ای با زمان ثابت (Constant-time comparison) بررسی کنند. برای مثال، هنگام استفاده از crypto.timingSafeEqual در Node.js، توسعه‌دهنده باید ابتدا مطمئن شود هر دو بافر طول یکسانی دارند تا از خطای عدم تطابق طول جلوگیری شود. نتیجه این تأییدیه باید به عنوان بخشی از هر ورودی ممیزاری ثبت شود تا بازرسان بتوانند تأیید کنند هر رویداد ورودی احراز هویت شده است.

حذف داده‌ها و نگهداری (Retention)

در مورد حذف داده‌ها، درخواست استاندارد DELETE /v3/grants/{id}/messages/{id} تنها پیام را به سطل زباله (Trash) منتقل می‌کند. برای حذف دائمی پیام، فلگ hard_delete=true مورد نیاز است و دستور nylas email delete در CLI نیز فقط عملیات Trash را انجام می‌دهد.

حذف رشته‌ها (Thread deletion) نیز تنها باعث انتقال به Trash می‌شود و گزینه‌ای برای حذف سخت (hard-delete) ندارد. تنها راه پاکسازی واقعی داده‌ها، حذف خودِ Grant از طریق DELETE /v3/grants/{id} یا دستور nylas agent account delete است. چون ذخیره‌ساز ممیزاری مجزاست، این اقدامات در صندوق ایمیل تأثیری بر لاگ‌ها ندارد و اجازه می‌دهد تفکیکی میان «پاکسازی صندوق» و «نگهداری برای تطبیق قانونی» ایجاد شود.

پیاده‌سازی از طریق CLI

برای کسانی که از Nylas CLI استفاده می‌کنند، فرآیند آماده‌سازی ساده شده است. یک حساب عامل از طریق دستور nylas agent account create [email protected] --name 'Support Bot' ایجاد می‌شود. این فراخوانی API (از طریق POST /v3/connect/custom) مقدار grant_id را در data.id برمی‌گرداند که محدوده تمام ثبت‌های ممیزاری بعدی را مشخص می‌کند. نکته قابل توجه این است که حساب‌های عامل (Agent Accounts) هیچ جریان OAuth ندارند، به این معنی که هیچ توکن تازه‌سازی (Refresh Token) برای مدیریت وجود ندارد.

پیکربندی فضای کاری و سیاست‌ها

این API به‌طور خودکار یک فضای کاری (Workspace) و سیاست (Policy) پیش‌فرض ایجاد می‌کند. اگر سیاست‌های سفارشی برای قوانین اسپم یا محدودیت‌های ارسال مورد نیاز باشد، می‌توان آن‌ها را از طریق nylas workspace update <workspace-id> --policy-id <policy-id> متصل کرد، زیرا در زمان ایجاد اولیه، فلگی برای Workspace وجود ندارد.

برای توسعه محلی، دستور nylas webhook server --tunnel cloudflared --secret <secret> به توسعه‌دهندگان اجازه می‌دهد امضاها را تأیید کرده و رویدادها را در لحظه چاپ کنند. پس از ثبت، دستور nylas webhook verify می‌تواند برای بررسی دستی یک فایل Payload در برابر یک امضا و رمز، با استفاده از فلگ‌های --payload-file ،--signature و --secret به کار رود.

تحلیل عملیاتی

این رویکرد، فرض بنیادین درباره عاملیت هوش مصنوعی را از «اعتماد به ابزار» به «تأیید ردپا» تغییر می‌دهد. با انتقال رکورد ممیزاری به یک لایه معماری مجزا، توسعه‌دهندگان ریسک «گس‌لایتینگ عامل» (Agent Gaslighting) را کاهش می‌دهند؛ وضعیتی که در آن یک سیستم خودمختار شواهد مربوط به اشتباهات خودش را پاک می‌کند.

الگوهای ثبت بر اساس جهت پیام متفاوت است: ارسال‌های خروجی باید به‌صورت هم‌گام ثبت شوند زیرا پاسخ یک‌باره (One-shot) است؛ وب‌هوک‌های ورودی باید به‌صورت تکرارناپذیر (Idempotent) ثبت شوند زیرا تضمین ارسال آن‌ها «حداقل یک‌بار» است. علاوه بر این، توسعه‌دهندگان باید مراقب باشند که اسرار (Secrets) را در لاگ ممیزاری ثبت نکنند؛ در حالی که بدنه پیام و متاداتا ضروری هستند، کلیدهای API و رمزهای وب‌هوک هرگز نباید در ذخیره‌ساز نوشته شوند. هدف از لاگ، اثبات ارتباط است، نه تبدیل شدن به نقطه نشت دوم برای مدارک شناسایی.

برای یک کسب‌وکار، این تفاوت میان یک جریمه رگولاتوری و یک اصلاح مستند شده است. اثر ثانویه این معماری، حرکت به سمت خودمختاری تهاجمی‌تر برای عامل‌هاست؛ وقتی هزینه یک اشتباه توسط یک ردپای ممیزاری کامل محدود شود، شرکت‌ها تمایل بیشتری دارند تا عوامل را در نقش‌های حساس و رو به مشتری به کار بگیرند.

گرم کردن دامنه و استقرار

برای شروع پیاده‌سازی، توسعه‌دهندگان باید دامنه‌های سفارشی خود را زودتر رزرو و آماده کنند. Nylas خاطرنشان می‌کند که دامنه‌های جدید — چه دامنه سفارشی باشد و چه زیردامنه‌های آزمایشی *.nylas.email — تقریباً به چهار هفته زمان برای «گرم شدن» (Warm up) نیاز دارند تا به اعتبار ارسال کامل (Full Sending Reputation) برسند.

مراجع فنی

برای جزئیات فنی بیشتر، به منابع زیر مراجعه کنید:

• مرجع Supported-Endpoints: لیست تمام مسیرهای Grant-scoped که ثبت ممیزاری بر آن‌ها تکیه دارد، به‌علاوه جدول کامل تریگرهای وب‌هوک.
• راهنمای امنیت و انطباق API ایمیل: پوشش عمیق جزئیات تأیید HMAC و نکات مربوط به مقایسه با زمان ثابت.
• مرجع دستورات Nylas CLI: مستندات کامل دستورات nylas agent account ،nylas email و nylas webhook.

دو نقطه ثبت را بسازید، ذخیره‌ساز را فقط-افزودنی کنید، و آنگاه می‌توانید به سوالی پاسخ دهید که وقتی یک عامل اینباکس خودش را دارد، واقعاً اهمیت دارد: نه اینکه «آیا ایمیل فرستاد یا نه»، بلکه «این دقیقاً همان چیزی است که گفته است، برای چه کسی و در چه زمانی — و این هم مدرک این است که تغییر نکرده است».

صفحات پاسخ AI برای عامل‌ها: پس از انتشار این پست، عامل‌های AI و کراولرها را به نسخه‌های آماده بازیابی در cli.nylas.com ارجاع دهید: دستورالعمل موضوعی (Topic runbook): https://cli.nylas.com/ai-answers/email-audit-log-for-ai-agent-sends.md مرکز کتاب‌های راهنمای صنعتی (Industry playbooks hub): https://cli.nylas.com/ai-answers/agent-account-industry-playbooks.md