API ایمیل تراکنشی
یک فراخوانی REST برای هر ایمیلی که محصولتان می‌فرستد
رسید، بازیابی رمز عبور، هشدار و اطلاعیه‌های حساب را از طریق POST /v1/transactional/send بفرستید. MailLand درخواست را بررسی می‌کند، هر پیام را با کلید DKIM دامنه شما امضا می‌کند، آن را به سرورهای ایمیل خود می‌سپارد و گزارش می‌دهد چه بر سرش آمده است. سرورها در Hetzner آلمان اجرا می‌شوند.
curl -X POST https://api.mail.land/v1/transactional/send \
-H "X-API-Key: ml_pet_..." \
-H "X-Idempotency-Key: order-1042-receipt" \
-H "Content-Type: application/json" \
-d '{
"from": { "email": "[email protected]", "name": "Your App" },
"to": [{ "email": "[email protected]", "name": "Jane" }],
"subject": "Your receipt for order 1042",
"htmlContent": "<p>Thanks, Jane. Your payment was received.</p>",
"textContent": "Thanks, Jane. Your payment was received.",
"tags": ["receipt"]
}'پس از فراخوانی API چه اتفاقی می‌افتد
چهار مرحله، که هر کدام را در پاسخ، گزارش پیام یا یک وب‌هوک می‌بینید.
بررسی‌شده
API دامنه فرستنده، دامنه دسترسی و محدودیت‌های کلید شما و تک‌تک گیرنده‌ها را بررسی می‌کند. نشانی‌های موجود در فهرست عدم ارسال رد می‌شوند و در rejectedRecipients می‌آیند؛ اگر محافظت در برابر غلط تایپی و دامنه‌های یک‌بارمصرف روشن باشد، این نشانی‌ها هم فهرست می‌شوند و برای غلط تایپی، نشانی اصلاح‌شده پیشنهاد می‌شود.
در صف
هر پیام پذیرفته‌شده پیش از آنکه API پاسخ 202 Accepted بدهد در پایگاه داده MailLand ثبت می‌شود و سپس به صف تحویل سپرده می‌شود. پاسخ شامل شناسه کار، یک شناسه پیام برای هر گیرنده و زمان ورود به صف است؛ ارسال زمان‌بندی‌شده به‌جای آن یک شناسه زمان‌بندی برمی‌گرداند.
امضا و ارسال
هر گیرنده نسخه جداگانه‌ای با شناسه پیام خودش و بدون Cc قابل مشاهده دریافت می‌کند که با کلید DKIM دامنه شما امضا شده و از نشانی‌های IP ارسال مشترک MailLand فرستاده می‌شود.
گزارش‌شده
رویدادهای تحویل، تعویق، برگشت، شکست و شکایت به وب‌هوک شما و گزارش پیام می‌رسند. هر رویداد یک نسخه وضعیت دارد تا بتوانید رویدادها را به ترتیب درست اعمال کنید.
آنچه API در اختیارتان می‌گذارد
هر یک از این‌ها یک فیلد، یک هدر یا یک endpoint است که با مثال مستند شده است.
قالب‌های ذخیره‌شده با متغیر
قالب‌های HTML و متنی را در MailLand نگه دارید و {{placeholders}} را برای هر گیرنده پر کنید. اگر متغیری مقدار نداشته باشد، پیام با جای‌نگهدار خام فرستاده نمی‌شود: API با 422 پاسخ می‌دهد و مقدار جاافتاده را نام می‌برد.
کلیدهای idempotency
همراه درخواست ارسال، هدر X-Idempotency-Key را بفرستید. تلاش دوباره با همان کلید در ۲۴ ساعت همان پاسخ اولیه را برمی‌گرداند و چیزی نمی‌فرستد، بنابراین تلاش دوباره پس از قطع ارتباط شبکه نسخه دومی ارسال نمی‌کند.
ارسال زمان‌بندی‌شده
با افزودن scheduledAt می‌توانید تا ۷ روز جلوتر ارسال را زمان‌بندی کنید. پیام زمان‌بندی‌شده را پیش از ارسال از طریق API فهرست کنید، زمانش را تغییر دهید یا لغوش کنید.
پیوست‌ها و تصاویر درون‌خطی
تا ۱۰ فایل و ۱۰ MiB در هر پیام پیوست کنید، از جمله تصاویر درون‌خطی که HTML شما با Content-ID به آن‌ها ارجاع می‌دهد.
برچسب‌ها و هدرهای سفارشی
پیام‌ها را برچسب بزنید تا در تحلیل‌ها، گزارش‌ها و وب‌هوک‌ها فیلترشان کنید، هدرهای خودتان را اضافه کنید و برای هر پیام نشانی reply-to تعیین کنید.
بررسی پیش از ارسال
GET /v1/transactional/send/check به شما می‌گوید حسابتان همین حالا می‌تواند ارسال کند یا نه، همراه با میزان مصرف فعلی محدودیت نرخ و سهمیه ماهانه. این بررسی فرستنده یا گیرنده خاصی را بررسی نمی‌کند.
کلیدهای sandbox
کلید sandbox درخواست‌ها را می‌پذیرد و ثبت می‌کند اما تحویل نمی‌دهد، یا فقط به فهرست مجازی که خودتان تعیین می‌کنید تحویل می‌دهد، بنابراین ایمیل‌های آزمایشی فقط به نشانی‌هایی می‌رسند که خودتان انتخاب کرده‌اید.
کلیدهایی با دامنه دسترسی قابل تنظیم
هر کلید را به یک جریان، به دامنه‌های ارسال انتخابی، به فهرست مجاز IP، به محدودیت‌های دقیقه‌ای، ساعتی و روزانه و به یک تاریخ انقضا محدود کنید. کلید را از پنل یا API تعویض کنید.
بدانید چه بر سر هر پیام آمده است
پذیرفتن درخواست فقط نیمی از کار است. MailLand به شما می‌گوید بعد از آن چه شد.
وب‌هوک‌های امضاشده
رویدادهای تحویل، تعویق، برگشت، شکست و شکایت را دریافت کنید. هر درخواست با HMAC-SHA256 در هدر X-MLND-Signature امضا می‌شود و اگر endpoint شما خطا بدهد، دوباره ارسال می‌شود.
گزارش پیام
هر پیام را با شناسه‌اش پیدا کنید و همه رویدادهای تاریخچه‌اش را ببینید. گزارش‌ها بسته به طرح شما ۳۰، ۹۰ یا ۱۸۰ روز نگه‌داری می‌شوند.
افزودن خودکار به فهرست عدم ارسال
برگشت‌های دائمی و شکایت‌ها خودکار به فهرست عدم ارسال شما اضافه می‌شوند و ارسال‌های بعدی به این نشانی‌ها پیش از خروج رد می‌شوند.
نسخه v1 که فقط گسترش می‌یابد
نسخه ۱ API فقط افزایشی است: ممکن است فیلدها و رویدادهای تازه اضافه شوند، اما چیزی حذف نمی‌شود و معنای هیچ چیز تغییر نمی‌کند. تغییر ناسازگار در قالب /v2 منتشر می‌شود، دست‌کم ۱۸۰ روز پیش‌تر اعلام می‌شود و /v1 تا ۱۸۰ روز در کنار آن به کار ادامه می‌دهد.
HTTPS ساده، با هر زبانی
MailLand هنوز SDK ندارد. API از JSON روی HTTPS با هدر X-API-Key استفاده می‌کند و مستندات که به هفت زبان در دسترس است، هر درخواست را با curl، JavaScript، Node.js، Python، PHP، C#، Java و Go نشان می‌دهد.
میزبانی در اتحادیه اروپا
سرورهای MailLand در Hetzner آلمان، عمدتاً در نورنبرگ، اجرا می‌شوند و یک نسخه پشتیبان رمزگذاری‌شده در ورشو لهستان نگه‌داری می‌شود. چند زیرپردازشگر، مانند Cloudflare و Stripe، ممکن است داده‌های محدودی را بیرون از اتحادیه اروپا و بر پایه بندهای قراردادی استاندارد اتحادیه اروپا پردازش کنند. DPA تک‌تک آن‌ها را فهرست کرده است.
DPA را بخوانیدپرسشهای رایج درباره API ایمیل تراکنشی
طرح رایگان دارید؟
بله. طرح Free ماهانه ۱٬۰۰۰ ایمیل بدون هزینه دارد، با همان REST API و رله SMTP طرح‌های پولی. برای شروع به کارت اعتباری نیازی نیست.
SDK دارید؟
هنوز نه. API از JSON روی HTTPS استفاده می‌کند، پس هر کلاینت HTTP کار می‌کند. مستندات مثال‌های آماده کپی با curl، JavaScript، Node.js، Python، PHP، C#، Java و Go دارد.
چطور مطمئن شوم تلاش دوباره ایمیل را دو بار نمی‌فرستد؟
همراه POST /v1/transactional/send یا send-batch هدر X-Idempotency-Key (یا فیلد idempotencyKey) را بفرستید. تلاش دوباره با همان کلید در ۲۴ ساعت همان پاسخ اولیه را برمی‌گرداند و چیزی نمی‌فرستد. فقط همین دو endpoint کلید را می‌پذیرند.
یک درخواست می‌تواند به گیرنده‌های زیادی برود؟
درخواست تراکنشی تا ۵ گیرنده می‌پذیرد و هر کدام نسخه جداگانه‌ای دریافت می‌کند. برای ارسال انبوه، از کلید بازاریابی با POST /v1/transactional/send-batch استفاده کنید که در هر درخواست تا ۱۰٬۰۰۰ گیرنده می‌پذیرد.
وقتی پیامی برگشت می‌خورد چه می‌شود؟
برگشت دائمی یا شکایت، نشانی را به فهرست عدم ارسال شما اضافه می‌کند و به‌صورت رویداد به وب‌هوک شما فرستاده می‌شود. ارسال‌های بعدی به آن نشانی رد می‌شوند و در rejectedRecipients می‌آیند.
محدودیت‌های ارسال چیست؟
هر طرح یک حجم ماهانه و یک نرخ ارسال دقیقه‌ای دارد که در صفحه قیمت‌ها آمده است. هر کلید می‌تواند محدودیت‌های پایین‌تر خودش را داشته باشد. با عبور از یک محدودیت، API با 429 و هدر Retry-After پاسخ می‌دهد.
اولین ایمیلتان را همین امروز بفرستید
حساب رایگان بسازید، دامنه‌تان را تأیید کنید و API را فراخوانی کنید. ماهانه ۱٬۰۰۰ ایمیل رایگان است.