وب‌هوک‌ها و رویدادها
نتیجه‌ی تحویل، مستقیم در اپلیکیشن شما
Mail.Land وقتی پیامی تحویل می‌شود، به تأخیر می‌افتد، برمی‌گردد یا ناموفق تمام می‌شود، وقتی گیرنده شکایت می‌کند و وقتی ایمیل ورودی می‌رسد، رویدادی امضاشده به نشانی شما می‌فرستد و از هر تلاش گزارشی نگه می‌دارد.
import crypto from "node:crypto";
// header: X-MLND-Signature: t=1708171200,v1=<hex>
export function verify(rawBody, header, secret) {
if (typeof header !== "string" || header === "") return false;
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
const age = Math.abs(Date.now() / 1000 - Number(parts.t));
if (!parts.t || !parts.v1 || age > 300) return false;
const expected = crypto
.createHmac("sha256", secret)
.update(`${parts.t}.${rawBody}`)
.digest("hex");
const a = Buffer.from(expected);
const b = Buffer.from(parts.v1);
return a.length === b.length && crypto.timingSafeEqual(a, b);
}رویدادهایی که امروز می‌توانید مشترکشان شوید
هشت نوع رویداد فعال است. مشترک همه شوید یا فقط آن‌هایی که لازم دارید.
| چه وقت فرستاده می‌شود | |
|---|---|
| message.delivered | سرور ایمیل گیرنده پیام را پذیرفت |
| message.deferred | تحویل فعلاً به تأخیر افتاد و Mail.Land همچنان تلاش می‌کند |
| message.bounced | سرور گیرنده پیام را رد کرد؛ همراه با نوع برگشت و پاسخ سرور |
| message.failed | Mail.Land پیام را به دلیلی داخلی یا طبق یک سیاست ناموفق علامت زد؛ این رویداد گیرنده را به فهرست عدم ارسال نمی‌برد |
| message.complained | گیرنده از طریق حلقه‌ی بازخورد، پیام را هرزنامه گزارش کرد |
| message.outcome_unknown | Mail.Land هنوز نمی‌داند پیام به صف تحویل رسیده یا نه؛ اگر بعداً نتیجه را بفهمد، رویداد نهایی می‌آید |
| message.retried | شما پیام برگشتی یا ناموفقی را دوباره فرستادید و دوباره در صف قرار گرفت |
| inbound.received | ایمیلی روی یکی از دامنه‌های شما رسید و با یک مسیر وب‌هوک جور شد |
رویدادهای دیگر، مثل message.sent، باز شدن و کلیک، برای آینده در فهرست رویدادها آمده‌اند و هنوز فرستاده نمی‌شوند. نشانی فهرست رویدادها مشخص می‌کند کدام‌ها همین حالا در دسترس‌اند.
امضاشده، و فقط به جایی که باید برود
هر درخواست را می‌توان بررسی کرد و Mail.Land مقصدهایی را که ممکن است سوءاستفاده شوند رد می‌کند.
HMAC-SHA256 همراه با زمان
سرآیند X-MLND-Signature یک زمان و امضای همان زمان به‌اضافه‌ی بدنه‌ی خام را دارد. امضا را با مقایسه‌ی زمان‌ثابت بررسی کنید و زمان‌های قدیمی را رد کنید تا جلوی ارسال دوباره‌ی درخواست‌های ضبط‌شده گرفته شود.
فقط HTTPS روی پورت 443
نشانی‌های خصوصی و loopback رد می‌شوند. تغییر مسیرها حداکثر تا سه گام دنبال می‌شوند و هر گام پیش از ارسال هر چیزی دوباره بررسی می‌شود.
یک کلید محرمانه برای هر وب‌هوک
کلید امضا فقط یک بار، هنگام ساخت وب‌هوک، نمایش داده می‌شود. اگر لو رفت، کلید تازه بسازید؛ کلید قبلی همان لحظه از کار می‌افتد.
وقتی نشانی شما در دسترس نیست
تحویل ناموفق به‌طور پیش‌فرض با این زمان‌بندی دوباره تلاش می‌شود. پاسخ 2xx در کمتر از ۱۵ ثانیه موفق حساب می‌شود.
| انتظار پیش از تلاش | زمان سپری‌شده از تلاش اول | |
|---|---|---|
| تلاش ۱ | بدون انتظار | ۰ |
| تلاش ۲ | بلافاصله | حدود ۰ |
| تلاش ۳ | ۱ دقیقه | حدود ۱ دقیقه |
| تلاش ۴ | ۵ دقیقه | حدود ۶ دقیقه |
| تلاش ۵ | ۱۵ دقیقه | حدود ۲۱ دقیقه |
| تلاش ۶ | ۱ ساعت | حدود ۱ ساعت و ۲۱ دقیقه |
تمام شدن زمان پاسخ، خطای شبکه و پاسخ‌های 408، 429، 500، 502، 503 و 504 دوباره تلاش می‌شوند و سرآیند Retry-After زمان انتظار بعدی را تعیین می‌کند. بقیه‌ی پاسخ‌های بیرون از 2xx نهایی‌اند. هر تحویل ناموفق را می‌توانید از گزارش تحویل‌ها دوباره بفرستید.
ساخته‌شده برای رویدادهایی که دیر یا دو بار می‌رسند
تحویل دست‌کم یک‌بار است و همیشه به ترتیب نیست. هر رویداد آنچه را برای مدیریت این وضعیت لازم دارید همراه دارد.
نسخه‌ی وضعیت
هر رویداد پیام یک نسخه‌ی وضعیت دارد که با هر تغییر بالا می‌رود. اگر مشترک همه‌ی رویدادهای پیام باشید و رویداد را فقط وقتی اعمال کنید که نسخه‌اش از نسخه‌ی ذخیره‌شده بالاتر است، وضعیت شما با هر ترتیب رسیدنی درست می‌ماند. اگر رویدادهای کمتری می‌گیرید، وضعیت فعلی را از API بخوانید.
شناسه‌ی رویداد ثابت
شناسه‌ی رویداد در همه‌ی تلاش‌های دوباره‌ی یک رویداد یکسان است. شناسه‌های پردازش‌شده را نگه دارید و تکراری‌ها را رد کنید.
محتوای نسخه‌دار
هر نوع رویداد نسخه‌ی طرح‌واره‌ی خودش را دارد. Mail.Land به نسخه‌ی موجود فقط فیلد و سرآیند اضافه می‌کند، پس گیرنده‌ای که فیلدهای ناشناخته را نادیده می‌گیرد به کارش ادامه می‌دهد.
کنترل و دید کامل
وب‌هوک‌ها را در پنل یا از طریق API مدیریت کنید.
فیلتر بر اساس محصول و دامنه
رویدادهای ایمیل تراکنشی، بازاریابی یا ورودی، نوع‌های مشخصی از رویداد، و همه‌ی دامنه‌ها یا فقط بعضی از آن‌ها را انتخاب کنید.
پیش از اتکا، آزمایش کنید
یک رویداد آزمایشی با همان امضا و همان روش ارسال واقعی بفرستید. پاسخ آن همچنین می‌گوید رویدادهای واقعی با اشتراک فعلی به این نشانی می‌رسند یا نه.
گزارش تحویل‌ها
هر تلاش را با وضعیتش ببینید، ناموفق‌ها را جدا کنید و تحویلی را دستی دوباره بفرستید.
توقف خودکار
به‌طور پیش‌فرض پس از ۱۰ تلاش ناموفقِ پشت‌سرهم، وب‌هوک متوقف می‌شود و در پنل اعلان می‌گیرید. وقتی نشانی‌تان دوباره کار کرد، آن را از سر بگیرید.
پرسش‌های وب‌هوک
وقتی پیامی پذیرفته یا ارسال می‌شود، رویدادی هست؟
هنوز نه. message.sent در فهرست رویدادها هست اما امروز فرستاده نمی‌شود. پاسخ API به درخواست ارسال شما شناسه‌ی پیام‌ها را دارد و اولین رویداد وب‌هوکی که می‌گیرید نتیجه‌ی تحویل است.
می‌توانم رویداد باز شدن و کلیک را بگیرم؟
امروز نه از طریق وب‌هوک. باز شدن‌ها و کلیک‌ها، هر جا ردیابی روشن باشد، در گزارش‌ها و تحلیل‌های شما دیده می‌شوند؛ رویدادهای آن‌ها برای بعد در فهرست رویدادها آمده‌اند.
اگر پیامی تحویل‌شده بعداً برگردد چه می‌شود؟
ممکن است پیش بیاید: سرور گیرنده می‌تواند پیامی را بعد از پذیرفتن رد کند. در این حالت Mail.Land رویداد برگشت را با نسخه‌ی وضعیت بالاتر می‌فرستد؛ پس بعد از رویداد تحویل هم پردازش رویدادها را ادامه دهید.
اگر نشانی من یک روز از دسترس خارج باشد چه می‌شود؟
به‌طور پیش‌فرض هر رویداد تا ۶ بار در حدود ۸۰ دقیقه تلاش می‌شود و وب‌هوک پس از ۱۰ تلاش ناموفقِ پشت‌سرهم متوقف می‌شود. تا وقتی متوقف است، رویداد تازه‌ای برایش در صف قرار نمی‌گیرد. بعد از ازسرگیری، تحویل‌های ناموفق را از گزارش دوباره بفرستید، وضعیت پیام‌ها را از API بخوانید و ایمیل‌های ورودی ازدست‌رفته را دوباره ارسال کنید.
چطور مطمئن شوم درخواست از Mail.Land آمده است؟
با کلید محرمانه‌ی وب‌هوک، HMAC-SHA256 را روی زمان، یک نقطه و بدنه‌ی خام حساب کنید، نتیجه را با مقایسه‌ی زمان‌ثابت با مقدار v1 بسنجید و زمان‌های قدیمی‌تر از ۵ دقیقه را رد کنید. در مستندات نمونه‌ای با مقادیر دقیق آمده است.
یک نشانی می‌تواند فقط رویدادهای بعضی از دامنه‌هایم را بگیرد؟
بله. دامنه‌ی کارکرد وب‌هوک را روی دامنه‌های انتخاب‌شده بگذارید و آن‌ها را مشخص کنید؛ از آن پس فقط رویدادهای همان دامنه‌ها را می‌گیرد.
اپلیکیشن‌تان را به نتیجه‌ی هر تحویل وصل کنید
حساب رایگان بسازید، یک نشانی اضافه کنید و برایش رویداد آزمایشی بفرستید.