راهنمای مهاجرت

مهاجرت از Mailgun به Mail.Land

Q: Mailgun امکان انتخاب منطقه آمریکا یا اتحادیه اروپا را میدهد. Mail.Land کجا اجرا میشود؟

Mail.Land منطقهای برای انتخاب ندارد. نسخه اصلی دادههای شما در آلمان است؛ ارائهدهندگان بیرون از اتحادیه اروپا در صفحه GDPR ما فهرست شدهاند.

Q: آیا SDK رسمی برای Mail.Land وجود دارد؟

هنوز نه. مستندات نمونهکدهای آماده REST API را برای cURL، Node.js، Python، PHP، C#، Java و Go دارد و هر کتابخانه SMTP با رله کار میکند.

اگر با SMTP می‌فرستید، تغییر لازم فقط یک میزبان و یک گذرواژه است. اگر از API پیام‌ها استفاده می‌کنید، این راهنما هر فیلد رایج Mailgun را به Mail.Land نگاشت می‌کند و مواردی را که به تغییر کد نیاز دارند فهرست می‌کند.

رایگان شروع کنید درخواست کمک برای مهاجرت

SMTP

# Before (Mailgun)
SMTP_HOST=smtp.mailgun.org
SMTP_PORT=587          # STARTTLS
SMTP_USER=<SMTP login of your sending domain>
SMTP_PASS=<SMTP password of that login>

# After (Mail.Land)
SMTP_HOST=smtp.mail.land
SMTP_PORT=587          # STARTTLS
SMTP_USER=apikey       # any value; Mail.Land ignores it
SMTP_PASS=ml_pet_...   # a Mail.Land key with SMTP enabled

مفاهیم Mailgun در Mail.Land

مفاهیم Mailgun در Mail.Land
Mailgun	Mail.Land
دامنه ارسال	دامنه تأییدشده (SPF، DKIM، DMARC و مسیر بازگشت)
کلید API و کلیدهای ارسال دامنه	کلیدهای API (اعتبارنامه‌ها)، که هر کدام به API یا SMTP، به دامنه‌ها و به نشانی‌های IP محدود می‌شوند
اعتبارنامه‌های SMTP برای هر دامنه	همان کلید API، که به‌عنوان گذرواژه SMTP به کار می‌رود
قالب‌ها (Handlebars)	قالب‌هایی با جای‌نگهدارهای {{name}}
فهرست‌های برگشتی‌ها، شکایت‌ها و لغو اشتراک‌ها	فهرست عدم ارسال با نوع و دامنه شمول
وب‌هوک‌ها	وب‌هوک‌های امضاشده با HMAC-SHA256، با یک کلید مخفی برای هر وب‌هوک
مسیرها (Routes)	مسیرهای ورودی

کلیدهای API مناسب را بسازید

پیشوند هر کلید Mail.Land حالت و جریان آن را نشان می‌دهد. برای هر برنامه و هر جریان یک کلید بسازید و کلیدهای تولیدی را از سامانه‌های آزمایشی دور نگه دارید.

کلیدهای API مناسب را بسازید
پیشوند	کاربرد
`ml_pet_`	تولیدی، تراکنشی: رسیدها، بازنشانی گذرواژه، هشدارها. حداکثر ۵ گیرنده در هر درخواست.
`ml_pem_`	تولیدی، بازاریابی: خبرنامه‌ها و ارسال انبوه با send-batch، حداکثر ۱۰٬۰۰۰ گیرنده در هر فراخوانی.
`ml_set_`	آزمایشی، تراکنشی: با sandboxBehavior برابر LogOnly (پیش‌فرض)، درخواست‌ها پذیرفته و ثبت می‌شوند اما هرگز تحویل داده نمی‌شوند. از آن برای آزمون‌های یکپارچه‌سازی استفاده کنید.

هر کلید را می‌توان به API، به SMTP یا هر دو، به دامنه‌های انتخابی و به نشانی‌های IP شناخته‌شده محدود کرد. هر کلید فقط یک بار نمایش داده می‌شود و Mail.Land تنها درهم‌سازی (hash) آن را نگه می‌دارد.

مستندات کلیدهای API

تغییر SMTP: میزبان و گذرواژه را عوض کنید

Mailgun برای هر دامنه ارسال یک نام کاربری SMTP دارد. Mail.Land کلید API شما را به‌عنوان گذرواژه به کار می‌برد و نام کاربری را نادیده می‌گیرد.

تغییر SMTP: میزبان و گذرواژه را عوض کنید
تنظیم	Mailgun	Mail.Land
میزبان	smtp.mailgun.org	smtp.mail.land
درگاه	25، 587 یا 2525 با STARTTLS، یا 465 با TLS	587 با STARTTLS
نام کاربری	نام کاربری SMTP دامنه ارسال شما	هر مقداری، برای نمونه apikey
گذرواژه	گذرواژه همان نام کاربری SMTP	یک کلید API از Mail.Land با SMTP فعال (ml_pet_ برای ایمیل تراکنشی)

Mail.Land ورود را فقط پس از STARTTLS می‌پذیرد و درگاه 465 ارائه نمی‌شود. اگر برنامه شما از 465 استفاده می‌کند، آن را به 587 با STARTTLS تغییر دهید. اندازه هر پیام می‌تواند تا ۱۵ مبی‌بایت باشد.

مستندات رله SMTP

تغییر فراخوانی API

Mailgun فیلدهای فرم را با احراز هویت HTTP Basic می‌پذیرد. Mail.Land بدنه JSON را با سرآیند X-API-Key می‌پذیرد. در اینجا یک پیام یکسان را در هر دو API و یک ارسال دسته‌ای را می‌بینید.

curl -s --user "api:$MAILGUN_API_KEY" \
  https://api.mailgun.net/v3/yourdomain.com/messages \
  -F from="Your Shop <[email protected]>" \
  -F to="Jane <[email protected]>" \
  -F subject="Order 12345 has shipped" \
  -F text="Your order is on its way." \
  -F html="<p>Your order is on its way.</p>" \
  -F h:Reply-To="[email protected]" \
  -F o:tag="order-shipped"

curl -X POST https://api.mail.land/v1/transactional/send \
  -H "X-API-Key: $MAILLAND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": { "email": "[email protected]", "name": "Your Shop" },
    "to": [{
      "email": "[email protected]", "name": "Jane",
      "variables": { "orderNumber": "12345" }
    }],
    "replyTo": "[email protected]",
    "subject": "Order {{orderNumber}} has shipped",
    "textContent": "Your order {{orderNumber}} is on its way.",
    "htmlContent": "<p>Your order {{orderNumber}} is on its way.</p>",
    "tags": ["order-shipped"]
  }'
# MAILLAND_API_KEY=ml_pet_...  (production, transactional)

نگاشت فیلدهای فراخوانی ارسال

از POST /v3/<domain>/messages به POST /v1/transactional/send.

نگاشت فیلدهای فراخوانی ارسال
Mailgun	Mail.Land	توضیح
`--user api:<key> (احراز هویت Basic)`	`X-API-Key: <key>`	یک سرآیند به‌جای احراز هویت Basic، و بدنه JSON به‌جای فیلدهای فرم.
`from`	`from.email, from.name`	نام نمایشی را از نشانی جدا کنید. نشانی باید روی دامنه‌ای تأییدشده باشد.
`to`	`to[].email, to[].name`	حداکثر ۵ گیرنده در هر درخواست با کلید تراکنشی؛ هر گیرنده نسخه‌ای جداگانه دریافت می‌کند.
`cc, bcc`	`ندارد`	پشتیبانی نمی‌شود. برای هر گیرنده پیامی جداگانه بفرستید.
`subject`	`subject`	الزامی است، مگر اینکه از قالب استفاده کنید.
`text`	`textContent`
`html`	`htmlContent`
`amp-html`	`ندارد`	بخش AMP وجود ندارد.
`template, t:version`	`templateId`	ابتدا قالب را در Mail.Land از نو بسازید. قالب‌ها نسخه ندارند.
`t:variables`	`variables`	مقدارهای مشترک برای همه گیرندگان، به‌صورت یک شیء JSON به‌جای رشته JSON.
`v:<name> (metadata)`	`tags`	Mail.Land روی رویدادها فراداده کلید و مقدار ندارد. یک شناسه را در tags یا یک سرآیند سفارشی منتقل کنید.
`recipient-variables`	`to[].variables`	مقدارهای مخصوص هر گیرنده. برای بیش از ۵ گیرنده، از send-batch با کلید بازاریابی و recipients[].variables استفاده کنید.
`o:tag`	`tags`	آرایه‌ای از رشته‌ها.
`h:<Header-Name>`	`customHeaders`	شیئی از نام‌ها و مقدارهای سرآیند.
`h:Reply-To`	`replyTo`	یک رشته ساده نشانی.
`attachment, inline`	`attachments[].fileName, contentType, content, contentId, inline`	محتوای Base64 در JSON به‌جای فایل‌های multipart. حداکثر ۱۰ پیوست و در مجموع ۱۰ مبی‌بایت.
`o:deliverytime`	`scheduledAt`	تاریخ و زمان UTC با قالب ISO 8601، تا ۷ روز جلوتر.
`o:tracking-opens, o:tracking-clicks`	`tracking.opens, tracking.clicks`	مقدارهای بولی. انتخاب خود دامنه برای ردیابی باز شدن اولویت دارد.
`معادلی ندارد`	`سرآیند X-Idempotency-Key`	در بازه نگهداری، تکرار درخواست با همان کلید پاسخ اصلی را برمی‌گرداند و دوباره ارسال نمی‌کند.

Mail.Land با 202 Accepted پاسخ می‌دهد، همراه با یک jobId، یک شناسه پیام برای هر گیرنده پذیرفته‌شده و فهرست گیرندگان پذیرفته‌شده و ردشده.

مستندات REST API

دامنه و رکوردهای DNS خود را بیفزایید

دامنه را در Mail.Land بیفزایید و رکوردهایی را که داشبورد نشان می‌دهد منتشر کنید. SPF، DKIM و DMARC باید پیش از ارسال تأیید شوند. می‌توانید این کار را در حالی انجام دهید که Mailgun هنوز ارسال می‌کند.

دامنه و رکوردهای DNS خود را بیفزایید
رکورد	نام	مقدار	توضیح
SPF (TXT)	`yourdomain.com`	`include:spf.mlnd.net`	include را به رکورد SPF فعلی خود بیفزایید. هر دامنه باید فقط یک رکورد SPF داشته باشد.
DKIM (TXT)	`mlnd._domainkey.yourdomain.com`	`v=DKIM1; k=rsa; p=...`	انتخابگر (selector) برابر mlnd است، بنابراین این رکورد در کنار رکورد DKIM Mailgun قرار می‌گیرد.
DMARC (TXT)	`_dmarc.yourdomain.com`	`v=DMARC1; p=...`	الزامی است. فقط یک رکورد DMARC نگه دارید؛ رکورد موجودی که سیاست داشته باشد کافی است.
مسیر بازگشت (CNAME)	`bounce.yourdomain.com`	`bounce.mlnd.net`	آن را روی DNS only و بدون پراکسی تنظیم کنید. بررسی کنید این نام از قبل استفاده نشده باشد.

رکوردهای DNS Mailgun را تا پایان انتقال نگه دارید و فقط پس از رفتن آخرین پیام آن حذفشان کنید.

مستندات راه‌اندازی DNS

ابتدا فهرست‌های عدم ارسال را وارد کنید

Mailgun برگشتی‌ها، شکایت‌ها و لغو اشتراک‌ها را برای هر دامنه ارسال جداگانه نگه می‌دارد، پس فهرست‌های همه دامنه‌هایی را که از آن‌ها می‌فرستید خروجی بگیرید، برای نمونه با GET /v3/<domain>/bounces. سپس هر فهرست را با نوع و دامنه شمول متناظر، در داشبورد یا با POST /v1/transactional/suppressions/import، به Mail.Land وارد کنید.

ابتدا فهرست‌های عدم ارسال را وارد کنید
فهرست Mailgun	نوع در Mail.Land	دامنه شمول
برگشتی‌ها (Bounces)	`HardBounce`	Global
شکایت‌ها (Complaints)	`Complaint`	Global
لغو اشتراک‌ها (همه ایمیل‌ها)	`Unsubscribe`	Global
لغو اشتراک برای یک برچسب یا فهرست پستی	`Unsubscribe`	Marketing؛ یا List، که فقط برای کارزارهای ارسال‌شده به فهرست پستی متناظر در Mail.Land اعمال می‌شود

پیش از نخستین ارسال از طریق Mail.Land وارد کنید تا کسانی که انصراف داده‌اند از همان ابتدا در فهرست عدم ارسال بمانند. نشانی‌هایی که از قبل وجود دارند نادیده گرفته می‌شوند و تکراری نمی‌شوند.

مستندات فهرست عدم ارسال

وب‌هوک‌های خود را به Mail.Land هدایت کنید

نقطه پایانی خود را در Mail.Land بیفزایید، رویدادها را انتخاب کنید و سرآیند X-MLND-Signature را بررسی کنید. Mailgun یک برچسب زمانی و یک توکن را با یک کلید واحد برای کل حساب امضا می‌کند؛ Mail.Land برچسب زمانی و بدنه خام را با کلید مخفی هر وب‌هوک امضا می‌کند، پس کد بررسی امضا را هم به‌روز کنید.

وب‌هوک‌های خود را به Mail.Land هدایت کنید
رویداد Mailgun	رویداد Mail.Land	توضیح
`accepted`	`فعلاً ندارد`	message.sent هنوز در دسترس نیست؛ پاسخ 202 پذیرش را تأیید می‌کند.
`delivered`	`message.delivered`
`temporary_fail`	`message.deferred`
`permanent_fail`	`message.bounced`	رد شدن از سوی سرور گیرنده. message.failed توقفی را گزارش می‌کند که از سوی Mail.Land است.
`complained`	`message.complained`
`unsubscribed`	`message.unsubscribed`	برای لغو اشتراک خود گیرنده فرستاده می‌شود، نه برای تغییراتی که شما از طریق API انجام می‌دهید.
`opened, clicked`	`هنوز در دسترس نیست`	رویدادهای باز شدن و کلیک در فهرست رویدادها آمده‌اند اما امروز فرستاده نمی‌شوند.

بر اساس event_id تکرارها را حذف کنید، زیرا تحویل دوباره همان شناسه رویداد را دارد. وضعیت ممکن است بعداً اصلاح شود، پس پس از رویداد نهایی هم پردازش رویدادها را ادامه دهید و status_version را مقایسه کنید.

رویدادهای وب‌هوک

بررسی امضای وب‌هوک

قالب‌های خود را از نو بسازید

هر قالب را در داشبورد Mail.Land یا با API قالب‌ها بسازید و سپس آن را با templateId و variables بفرستید. هر جای‌نگهدار باید مقداری داشته باشد، وگرنه ارسال با کد 422 و نام موارد ناموجود رد می‌شود.

قالب‌های خود را از نو بسازید
Mailgun	Mail.Land
`{{firstName}}`	`{{firstName}}`
`%recipient.firstName%`	`{{firstName}}`
`{{#if}}, {{#unless}}, {{#each}}, {{#with}}, {{#equal}}`	`ندارد`
`نسخه‌های قالب (t:version)`	`ندارد`

جای‌نگهدارهای Mail.Land ساده‌اند: بدون شرط، حلقه، فیلتر یا partial. آن منطق را به برنامه خود منتقل کنید یا برای هر حالت یک قالب جداگانه نگه دارید.

مستندات قالب‌ها

انتقال گام‌به‌گام

دامنه ارسال خود را در Mail.Land بیفزایید و تأیید کنید و include:spf.mlnd.net را به رکورد SPF فعلی خود بیفزایید.
فهرست‌های عدم ارسال هر دامنه Mailgun را خروجی بگیرید و وارد کنید.
قالب‌ها و وب‌هوک‌های خود را از نو بسازید.
یک کلید آزمایشی با sandboxBehavior برابر LogOnly بسازید و آزمون‌های یکپارچه‌سازی خود را بدون تحویل ایمیل روی Mail.Land اجرا کنید.
پیام‌های واقعی به نشانی‌هایی که در اختیار دارید بفرستید و آن‌ها را در گزارش ایمیل بررسی کنید.
یک برنامه یا سهم کوچکی از ترافیک را منتقل کنید و سپس تحویل، برگشتی‌ها و شکایت‌ها را زیر نظر بگیرید.
تا وقتی هر دو ارائه‌دهنده فعال‌اند، انصراف‌ها را در هر دو سو همگام نگه دارید: لغو اشتراک‌ها، شکایت‌ها و برگشتی‌های جدید را از Mailgun به Mail.Land و از Mail.Land به Mailgun کپی کنید و پیش از انتقال باقی ترافیک یک همگام‌سازی نهایی انجام دهید.
گرم‌کردن دامنه را بررسی کنید: در Free و Pro، دامنه تازه سقف روزانه‌ای دارد که مرحله‌به‌مرحله بالا می‌رود و ارسال‌های بیش از آن رد می‌شوند. انتقال را در همین حدود برنامه‌ریزی کنید یا درباره برنامه سفارشی از ما بپرسید. طرح Max مرحله گرم‌کردن ندارد.
سپس باقی ترافیک را منتقل کنید و Mailgun را تا رفتن آخرین پیام‌های زمان‌بندی‌شده و تکرارشده آن فعال نگه دارید.

Mail.Land در برابر Mailgun: مقایسه مستند

منابع

صفحه‌های عمومی Mailgun که در این راهنما استفاده شده‌اند.

[۱]Mailgun API: ارسال پیامhttps://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/messages/post-v3--domain-name--messagesبررسی‌شده در ۱۳ آبان ۱۴۰۵
[۲]Mailgun API: احراز هویتhttps://documentation.mailgun.com/docs/mailgun/api-reference/authenticationبررسی‌شده در ۱۳ آبان ۱۴۰۵
[۳]Mailgun: ارسال با SMTPhttps://documentation.mailgun.com/docs/mailgun/user-manual/sending-messages/send-smtpبررسی‌شده در ۱۳ آبان ۱۴۰۵
[۴]Mailgun: ارسال با قالبhttps://documentation.mailgun.com/docs/mailgun/user-manual/sending-messages/send-templatesبررسی‌شده در ۱۳ آبان ۱۴۰۵
[۵]Mailgun: وب‌هوک‌هاhttps://documentation.mailgun.com/docs/mailgun/user-manual/webhooks/webhooksبررسی‌شده در ۱۳ آبان ۱۴۰۵
[۶]Mailgun: ایمن‌سازی وب‌هوک‌هاhttps://documentation.mailgun.com/docs/mailgun/user-manual/webhooks/securing-webhooksبررسی‌شده در ۱۳ آبان ۱۴۰۵
[۷]Mailgun API: برگشتی‌هاhttps://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/bounces/get-v3--domainid--bouncesبررسی‌شده در ۱۳ آبان ۱۴۰۵

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

آیا هنگام آزمایش می‌توانم همچنان از طریق Mailgun ارسال کنم؟

بله. تأیید دامنه در Mail.Land جلوی ارسال Mailgun برای آن دامنه را نمی‌گیرد، پس می‌توانید هر دو را اجرا کنید و ترافیک را به‌تدریج منتقل کنید.

Mailgun امکان انتخاب منطقه آمریکا یا اتحادیه اروپا را می‌دهد. Mail.Land کجا اجرا می‌شود؟

Mail.Land منطقه‌ای برای انتخاب ندارد. نسخه اصلی داده‌های شما در آلمان است؛ ارائه‌دهندگان بیرون از اتحادیه اروپا در صفحه GDPR ما فهرست شده‌اند.

چگونه هم‌زمان برای گیرندگان زیادی بفرستم؟

از POST /v1/transactional/send-batch با کلید بازاریابی (ml_pem_) استفاده کنید. این نقطه پایانی تا ۱۰٬۰۰۰ گیرنده را، هر کدام با متغیرهای خود، می‌پذیرد. کلید تراکنشی حداکثر ۵ گیرنده در هر درخواست می‌پذیرد.

آیا SDK رسمی برای Mail.Land وجود دارد؟

هنوز نه. مستندات نمونه‌کدهای آماده REST API را برای cURL، Node.js، Python، PHP، C#، Java و Go دارد و هر کتابخانه SMTP با رله کار می‌کند.

آماده انتقال از Mailgun هستید؟

یک حساب رایگان بسازید و همین امروز نخستین ایمیل آزمایشی خود را بفرستید. اگر کمک می‌خواهید، درباره تنظیمات خود به ما بگویید.

رایگان شروع کنید درخواست کمک برای مهاجرت