راهنما · SendGrid API

یک تیم محصول چگونه باید SendGrid API را به‌طور امن پیاده‌سازی کند؟

SendGrid API را پشت یک سرویس ایمیل سمت سرور پیاده‌سازی کنید و از یک دامنه ارسال احراز هویت‌شده و کلید API محدود به مجوز Mail Send استفاده کنید. پیش از فراخوانی `POST /v3/mail/send` هر پیام را اعتبارسنجی کنید، رکورد ارسال خودتان را ذخیره کنید و `X-Message-ID` پاسخ را ثبت کنید. payloadهای امضاشده Event Webhook را از بایت‌های خامشان پردازش کنید، تکرار رویدادها را حذف کنید و برگشت‌ها، گزارش‌های اسپم و لغو اشتراک‌ها را رعایت کنید. `202 Accepted`، تحویل به سرور گیرنده و رسیدن به صندوق ورودی را وضعیت‌هایی جداگانه بدانید و تلاش‌های مجدد محدود را فقط برای خطاهای گذرا به کار ببرید.

یک کار ارسال محدود و مشروع تعریف کنید

Mail Send API نسخه v3 در SendGrid یک endpoint ارائه‌دهنده برای ایمیل خروجی است، نه یک صندوق ایمیل عمومی برای کاربران. آن را پشت یک سرویس اپلیکیشن قابل‌اعتماد یا worker صف قرار دهید و تعریف کنید کدام رویدادهای محصول می‌توانند پیام بسازند، مانند تأیید حساب، رسید، اطلاعیه امنیتی یا اعلان درخواستی. کلید ارائه‌دهنده را در اختیار مرورگرها، کلاینت‌های موبایل، قالب‌ها، promptها یا لاگ‌ها قرار ندهید. پیام‌های تراکنشی را در سطح مدل داده از کمپین‌های وابسته به رضایت جدا کنید تا انتظارات گیرندگان، مدیریت ترجیحات و اعتبار به‌طور مستقل اداره شوند. پیش از پیاده‌سازی تصمیم بگیرید مالک دامنه فرستنده کیست، چه کسی قالب‌ها را تأیید می‌کند، کدام محیط‌ها می‌توانند به بیرون ارسال کنند و در محیط توسعه کدام گیرندگان مجازند. این دامنه کار به مرز مجوزهای کلید API، راه‌اندازی دامنه، سوابق ممیزی، هشدارها و واکنش به رخداد تبدیل می‌شود. همچنین مهاجرت میان ارائه‌دهندگان را ممکن می‌کند، زیرا کد محصول یک عملیات ایمیل تأییدشده را درخواست می‌کند، نه اینکه در سراسر اپلیکیشن درخواست‌های دلخواه SendGrid بسازد.

یک دامنه ارسال اختصاصی را احراز هویت کنید

Domain Authentication در SendGrid را برای دامنه یا زیردامنه‌ای با کاربرد مشخص که در کنترل شماست پیکربندی کنید، سپس دقیقاً رکوردهای DNS تولیدشده برای آن هویت را منتشر کنید و در SendGrid تأییدشان کنید. مستندات ارائه‌دهنده یادآوری می‌کند که زیردامنه‌ها هویت احراز هویت‌شده دامنه والد را به ارث نمی‌برند، پس دامنه‌ای را که واقعاً در نشانی‌های From به کار می‌رود تأیید کنید. پیش از تغییر DNS، رکوردهای SPF و DMARC موجود را بازبینی کنید؛ برای همان نام هاست سیاست SPF دوم نسازید و سیاست DMARC موجود سازمان را بدون هماهنگی با مالکش جایگزین نکنید. وقتی مخاطبان و ریسک ترافیک تراکنشی و تبلیغاتی متفاوت است، آن‌ها را روی هویت‌هایی که آگاهانه انتخاب شده‌اند نگه دارید. نشانی From قابل‌مشاهده، return path، دامنه امضای DKIM، مسیر پاسخ و رفتار link branding را در یک پیام آزمایشی دریافت‌شده تأیید کنید. احراز هویت هویت مجاز و سیگنال‌های هم‌راستایی را برقرار می‌کند، اما پوشه نهایی در سیستم گیرنده را تعیین نمی‌کند. پس از موفقیت تأیید DNS، پایش برگشت‌ها، گزارش‌های اسپم، انتظارات گیرندگان و محتوا را ادامه دهید.

برای هر محیط کلیدهای API با حداقل دسترسی صادر کنید

یک کلید API از نوع Custom Access بسازید که فقط مجوزهای لازم بار کاری را داشته باشد؛ برای یک worker ارسال معمولاً دسترسی Mail Send کافی است. به فرستنده روزمره Full Access به قالب‌ها، فهرست توقف ارسال، هم‌تیمی‌ها، آمار، پیکربندی IP یا مدیریت حساب ندهید. برای توسعه، staging و محیط عملیاتی کلیدهای جداگانه با نام‌هایی که سرویس مالک و هدف چرخش را مشخص می‌کنند استفاده کنید. SendGrid کلید جدید را فقط یک بار نمایش می‌دهد، پس آن را مستقیماً در مدیر اسرار آن محیط قرار دهید و هرگز در کنترل نسخه یا یک سند مشترک کپی نکنید. در زمان اجرا، آن را از پیکربندی متکی به مخزن اسرار بخوانید و فقط در هدر `Authorization: Bearer` روی HTTPS ارسال کنید. چرخش کلید را به‌صورت یک توالی عملیاتی آزمایش کنید: جایگزینی با مجوزهای محدود معادل بسازید، آن را مستقر کنید، ترافیک کنترل‌شده موفق را تأیید کنید و سپس کلید قدیمی را ابطال کنید. برای پاسخ‌های غیرمنتظره 401 یا 403 هشدار تعریف کنید، زیرا ممکن است نشان‌دهنده کلید گم‌شده، اعتبارنامه ابطال‌شده، عدم تطابق مجوز یا تغییر ناامن پیکربندی باشند.

هر درخواست Mail Send را بسازید و ثبت کنید

پیش از تماس با SendGrid یک رکورد خروجی داخلی بسازید. به آن کلید پایدار رویداد اپلیکیشن، tenant، هویت فرستنده، گیرندگان تأییدشده، دسته پیام، نسخه قالب و وضعیت بدهید. payload ارائه‌دهنده را از همان رکورد با `personalizations`، `from`، `subject` و دست‌کم یک بخش محتوای پشتیبانی‌شده یا یک قالب پویای تأییدشده بسازید. پیش از فراخوانی شبکه، نحو نشانی، تعداد گیرندگان، اندازه پیوست، داده‌های قالب و هدرهای سفارشی را اعتبارسنجی کنید. نمای کلی فعلی Mail Send در SendGrid اندازه کل درخواست، شامل پیوست‌ها، را به کمتر از 30 MB و مجموع گیرندگان در To، Cc و Bcc را به حداکثر 1,000 محدود می‌کند. درخواست‌های کوچک‌تر و با هدف مشخص را آسان‌تر می‌توان ممیزی و بازیابی کرد. در پاسخ `202 Accepted`، هدر `X-Message-ID` را ثبت و به رکورد خروجی پیوست کنید. داده‌های شخصی را در categories یا unique arguments قرار ندهید؛ SendGrid هشدار می‌دهد که این مقادیر ممکن است خارج از محافظت‌های موردانتظار برای محتوای پیام نگهداری و مشاهده شوند.

Event Webhook را تأیید و پردازش کنید

Event Webhook در SendGrid را روی یک endpoint با HTTPS پیکربندی کنید که بتواند بدنه خام درخواست را نگه دارد. امضای رمزنگاری، OAuth 2.0 یا هر دو را فعال کنید. برای تحویل امضاشده، timestamp و `X-Twilio-Email-Event-Webhook-Signature` را پیش از parse کردن JSON در برابر بایت‌های خام دقیق تأیید کنید؛ Twilio هشدار می‌دهد که serialize کردن دوباره payload می‌تواند بایت‌ها را تغییر دهد و تأیید را باطل کند. ورودی احراز هویت‌نشده را رد کنید، محدودیت معقولی برای اندازه درخواست اعمال کنید و طبق سیاست timestamp انتخاب‌شده تیم از تکرار (replay) جلوگیری کنید. پس از تأیید، دسته رویدادها را پیش از برگرداندن پاسخ موفق در صف بگذارید یا به‌طور پایدار ذخیره کنید. با `sg_event_id` تکرارها را حذف کنید، سپس `sg_message_id`، `X-Message-ID` ذخیره‌شده و یک مقدار همبستگی داخلی غیرحساس را مرتبط کنید. گذار وضعیت‌ها را یکنوا کنید تا یک رویداد processed دیررسیده نتواند نتیجه delivered یا bounce بعدی را بازنویسی کند. رویداد اصلی ارائه‌دهنده را برای عیب‌یابی در فضای ذخیره‌سازی با دسترسی محدود نگه دارید، اما نگهداری نشانی‌ها، متن پاسخ و داده‌های تعامل را به آنچه محصول و سیاست واقعاً لازم دارند محدود کنید.

پذیرش، تحویل و رسیدن به صندوق ورودی را دقیق مدل کنید

پاسخ HTTP `202 Accepted` در SendGrid یعنی درخواست پذیرفته شده و برای پردازش در صف قرار گرفته است. نمی‌گوید که مقصد پیام را پذیرفته است. رویداد وب‌هوک `processed` یعنی SendGrid پیام را پذیرفته و می‌تواند برای تحویل تلاش کند. رویداد `delivered` یعنی SendGrid گزارش می‌دهد که سرور ایمیل گیرنده آن را پذیرفته است، اغلب همراه با یک پاسخ SMTP. این هم رسیدن به صندوق ورودی را ثابت نمی‌کند، زیرا سیستم گیرنده می‌تواند ایمیل پذیرفته‌شده را در یک زبانه صندوق ورودی، قرنطینه، پوشه junk یا جای دیگری دسته‌بندی کند. این وضعیت‌ها را در ذخیره‌سازی و رابط‌های کاربری جدا نگه دارید: درخواست‌شده، پذیرفته‌شده توسط ارائه‌دهنده، پردازش‌شده، به تعویق افتاده، پذیرفته‌شده توسط سرور گیرنده، برگشت‌خورده، drop‌شده، گزارش اسپم‌شده یا در فهرست توقف ارسال. از ترجمه هر پاسخ HTTP بدون خطا به «تحویل‌شده» پرهیز کنید. سیگنال‌های تعامل مانند باز شدن نیز دلیل تحویل نیستند و ممکن است تحت تأثیر قابلیت‌های حریم خصوصی قرار گیرند. نام‌گذاری دقیق وضعیت‌ها بررسی‌های پشتیبانی، تلاش‌های مجدد و تصمیم‌های تحویل‌پذیری را امن‌تر می‌کند.

پیش از تلاش مجدد، خطاها را دسته‌بندی کنید

خطاهای ارائه‌دهنده را بر اساس دسته مدیریت کنید، نه اینکه هر پاسخ غیر 202 را دوباره امتحان کنید. خطای 400 معمولاً مستلزم اصلاح payload، فرستنده، داده‌های قالب یا هدرهای رزروشده است. 401 به احراز هویت اشاره دارد؛ 403 ممکن است نشان‌دهنده مجوز ناکافی یا سیاست حساب باشد؛ 413 مستلزم کاهش اندازه پیام است. SendGrid هدرهای محدودیت نرخ را برای هر endpoint مستند کرده است و وقتی سهمیه دوره تازه‌سازی تمام شود 429 برمی‌گرداند، پس تا زمان reset صبر کنید و jitter اضافه کنید، نه اینکه تلاش‌های مجدد هم‌زمان بسازید. خطاهای 5xx و خطاهای انتقال را با exponential backoff، تعداد تلاش محدود و یک هشدار عملیاتی دوباره امتحان کنید. timeoutهای مبهم توجه ویژه‌ای می‌خواهند: ممکن است ارائه‌دهنده درخواست را پذیرفته باشد، حتی اگر کلاینت پاسخ را از دست داده باشد. رکورد خروجی را در وضعیت نامعلوم نگه دارید، دنبال رویدادهای مرتبط بگردید و پیش از ارسال مجدد یک قاعده تطبیق آگاهانه را الزامی کنید. APIهای ارائه‌دهنده نیاز به جلوگیری از تکرار در سطح محصول را از بین نمی‌برند. هرگز مقصدی را که برگشت دائمی شناخته‌شده، گیرنده نامعتبر، لغو اشتراک یا گزارش اسپم دارد، مانند یک خطای گذرای زیرساخت دوباره امتحان نکنید.

فهرست توقف ارسال و انتخاب‌های گیرندگان را رعایت کنید

رویدادهای برگشت ایمیل (bounce)، ارسال‌نشده (dropped)، گزارش اسپم، لغو اشتراک و لغو اشتراک گروهی را در یک مدل ایمنی گیرنده دریافت کنید. SendGrid از فهرست‌های توقف ارسال سراسری و گروه‌های لغو اشتراک برای دسته‌های مختلف پیام پشتیبانی می‌کند. هر پیام تبلیغاتی یا اختیاری را به گروه درست مرتبط کنید، مسیر قابل‌فهمی برای ترجیحات فراهم کنید و وقتی مورد توقف ارسال مرتبط اعمال می‌شود ارسال را متوقف کنید. از گزینه‌های دور زدن فهرست توقف ارسال به‌عنوان یک تکنیک روزمره تحویل استفاده نکنید. یک پیام حیاتی محصول ممکن است به سیاست حقوقی و عملیاتی جداگانه و مستندی نیاز داشته باشد، اما آن سیاست نباید بی‌صدا انتخاب تبلیغاتی یک فرد یا سازوکار حفاظت از اعتبار ارائه‌دهنده را نادیده بگیرد. از ابزارهای پشتیبانی که یک مورد توقف ارسال را حذف می‌کنند با مجوز قوی، دلیل قابل‌مشاهده و سابقه ممیزی محافظت کنید. خطاهای دائمی و موقت تحویل را جداگانه ردیابی کنید و هر فعال‌سازی مجدد دستی را پیش از ارسال بعدی بازبینی کنید. این کنترل‌ها از گیرندگان محافظت می‌کنند و تلاش‌های مکرر به مقصدهایی را که ترافیک را رد کرده یا نپذیرفته‌اند کاهش می‌دهند. همچنین مانع می‌شوند ارسال تراکنشی رفتار ناامن کمپین‌ها را به ارث ببرد.

پیش از ترافیک محیط عملیاتی، کل چرخه عمر را آزمایش کنید

با یک کلید SendGrid غیرعملیاتی و یک زیردامنه احراز هویت‌شده کنترل‌شده شروع کنید. DNS را تأیید کنید، سپس نسخه‌های متن ساده و HTML را به صندوق‌هایی که در اختیار تیم است بفرستید. پاسخ `202` و `X-Message-ID` را تأیید کنید و بررسی کنید که رویدادهای وب‌هوک امضاشده با رکورد خروجی محلی مرتبط می‌شوند. مسیرهای payload نامعتبر، کلید ابطال‌شده، مجوز ناموجود، پیوست بیش از حد بزرگ، محدودیت نرخ، deferred، bounce، dropped و رویداد تکراری را بدون استفاده از نشانی‌های واقعی مشتریان اجرا کنید. تأیید کنید که تأیید وب‌هوک بدنه تغییریافته را رد می‌کند و handler فقط پس از ثبت پایدار تأیید دریافت می‌فرستد. چرخش کلید، بازگشت قالب، اعمال فهرست توقف ارسال و timeout مبهم کلاینت را آزمایش کنید. برای خطاهای درخواست، تأخیر رویدادها، تعویق‌ها، برگشت‌ها، گزارش‌های اسپم و خطاهای امضای وب‌هوک داشبورد بسازید، با شناسه‌های tenant و پیام اما بدون اعتبارنامه یا محتوای کامل. در پایان، هنگام راه‌اندازی مستندات فعلی SendGrid و محدودیت‌های حساب را بازبینی کنید، زیرا امتیازات پلن، قابلیت‌های منطقه‌ای، سهمیه‌ها و سیاست‌های ارائه‌دهنده ممکن است مستقل از کد اپلیکیشن تغییر کنند.

وابستگی‌های ویژه ارائه‌دهنده را مقایسه کنید

یک یکپارچه‌سازی مستقیم SendGrid زمانی مناسب است که یک تیم آگاهانه به فیلدهای درخواست ویژه SendGrid، قالب‌ها، کنترل‌های حساب، قالب‌های وب‌هوک، موارد توقف ارسال و مالکیت عملیاتی وابسته باشد. مستندات عمومی SendHQ یک API ایمیل در سطح فضای کاری با ارسال از دامنه تأییدشده، ایمیل ورودی، قالب‌های میزبانی‌شده، رویدادهای تحویل، موارد توقف ارسال و یک داشبورد وب را شرح می‌دهد. پیش از مهاجرت، payloadها، رویدادها، کنترل‌های هویت، موارد توقف ارسال، نیازهای منطقه‌ای و شناسه‌های ارائه‌دهنده ذخیره‌شده این دو ارائه‌دهنده را بررسی کنید.

پرسش‌های متداول

آیا 202 Accepted در SendGrid یعنی ایمیل تحویل شده است؟

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

کلید ارسال SendGrid چه مجوزی باید داشته باشد؟

از کلید Custom Access محدود به قابلیت Mail Send که worker لازم دارد استفاده کنید. برای ارسال روزمره از Full Access پرهیز کنید و برای توسعه، staging، محیط عملیاتی، مدیریت و هر بار کاری دیگری با اختیارات متفاوت، کلیدهای جداگانه تحت مدیریت اسرار به کار ببرید.

امضای Event Webhook در SendGrid را چگونه باید تأیید کرد؟

بدنه خام دقیق HTTP را نگه دارید، هدرهای امضا و timestamp مربوط به Twilio را بخوانید و آن‌ها را پیش از parse کردن JSON یا serialize کردن مجدد تأیید کنید. محافظت در برابر replay را اعمال کنید، تأیید ناموفق را رد کنید و سپس دسته رویدادها را پیش از تأیید دریافت به‌طور پایدار ذخیره یا در صف قرار دهید.

آیا محصول باید هر درخواست ناموفق Mail Send را دوباره امتحان کند؟

خیر. خطاهای payload، احراز هویت، مجوزدهی، اندازه و گیرنده دائمی را اصلاح کنید، نه اینکه دوباره امتحان کنید. پاسخ‌های 429 را تا زمان reset مستند به تعویق بیندازید، خطاهای گذرای شبکه و 5xx را با backoff محدود دوباره امتحان کنید و timeoutهای مبهم را پیش از ارسال مجدد تطبیق دهید.

آیا می‌توان فهرست توقف ارسال SendGrid را برای ایمیل تراکنشی دور زد؟

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

یک تیم پیش از مقایسه SendGrid و SendHQ چه چیزی را باید ارزیابی کند؟

پیش از برنامه‌ریزی مهاجرت، payloadها، رویدادها، کنترل‌های هویت، موارد توقف ارسال، نیازهای منطقه‌ای و شناسه‌های ارائه‌دهنده ذخیره‌شده را مقایسه کنید.

منابع

ادامه یادگیری

راهنمای پیاده‌سازی API ایمیل برای تیم‌های محصولیکپارچه‌سازی امنی با API ایمیل طراحی کنید: دامنه‌های تأییدشده، ارسال از طریق صف، شناسه‌های پایدار، تلاش مجدد کنترل‌شده، رویدادهای تحویل، فهرست توقف ارسال و جداسازی tenantها.