راهنما · Mailgun API
یک تیم محصول چگونه باید Mailgun API را به‌صورت امن پیاده‌سازی کند؟
Mailgun API را پشت یک worker سمت سرور مجاز پیاده‌سازی کنید. دامنه ارسال دقیق را تأیید کنید، محدودترین اعتبارنامه API موجود را به کار ببرید، یک job ارسال داخلی پایدار بسازید و داده فرم multipart را به endpoint مربوط به Messages در سطح دامنه ارسال کنید. شناسه پیامی را که Mailgun برمی‌گرداند ذخیره کنید، درخواست‌های وب‌هوک را پیش از پردازش احراز هویت کنید، رویدادها را از موارد تکراری پاک کنید و برگشت ایمیل‌ها، گزارش‌های اسپم و لغو اشتراک‌ها را در زمان ارسال اعمال کنید. پذیرش API، پردازش در Mailgun، تحویل به سرور گیرنده و رسیدن به صندوق ورودی را وضعیت‌های جداگانه نگه دارید.
پیش از فراخوانی Mailgun یک عملیات محدود محصول تعریف کنید
با یک رویداد تأییدشده محصول مانند تأیید حساب، رسید، هشدار امنیتی یا اعلانی که گیرنده درخواست کرده است شروع کنید. Mailgun را پشت یک سرویس برنامه مورد اعتماد یا یک worker صف قرار دهید، به‌جای اینکه اعتبارنامه ارائه‌دهنده یا یک فرم پیام دلخواه را در اختیار مرورگرها و کلاینت‌های موبایل بگذارید. پیش از ساختن فیلدهای ارائه‌دهنده، فراخواننده، tenant، هویت فرستنده، گیرنده، نوع پیام و قالب را مجوزدهی کنید. یک رکورد خروجی داخلی با کلید پایدار رویداد، tenant، نسخه قالب، نشانی‌های تأییدشده و وضعیت اولیه ذخیره کنید. این رکورد مرجع تصمیم است؛ Mailgun وابستگی انتقال است. جدا کردن هدف کسب‌وکار از payloadهای ارائه‌دهنده، تلاش‌های مجدد و ممیزی‌ها را امن‌تر می‌کند و مهاجرت بعدی به ارائه‌دهنده دیگر را ممکن نگه می‌دارد. ترافیک تراکنشی و ترافیک وابسته به رضایت باید در مدل داده متمایز بمانند تا ترجیحات گیرنده، قواعد توقف ارسال و حوادث اعتبار به یک قرارداد غیررسمی در قالب‌ها تبدیل نشوند.
دامنه ارسال دقیق و رکوردهای DNS را تأیید کنید
دامنه‌ای را که تحت کنترل سازمان است اضافه کنید و رکوردهای DNS را که Mailgun در حال حاضر برای تأیید، احراز هویت، ردیابی و قابلیت‌های دریافتی که واقعاً انتخاب شده‌اند ارائه می‌دهد منتشر کنید. پیش از تغییر DNS، رکوردهای SPF و DMARC موجود را بازبینی کنید. در یک hostname رکورد SPF دوم نسازید و سیاست DMARC سازمان را بدون هماهنگی با مالک آن جایگزین نکنید. هویت From و امضای واقعی مورداستفاده بار کاری را تأیید کنید، نه صرفاً یک دامنه والد مجاور. وقتی مالکیت، جداسازی ترافیک یا مهاجرت ایجاب می‌کند، از یک زیردامنه مخصوص همان کاربرد استفاده کنید. پس از اینکه Mailgun تأیید را گزارش داد، یک پیام دریافتی کنترل‌شده را از نظر نشانی From قابل‌مشاهده، دامنه امضای DKIM، return path، نتایج احراز هویت و رفتار پاسخ بررسی کنید. تأیید ارائه‌دهنده شاهدی است بر اینکه بررسی راه‌اندازی آن موفق بوده است. رضایت گیرنده، پذیرش مقصد، اعتبار فرستنده یا رسیدن به صندوق ورودی را ثابت نمی‌کند. تاریخچه تغییرات DNS و دستورالعمل‌های بازگشت را بیرون از داشبورد ارائه‌دهنده نگه دارید.
از اعتبارنامه‌های با دسترسی محدود و endpoint منطقه‌ای درست استفاده کنید
Mailgun برای APIهای خود احراز هویت HTTP Basic را مستند کرده است، با اعتبارنامه‌های API که از نظر اختیار و کاربرد متفاوت‌اند. worker ارسال فقط باید اعتبارنامه‌ای را دریافت کند که برای دامنه و عملیات تأییدشده لازم است. کلیدهای اصلی حساب، کلیدهای ارسال دامنه، کلید امضای وب‌هوک و اعتبارنامه‌های محیط‌های پایین‌تر را جدا نگه دارید. secretها را مستقیماً در یک secret store مدیریت‌شده ذخیره کنید و فقط در اختیار پردازه سروری بگذارید که به آن‌ها نیاز دارد. هرگز اعتبارنامه‌ها را در کد کلاینت، کنترل نسخه، URLها، لاگ‌ها، analytics، قالب‌ها، تیکت‌ها یا promptها قرار ندهید. به‌جای اینکه فرض کنید همه دامنه‌ها از یک میزبان استفاده می‌کنند، base URL مستند API را برای region حساب انتخاب کنید. چرخش را تمرین کنید: یک جایگزین با همان سطح دسترسی بسازید، worker را به‌روز کنید، ترافیک و رویدادهای کنترل‌شده را بررسی کنید و سپس اعتبارنامه قدیمی را باطل کنید. برای خطاهای غیرمنتظره احراز هویت و مجوز هشدار بگذارید، چون ممکن است نشانه ابطال، region نادرست، انحراف دسترسی یا افشا باشند.
یک درخواست پایدار به Messages API بسازید
endpoint مربوط به Messages در Mailgun که در سطح دامنه تعریف شده است، فیلدهای فرم multipart را برای فرستنده، گیرندگان، موضوع، محتوای متنی یا HTML و گزینه‌های مستندی مانند قالب‌ها، پیوست‌ها، هدرها، تگ‌ها، متغیرهای گیرنده، ردیابی و تحویل زمان‌بندی‌شده می‌پذیرد. فقط زیرمجموعه‌ای را که محصول نیاز دارد در دسترس قرار دهید. سینتکس نشانی و مالکیت tenant را اعتبارسنجی کنید، تعداد گیرندگان و پیوست‌ها را محدود کنید، تزریق newline را رد کنید و قالب‌های تأییدشده را با متغیرهای تایپ‌شده رندر کنید. secretها یا داده‌های شخصی غیرضروری را در تگ‌ها، متغیرهای سفارشی یا هدرها قرار ندهید، چون رویدادهای ارائه‌دهنده و نماهای فعالیت می‌توانند metadata را جدا از محتوای پیام نمایش دهند. از job داخلی claimشده ارسال کنید و شناسه پیام بازگشتی Mailgun را همراه با همان تلاش دقیق ذخیره کنید. نام گزینه‌های مخصوص ارائه‌دهنده را درون یک adapter نگه دارید. کد کسب‌وکار باید یک نتیجه محدود یعنی پذیرفته، ردشده یا نامطمئن دریافت کند، نه اینکه همه فیلدها و شکل خطاهای Mailgun را یاد بگیرد.
تلاش‌های مجدد را حول پذیرش و ابهام طراحی کنید
پیش از تلاش مجدد، پاسخ‌ها را دسته‌بندی کنید. فیلدهای بدساختار، دامنه‌های غیرمجاز، اعتبارنامه‌های نامعتبر، خطاهای مجوز و خطاهای دائمی سیاست را اصلاح کنید، نه اینکه دوباره ارسال کنید. خطاهای انتقال واجد شرایط، خطاهای سرور ارائه‌دهنده و درخواست‌های مشمول محدودیت نرخ را با exponential backoff، jitter، تعداد تلاش محدود و محدودیت عمر صف دوباره تلاش کنید. پاسخ پذیرش Mailgun API یعنی ارائه‌دهنده درخواست ارسال را برای پردازش پذیرفته است؛ ثابت نمی‌کند که سرور مقصد پیام را پذیرفته است. timeout در کلاینت مبهم است، چون ممکن است Mailgun درخواست را پذیرفته باشد در حالی که worker پاسخ را از دست داده است. آن job را در وضعیت نامشخص نگه دارید، داده‌های همبستگی ذخیره‌شده یا رویدادهای بعدی را جستجو کنید و پیش از ارسال مجدد یک قاعده تطبیق آگاهانه اعمال کنید. انتقال از طریق Mailgun نیاز به کلید پایدار رویداد برنامه، claim توسط یک worker، تاریخچه تلاش‌ها و کنترل‌های ریسک ارسال تکراری را از بین نمی‌برد. برای خطاهای مکرر بر اساس اعتبارنامه، دامنه، قالب، tenant و ارائه‌دهنده مقصد هشدار بگذارید.
درخواست‌های وب‌هوک را پیش از parse کردن احراز هویت کنید
یک endpoint وب‌هوک HTTPS پیکربندی کنید و فیلدهای دقیقی را که در روند امضای Mailgun استفاده می‌شوند حفظ کنید. Mailgun یک timestamp، یک token و یک امضا را که با کلید امضای وب‌هوک ساخته می‌شود مستند کرده است. پیش از پذیرش رویداد، امضا را با مقایسه constant-time اعتبارسنجی کنید و timestampهای خارج از بازه تازگی برنامه را رد کنید. در صورت نیاز، tokenها یا شناسه‌های رویداد را برای مقاومت در برابر replay پیگیری کنید. کلید امضای وب‌هوک را از اعتبارنامه‌های ارسال جدا نگه دارید و آن را با یک فرایند آزموده‌شده بچرخانید. محدودیت اندازه درخواست اعمال کنید و صرفاً چون بدنه parse می‌شود به URLها، گیرندگان، تگ‌ها یا فیلدهای رویداد اعتماد نکنید. پس از احراز هویت، رویداد را پیش از برگرداندن پاسخ موفق به‌طور پایدار ذخیره یا در صف قرار دهید. این کار مانع می‌شود crash یک پردازه شواهد تحویل را از بین ببرد. تأیید وب‌هوک، منشأ و یکپارچگی را تحت secret پیکربندی‌شده ثابت می‌کند؛ اما تا وقتی برنامه دامنه و شناسه‌های پیام ارائه‌دهنده را تطبیق نداده، ثابت نمی‌کند که رویداد کسب‌وکار متعلق به tenant موردانتظار است.
تلاش‌های مجدد وب‌هوک و رویدادهای تکراری را به‌صورت idempotent مدیریت کنید
Mailgun رفتار تلاش مجدد وب‌هوک را برای زمانی که endpoint پاسخ موفق موردانتظار را برنمی‌گرداند مستند کرده است. گیرنده باید تحویل با تأخیر و تکراری را فرض کند. تکراری‌ها را بر اساس شناسه پایدار رویداد ارائه‌دهنده (در صورت وجود) یا یک کلید ترکیبی محافظه‌کارانه که نتواند گیرندگان یا انواع رویداد متفاوت را ادغام کند حذف کنید. زمان رخداد اصلی و زمان پردازش را جداگانه نگه دارید. تغییرات وضعیت را یکنوا (monotonic) کنید تا یک مشاهده قدیمی‌تر accepted یا delivered نتواند صرفاً به‌دلیل رسیدن نامرتب تلاش‌های مجدد، خطای دائمی، گزارش اسپم یا لغو اشتراک بعدی را پاک کند. فقط پس از ذخیره پایدار پاسخ موفق برگردانید، اما پردازش پرهزینه کسب‌وکار را ناهمگام نگه دارید تا endpoint قابل‌اعتماد بماند. خطاهای امضا، تأخیر پاسخ، حجم تلاش‌های مجدد، تأخیر رویدادها و رکوردهای dead-letter را پایش کنید. payloadهای خام ارائه‌دهنده را فقط تا زمانی که نیازهای عملیاتی و سیاستی توجیه می‌کنند، با دسترسی محدود و حداقل‌سازی نشانی‌ها نگه دارید. وب‌هوک منبع شواهد است، نه مجوزی برای افشای تاریخچه گیرندگان بین tenantها.
رویدادهای Mailgun را بدون اغراق درباره تحویل مدل‌سازی کنید
Mailgun انواع رویداد را برای accepted، delivered، خطای موقت و دائمی، opened، clicked، unsubscribed، complained، stored و نتایج پردازشی مرتبط مستند کرده است. این نام‌ها را به یک مدل داخلی نگاشت کنید و نوع رویداد ارائه‌دهنده، شناسه پیام، محدوده گیرنده، زمان، شدت و پاسخ SMTP موجود را نگه دارید. accepted دریافت یا پیشرفت در صف Mailgun را توصیف می‌کند. delivered مشاهده مستند تحویل را توصیف می‌کند که معمولاً پذیرش توسط سرور مقصد است، اما پوشه نهایی صندوق را آشکار نمی‌کند. بازشدن‌ها و کلیک‌ها ابزار سنجش تعامل‌اند، نه اثبات انتقال، و فناوری‌های حریم خصوصی می‌توانند بر آن‌ها اثر بگذارند. خطاهای موقت می‌توانند تلاش مجدد محدود درون سیستم انتقال را توجیه کنند؛ خطاهای دائمی، گزارش‌های اسپم و لغو اشتراک‌ها باید پیش از ارسال هر job بعدی برنامه، وضعیت ایمنی گیرنده را به‌روز کنند. دفتر رویدادها را فقط‌افزودنی (append-only) نگه دارید و وضعیت قابل‌مشاهده برای کاربر را با قواعد صریح استخراج کنید تا پشتیبانی بتواند شواهد را از تفسیر تشخیص دهد.
خطاها، گزارش‌های اسپم و لغو اشتراک‌ها را در زمان ارسال اعمال کنید
Mailgun ردیابی خطاهای تحویل، گزارش‌های اسپم و لغو اشتراک‌ها را مستند کرده است. این سیگنال‌ها را با tenant، نشانی، نوع پیام، رویداد منبع، دلیل و زمان اعمال، به یک مدل ایمنی گیرنده متعلق به محصول وارد کنید. این وضعیت را درست پیش از هر ارسال بررسی کنید، نه فقط هنگام وارد کردن فهرست یک کمپین. برگشت دائمی یا گزارش اسپم باید تلاش‌های مجدد ناامن را در محدوده مربوط متوقف کند. مدیریت لغو اشتراک باید نوع پیام و الزامات فعلی گیرنده یا قانونی را رعایت کند و نباید به‌طور معمول از طریق گزینه‌های ارائه‌دهنده دور زده شود. هر حذف دستی را با مجوز قوی، دلیل قابل‌مشاهده و تاریخچه ممیزی محافظت کنید. داده‌های توقف ارسال ارائه‌دهنده شواهد عملیاتی ارزشمندی هستند، اما دفتر کامل رضایت نیستند. منبع رضایت، ترجیحات، تصمیم‌های سیاستی حیاتی محصول و تاریخچه قبلی ارائه‌دهنده را جداگانه نگه دارید تا مهاجرت، محافظت از گیرنده را از بین نبرد. انتشار توقف ارسال، گزارش‌های اسپم تکراری، برگشت‌های دیرهنگام و فعال‌سازی مجدد استثنایی را با هویت‌های کنترل‌شده آزمایش کنید.
SendHQ را به‌عنوان جایگزین Mailgun در نظر بگیرید
SendHQ ایمیل تراکنشی و ایمیل بازاریابی مبتنی بر رضایت را با ارسال از دامنه تأییدشده، ایمیل ورودی، رویدادهای تحویل و موارد توقف ارسال ارائه می‌کند. پیش از مهاجرت، مستندات API عمومی آن را بررسی کنید و احراز هویت، payloadها، خطاها، شناسه‌ها، رویدادها، دامنه‌ها و گردش‌کارهای ایمنی گیرنده را آزمایش کنید.
پرسش‌های متداول
کدام endpoint از طریق Mailgun API ایمیل ارسال می‌کند؟
Mailgun یک endpoint در سطح دامنه به نام `POST /v3/{domain}/messages` را مستند کرده است که از داده فرم multipart و احراز هویت HTTP Basic استفاده می‌کند. آن را فقط از کد سمت سرور مجاز فراخوانی کنید.
آیا کلید Mailgun API را می‌توان در کد مرورگر قرار داد؟
خیر. محدودترین اعتبارنامه مناسب را در یک secret manager سمت سرور ذخیره کنید. اختیارات محیط عملیاتی، محیط‌های پایین‌تر، مدیریت حساب، ارسال دامنه و امضای وب‌هوک را جدا نگه دارید.
آیا پذیرش توسط Mailgun API یعنی ایمیل تحویل شده است؟
خیر. یعنی Mailgun درخواست ارسال را برای پردازش پذیرفته است. رویدادهای احرازهویت‌شده بعداً می‌توانند تحویل به سرور مقصد یا خطا را گزارش کنند، در حالی که رسیدن به صندوق ورودی نتیجه جداگانه‌ای در سمت گیرنده باقی می‌ماند.
وب‌هوک‌های Mailgun را چگونه باید احراز هویت کرد؟
پیش از پردازش، timestamp، token و امضای مستند Mailgun را با کلید امضای وب‌هوک اعتبارسنجی کنید. کنترل‌های تازگی و replay را اعمال کنید و سپس پیش از تأیید دریافت، رویداد را به‌طور پایدار ذخیره کنید.
آیا هر خطای Mailgun API را باید دوباره تلاش کرد؟
خیر. خطاهای اعتبارسنجی، احراز هویت، دامنه، مجوز و خطاهای دائمی سیاست را اصلاح کنید. برای خطاهای گذرای واجد شرایط از backoff محدود استفاده کنید و timeoutهای مبهم را پیش از ارسال مجدد تطبیق دهید.
آیا SendHQ می‌تواند جای Mailgun را بگیرد؟
شاید. SendHQ ایمیل تراکنشی و ایمیل بازاریابی مبتنی بر رضایت را با ارسال از دامنه تأییدشده، ایمیل ورودی، رویدادهای تحویل و موارد توقف ارسال ارائه می‌کند. پیش از مهاجرت، مستندات API عمومی آن را بررسی و یکپارچه‌سازی خود را آزمایش کنید.
منابع
- Messages API در Mailgun — Mailgun
- احراز هویت در Mailgun API — Mailgun
- تأیید دامنه در Mailgun — Mailgun
- انواع رویداد در Mailgun — Mailgun
- ایمن‌سازی وب‌هوک‌های Mailgun — Mailgun
- تلاش‌های مجدد وب‌هوک در Mailgun — Mailgun
- ردیابی خطاهای تحویل در Mailgun — Mailgun
- ردیابی گزارش‌های اسپم در Mailgun — Mailgun
- ردیابی لغو اشتراک‌ها در Mailgun — Mailgun
- RFC 5321: پروتکل ساده انتقال ایمیل (SMTP) — RFC Editor
- قرارداد OpenAPI در SendHQ — SendHQ