راهنما · Postmark API
یک تیم محصول چگونه باید Postmark API را به‌طور امن پیاده‌سازی کند؟
Postmark API را پشت یک worker مجاز سمت سرور پیاده‌سازی کنید. دامنه ارسال یا sender signature را تأیید کنید، هر محیط و بار کاری را در server و message stream مناسب در Postmark جدا کنید، server token را در یک مدیر اسرار ذخیره کنید و پیش از فراخوانی POST /email یک job ارسال پایدار در اپلیکیشن ثبت کنید. فقط فیلدهای تأییدشده را ارسال کنید، MessageID و ErrorCode دقیق Postmark را نگه دارید و پذیرش توسط API را شاهد پردازش بدانید، نه تحویل. وب‌هوک‌های تحویل و برگشت را ایمن کنید و تکرارهایشان را حذف کنید، پیش از هر ارسال فهرست توقف ارسال گیرندگان را اعمال کنید، timeoutهای مبهم را تطبیق دهید و پیش از محیط عملیاتی چرخش توکن، خطاهای جزئی، تلاش‌های مجدد و خروجی گرفتن را آزمایش کنید.
پیش از Postmark مرز اپلیکیشن را تعریف کنید
از یک رویداد کسب‌وکار مجاز مانند رسید، تأیید، هشدار درخواستی یا اطلاعیه امنیتی شروع کنید. یک job خروجی پایدار با کلید رویداد پایدار، tenant، دسته پیام، نسخه قالب، فرستنده و گیرندگان تأییدشده، مبنای رضایت یا ضرورت، تصمیم فعلی توقف ارسال و وضعیت اولیه ثبت کنید. ورودی مرورگر، موبایل، قالب و کاربر نباید server token در Postmark، هویت From دلخواه، message stream، وب‌هوک، گیرنده نامحدود یا فراداده ارائهدهنده را انتخاب کند. همه فراخوانی‌های ارائهدهنده را پشت یک adapter سمت سرور قرار دهید. ترافیک تراکنشی را از ترافیک broadcast یا بازاریابی مطابق مدل رضایت و اعتبار محصول جدا کنید. API در Postmark یک پیام را انتقال میدهد؛ مجوز tenant، رضایت گیرنده یا idempotency کسب‌وکار را برقرار نمی‌کند. job داخلی را فقط یک بار برداشت کنید، هر تلاش ارائهدهنده را ثبت کنید و شناسه‌های ارائهدهنده را به‌عنوان شاهد مرتبط با رویداد اپلیکیشن نگه دارید، نه اینکه آن‌ها را تنها مرجع ثبت بدانید.
از server tokenها با دامنه عملیاتی محدود استفاده کنید
API ایمیل Postmark هدر X-Postmark-Server-Token را برای دسترسی API در سطح سرور مستند کرده است. هر توکن را در یک سرویس مدیریت اسرار ذخیره کنید و فقط در اختیار workerی قرار دهید که به آن server و محیط نیاز دارد. هرگز توکن‌ها را در کد کلاینت، کنترل نسخه، URLها، لاگ‌ها، analytics، قالبها، اسکرین‌شات‌ها، تیکت‌ها، promptها یا داده‌های آزمایشی قرار ندهید. محیط عملیاتی را از توسعه و محصولات نامرتبط جدا کنید تا ابطال یا سوءاستفاده اثر محدودی داشته باشد. چرخش را تمرین کنید: از طریق مدیریت مجاز یک جایگزین فراهم کنید، worker را به‌روز کنید، پیام‌های کنترل‌شده بفرستید، شواهد API و رویدادها را تأیید کنید و سپس توکن قدیمی را ابطال کنید. خطاهای غیرمنتظره احراز هویت را شرط توقف بدانید، نه دعوتی برای امتحان سریع اعتبارنامه‌ها. مدیریت داشبورد را با احراز هویت قوی و نقش‌ها محدود کنید. server token عملیات Postmark API را برای server خودش مجاز میکند؛ اپلیکیشن همچنان باید tenant، فرستنده، گیرنده، قالب و دسته پیام را مجاز کند.
هویت دقیق فرستنده را تأیید کنید
از یک sender signature یا دامنه تأییدشده تحت کنترل سازمان استفاده کنید و نشانی دقیق From را که هر stream استفاده میکند تأیید کنید. دامنه From قابل‌مشاهده، return path در SMTP، دامنه d= و selector در DKIM، نشانی پاسخ و message stream ارسال را روی نمونه‌های خام دریافت‌شده فهرست کنید. پس از بازبینی مالکیت فعلی SPF، DKIM و DMARC، فقط رکوردهای DNSی را منتشر کنید که Postmark در حال حاضر برای تنظیمات انتخاب‌شده لازم می‌داند. مقادیر قبلی و دستورالعمل بازگشت را نگه دارید. تأیید ارائهدهنده شاهدی است بر اینکه بررسی پیکربندی آن موفق بوده است؛ ثابت نمی‌کند همه مسیرهای اپلیکیشن از آن هویت استفاده می‌کنند، DMARC هم‌راستاست، گیرندگان رضایت داده‌اند یا پیام‌ها به صندوق ورودی می‌رسند. مجوز فرستنده مخصوص هر tenant را در اپلیکیشن نگه دارید و مقادیر From cross-tenant را مسدود کنید. زیردامنه‌ها، پاسخ‌ها، برگشت‌ها، محیط‌های غیرعملیاتی و مسیرهای قالب را آزمایش کنید. سیاست SPF یا DMARC سازمان را صرفاً برای سبز شدن یک نشانگر داشبورد تضعیف نکنید.
یک درخواست صریح POST email بسازید
Postmark درخواست POST /email را با فیلدهای JSON برای فرستنده، گیرندگان، موضوع، بدنه متنی یا HTML، ReplyTo، هدرها، برچسب‌ها یا فراداده، message stream، پیوست‌ها و گزینه‌های ردیابی مستند کرده است. فقط فیلدهایی را که محصول لازم دارد در معرض قرار دهید. نشانی‌ها را اعتبارسنجی و نرمال‌سازی کنید، تعداد گیرندگان و پیوست‌ها را محدود کنید، تزریق هدر را رد کنید، مقادیر قالب را بر اساس زمینه خروجی escape کنید و متن و HTML را از یک نسخه تأییدشده تولید کنید. اسرار یا داده‌های شخصی غیرضروری را در برچسب‌ها، فراداده، هدرها، موضوع‌ها یا نام پیوست‌ها قرار ندهید، چون ممکن است در فعالیت و رویدادهای ارائهدهنده ظاهر شوند. MessageStream را از پیکربندی قابل‌اعتماد انتخاب کنید، هرگز از ورودی دلخواه درخواست. payload ارائهدهنده را در یک adapter نگه دارید تا کد کسب‌وکار به همه فیلدهای Postmark وابسته نباشد. وقتی نیازهای ممیزی توجیه میکند، به‌جای لاگ کردن کل بدنه پیام، نسخه محتوا یا یک hash حافظ حریم خصوصی را ذخیره کنید.
پاسخ فوری را محدود تفسیر کنید
endpoint ارسال تک‌ایمیل در Postmark فیلدهای پاسخ از جمله ErrorCode، Message، MessageID، SubmittedAt و اطلاعات گیرنده را مستند کرده است. وضعیت دقیق HTTP و پاسخ ساخت‌یافته ارائهدهنده را همراه با تلاش اپلیکیشن ذخیره کنید. پاسخ موفق و MessageID نشان می‌دهند که Postmark درخواست API را طبق معنای مستند خود پذیرفته است؛ نشان نمی‌دهند که سرور مقصد پیام را پذیرفته یا پیام به صندوق ورودی رسیده است. پیش از تلاش مجدد، خطاهای اعتبارسنجی، sender signature، احراز هویت، payload بدشکل، سهمیه و سیاست را دسته‌بندی کنید. timeout درخواست مبهم است، زیرا ممکن است Postmark عملیات را پذیرفته باشد در حالی که کلاینت پاسخ را از دست داده است. آن تلاش را در وضعیت نامعلوم نگه دارید، با داده‌های همبستگی امن در فعالیت ارائهدهنده یا رویدادهای بعدی جست‌وجو کنید و پیش از ارسال مجدد، قاعده تطبیق مخصوص دسته پیام را اعمال کنید. هرگز تحویل دقیقاً یک‌باره را وعده ندهید و صرفاً به دلیل شکست یک درخواست HTTP رویداد منطقی جدیدی نسازید.
تلاش‌های مجدد را بر اساس شواهد ارائهدهنده و انتقال طراحی کنید
فقط خطاهای شبکه واجد شرایط، محدودیت‌های نرخ و خطاهای سرور ارائهدهنده را با exponential backoff، jitter، تعداد تلاش محدود و محدودیت سن صف دوباره امتحان کنید. خطاهای دائمی درخواست، فرستنده، گیرنده، توکن، قالب و سیاست را اصلاح کنید، نه اینکه دوباره اجرا کنید. همان کلید رویداد اپلیکیشن را نگه دارید و تلاش‌های مرتبط را ثبت کنید. درست پیش از هر تلاش مجدد، فهرست توقف ارسال و مجوز را دوباره بررسی کنید، زیرا وضعیت گیرنده یا کسب‌وکار ممکن است در صف تغییر کند. هم‌زمانی و نرخ را بر اساس server، tenant، message stream، دامنه فرستنده و گروه مقصد محدود کنید تا یک قطعی نتواند کل ظرفیت را در انحصار بگیرد. در صورت منقضی شدن رویداد، ابطال هویت فرستنده، گزارش اسپم، لغو اشتراک، خطای دائمی گیرنده یا توقف ناشی از رخداد، متوقف شوید. سن تلاش‌های مجدد، نتایج نامعلوم، دسته‌های پاسخ، خطاهای توکن و تأخیر ارائهدهنده را پایش کنید. اگر Postmark پس از پذیرش خودش تلاش‌های مجدد SMTP پایین‌دستی را انجام میدهد، یک حلقه تکراری تهاجمی در اپلیکیشن روی آن رفتار انتقال نسازید.
وب‌هوک‌های تحویل و برگشت را ایمن کنید
فقط انواع وب‌هوک Postmark را که اپلیکیشن لازم دارد پیکربندی کنید و از HTTPS استفاده کنید. کنترل‌های امنیتی مستند فعلی برای وب‌هوک را اعمال کنید، endpoint را به server یا stream موردانتظار محدود کنید، محدودیت‌های اندازه درخواست و content-type را اعمال کنید و هرگز به شناسه‌های پیام، گیرندگان، برچسب‌ها، فراداده یا اطلاعات عیب‌یابی فقط به این دلیل که JSON درست parse می‌شود اعتماد نکنید. رویداد احراز هویت‌شده یا به‌طور امن پذیرفته‌شده را پیش از برگرداندن پاسخ موفق ذخیره یا در صف قرار دهید. تکرارها را بر اساس شناسه پایدار رویداد ارائهدهنده، در صورت وجود، یا یک ترکیب محافظه‌کارانه که نتواند گیرندگان، انواع رویداد یا تلاش‌ها را ادغام کند حذف کنید. زمان وقوع و زمان پردازش را جدا نگه دارید. انتظار تأخیر، تلاش مجدد، تکرار و تحویل خارج از ترتیب را داشته باشید. پیش از تغییر وضعیت، MessageID و فراداده قابل‌اعتماد را با tenant و job داخلی مرتبط کنید. اعتبارنامه‌ها یا URLهای وب‌هوک را مستقل از توکن‌های API بچرخانید، درخواست‌های غیرمجاز و تأخیر را پایش کنید و payloadهای خام را فقط تا زمانی نگه دارید که نیازهای عملیاتی و سیاستی توجیه می‌کنند.
وضعیت‌های تحویل، برگشت و توقف ارسال را مدل کنید
شواهد تحویل و برگشت Postmark را به یک مدل داخلی در سطح گیرنده نگاشت کنید و در عین حال نوع اصلی ارائهدهنده، MessageID، زمان، وضعیت یا دسته‌بندی برگشت و اطلاعات عیب‌یابی را نگه دارید. پذیرش توسط API، پردازش در Postmark، پذیرش توسط سرور مقصد، عدم تحویل بعدی، قرار گرفتن در پوشه صندوق ایمیل و تعامل وضعیت‌های متفاوتی هستند. رویداد delivered معمولاً مشاهده مستند ارائهدهنده از سرور مقصد را منعکس میکند، نه نمایی از پوشه نهایی. خطاهای موقت می‌توانند مدیریت انتقال محدود را توجیه کنند؛ خطاهای دائمی تأییدشده نشانی باید به توقف ارسال در سطح گیرنده منجر شوند. گزارش‌های اسپم و لغو اشتراک‌ها باید پیش از jobهای بعدی ایمنی گیرنده را به‌روز کنند. فعال‌سازی مجدد دستی را با مجوز، دلیل و تاریخچه ممیزی محافظت کنید. وضعیت رضایت و توقف ارسال را در اختیار محصول نگه دارید تا مهاجرت محافظت از گیرنده را از بین نبرد. خوانده شدن توسط انسان را از ردیابی باز شدن یا کلیک استنباط نکنید؛ این‌ها ابزار سنجش تعامل‌اند و ممکن است تحت تأثیر فناوری‌های حریم خصوصی قرار گیرند.
مسیرهای sandbox، محیط عملیاتی و خطا را آزمایش کنید
برای خطاهای قطعی و قابل‌پیش‌بینی، از امکانات آزمایشی یا sandbox مستند Postmark و گیرندگان کنترل‌شده اختصاصی استفاده کنید، نه نشانی‌های واقعی مشتریان. توکن‌های معتبر و نامعتبر، هویت‌های From غیرمجاز، گیرندگان تأییدشده و مسدودشده، متن و HTML، Unicode، پیوست‌ها، حداقل‌سازی فراداده، message streamها، timeout درخواست پیش و پس از پذیرش، پاسخ نرخ، احراز هویت وب‌هوک، تحویل تکراری، رویدادهای خارج از ترتیب، دسته‌بندی‌های برگشت، توقف ارسال و چرخش توکن را آزمایش کنید. هدرهای خام دریافت‌شده، هم‌راستایی DKIM و DMARC، Reply-To، پیکربندی ردیابی و همبستگی MessageID را بررسی کنید. تأیید کنید که محیط‌های غیرعملیاتی به گیرندگان محیط عملیاتی دسترسی ندارند. آزمون‌های خروجی گرفتن و مهاجرت را برای فهرست توقف ارسال و شواهد عملیاتی اجرا کنید. در صورت دسترسی cross-tenant به فرستنده یا رویداد، در دسترس نبودن اعمال فهرست توقف ارسال، پذیرش مبهم وب‌هوک، وجود اسرار در لاگ‌ها، تلاش‌های مجدد نامحدود یا ناتوانی در توقف امن server یا stream آسیب‌دیده، راه‌اندازی را متوقف کنید.
SendHQ چگونه جای می‌گیرد
SendHQ یک API ایمیل در سطح فضای کاری برای ارتباط موردانتظار محصول است. مستندات عمومی آن ارسال با دامنه تأییدشده، ایمیل ورودی، قالب‌های میزبانی‌شده، رویدادهای تحویل، موارد توقف ارسال و یک داشبورد وب را پوشش میدهد.
پرسش‌های متداول
کدام endpoint یک ایمیل را از طریق Postmark ارسال میکند؟
Email API فعلی Postmark درخواست POST /email را با یک server token و فیلدهای ساخت‌یافته JSON برای پیام مستند کرده است. آن را فقط از کد سمت سرور مجاز فراخوانی کنید.
server token در Postmark را کجا باید ذخیره کرد؟
آن را در یک سیستم مدیریت اسرار سمت سرور با دامنه محدود به محیط و بار کاری، دسترسی ممیزی‌شده، چرخش آزموده‌شده و بدون هیچ افشایی در سمت کلاینت ذخیره کنید.
آیا پاسخ موفق Postmark API تحویل را ثابت میکند؟
خیر. این پاسخ پذیرش توسط ارائهدهنده را طبق قرارداد فوری API ثبت میکند. پذیرش توسط سرور مقصد، برگشت، رسیدن به صندوق ایمیل و تعامل به شواهد بعدی و دامنهدار نیاز دارند.
timeoutهای درخواست Postmark را چگونه باید دوباره امتحان کرد؟
timeout پس از ارسال احتمالی را مبهم بدانید. پیش از ارسال مجدد، فعالیت ارائهدهنده یا رویدادهای بعدی را با همان کلید پایدار رویداد کسب‌وکار تطبیق دهید.
آیا باید فرض کرد وب‌هوک‌های Postmark یکتا و مرتب‌اند؟
خیر. برای تأخیر، تلاش مجدد، تکرار و رسیدن خارج از ترتیب طراحی کنید. پذیرش را ایمن کنید، رویدادها را به‌طور پایدار ثبت کنید، تکرارها را حذف کنید و گذارهای یکنوای وضعیت را در سطح گیرنده اعمال کنید.
آیا فراداده Postmark باید شامل اسرار مشتری باشد؟
خیر. از مقادیر همبستگی محدود و حافظ حریم خصوصی استفاده کنید. فراداده، برچسب‌ها، هدرها، نماهای فعالیت، رویدادها، لاگ‌ها و خروجی‌ها می‌توانند این فیلدها را در عملیات افشا کنند.
آیا رویداد delivered رسیدن به صندوق ورودی را ثابت میکند؟
خیر. این شاهدی دامنهدار از سوی ارائهدهنده است که معمولاً پذیرش توسط سرور مقصد را نشان میدهد. فیلترینگ گیرنده، قوانین صندوق ایمیل، پوشه نهایی و تعامل انسانی جداگانهاند.
مستندات API SendHQ را از کجا پیدا کنم؟
برای API ایمیل، ارسال با دامنه تأییدشده، ایمیل ورودی، قالبها، رویدادهای تحویل و موارد توقف ارسال، مستندات عمومی SendHQ را ببینید.
منابع
- Email API در Postmark — Postmark
- نمای کلی Postmark API — Postmark
- نمای کلی وب‌هوک‌های Postmark — Postmark
- وب‌هوک Bounce در Postmark — Postmark
- RFC 5321: پروتکل ساده انتقال ایمیل (SMTP) — RFC Editor