پرش به محتوای اصلی
MailLand

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

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

اغلب تغییر لازم فقط یک میزبان SMTP یا یک فراخوانی API است. این راهنما فیلدهای رایج SendGrid را به Mail.Land نگاشت می‌کند و تفاوت‌هایی را که به تغییر کد نیاز دارند فهرست می‌کند.

SMTP
# Before (SendGrid)
SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_USER=apikey
SMTP_PASS=<your SendGrid API key>

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

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

مفاهیم SendGrid در Mail.Land
SendGridMail.Land
کلید APIکلید API (اعتبارنامه)، محدود به API یا SMTP، به دامنه‌ها و به نشانی‌های IP
احراز هویت فرستنده (Sender authentication)تأیید دامنه (SPF، DKIM، DMARC و return path)
قالب‌های پویا (Dynamic templates)قالب‌هایی با جای‌نگهدارهای {{name}}
فهرست‌های عدم ارسال و گروه‌های لغو اشتراک (Suppressions و unsubscribe groups)فهرست عدم ارسال با دامنه شمول: همه ایمیل‌ها، فقط بازاریابی، یا یک فهرست پستی
Event Webhookوب‌هوک‌های امضاشده با HMAC-SHA256
Inbound Parseمسیرهای ورودی (Inbound routes)

جابه‌جایی SMTP: سه تنظیم را تغییر دهید

اگر از طریق SMTP ارسال می‌کنید، میزبان، درگاه و گذرواژه را تغییر دهید. نام کاربری می‌تواند همان apikey بماند، زیرا Mail.Land آن را نادیده می‌گیرد و فقط با کلید احراز هویت می‌کند.

جابه‌جایی SMTP: سه تنظیم را تغییر دهید
تنظیمSendGridMail.Land
میزبانsmtp.sendgrid.netsmtp.mail.land
درگاه25، 587 یا 2525 (TLS)، یا 465 (SSL)587 با STARTTLS
نام کاربریapikeyهر مقداری، برای نمونه apikey
گذرواژهکلید API شما در SendGridیک کلید API از Mail.Land که SMTP برای آن فعال است

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

مستندات رله SMTP

جابه‌جایی فراخوانی API

فراخوانی ارسال در Mail.Land از بدنه JSON تخت‌تر و سرآیند X-API-Key استفاده می‌کند. در ادامه همان پیام را در هر دو API می‌بینید.

curl -X POST https://api.sendgrid.com/v3/mail/send \
  -H "Authorization: Bearer $SENDGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "personalizations": [{
      "to": [{ "email": "[email protected]", "name": "Jane" }],
      "dynamic_template_data": { "orderNumber": "12345" }
    }],
    "from": { "email": "[email protected]", "name": "Your Shop" },
    "reply_to": { "email": "[email protected]" },
    "subject": "Order 12345 has shipped",
    "content": [
      { "type": "text/plain", "value": "Your order is on its way." },
      { "type": "text/html", "value": "<p>Your order is on its way.</p>" }
    ],
    "categories": ["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 '{
    "to": [{
      "email": "[email protected]", "name": "Jane",
      "variables": { "orderNumber": "12345" }
    }],
    "from": { "email": "[email protected]", "name": "Your Shop" },
    "replyTo": "[email protected]",
    "subject": "Order 12345 has shipped",
    "textContent": "Your order is on its way.",
    "htmlContent": "<p>Your order is on its way.</p>",
    "tags": ["order-shipped"]
  }'

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

از POST /v3/mail/send به POST /v1/transactional/send.

نگاشت فیلدهای فراخوانی ارسال
SendGridMail.Landتوضیح
Authorization: Bearer <key>X-API-Key: <key>سرآیندی متفاوت.
from.email, from.namefrom.email, from.nameنشانی باید روی یک دامنه تأییدشده باشد.
personalizations[].to[]to[]با کلید تراکنشی، حداکثر ۵ گیرنده در هر درخواست. برای ارسال انبوه، از ارسال دسته‌ای با کلید بازاریابی استفاده کنید.
personalizations[].cc, bccنداردپشتیبانی نمی‌شود. برای هر گیرنده پیامی جداگانه بفرستید.
personalizations[].dynamic_template_datato[].variablesمقادیر مخصوص هر گیرنده. برای مقادیری که میان همه گیرندگان مشترک است، از variables در سطح بالا استفاده کنید.
subjectsubjectالزامی است، مگر اینکه از قالب استفاده کنید.
content[] (text/html)htmlContent
content[] (text/plain)textContent
template_idtemplateIdابتدا قالب را در Mail.Land دوباره بسازید؛ شناسه آن تغییر می‌کند.
reply_to.emailreplyToیک رشته ساده حاوی نشانی.
categories, custom_argstagsبرچسب‌ها در تحلیل‌ها و رویدادهای وب‌هوک نمایش داده می‌شوند.
headerscustomHeaders
attachments[].content, filename, typeattachments[].content, fileName, contentTypeمحتوای Base64. حداکثر ۱۰ پیوست و در مجموع ۱۰ MiB.
attachments[].disposition, content_idattachments[].inline, contentIdبرای تصویر درون‌خطی، inline: true.
send_at (زمان Unix، حداکثر ۷۲ ساعت آینده)scheduledAt (تاریخ و زمان UTC، حداکثر ۷ روز آینده)
tracking_settings (open, click)tracking.opens, tracking.clicksبرای باز شدن‌ها، تنظیمات ردیابی خود دامنه اولویت دارد.
asm.group_idدر فراخوانی ارسال وجود نداردلغو اشتراک‌های بازاریابی با فهرست‌ها و کمپین‌های Mail.Land مدیریت می‌شوند. لغو اشتراک‌های گروهی موجود را وارد کنید؛ توضیح آن در ادامه آمده است.
معادلی نداردسرآیند X-Idempotency-Keyدر بازه نگهداری، تلاش مجدد با همان کلید به‌جای ارسال دوباره، پاسخ اصلی را برمی‌گرداند.

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

مستندات REST API

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

پیش از نخستین ارسال از طریق Mail.Land آن‌ها را وارد کنید تا کسانی که اشتراک خود را لغو کرده‌اند یا شکایت کرده‌اند از همان ابتدا در فهرست عدم ارسال بمانند. هر فهرست را از SendGrid به‌صورت CSV خروجی بگیرید و سپس آن را با نوع و دامنه شمول متناظر، در داشبورد یا با POST /v1/transactional/suppressions/import، وارد کنید.

ابتدا فهرست‌های عدم ارسال خود را وارد کنید
فهرست SendGridنوع در Mail.Landدامنه شمول
برگشتی‌ها (Bounces)HardBounceGlobal
گزارش‌های هرزنامه (Spam reports)ComplaintGlobal
ایمیل‌های نامعتبر (Invalid emails)InvalidGlobal
لغو اشتراک‌های سراسری (Global unsubscribes)UnsubscribeGlobal
لغو اشتراک‌های گروهی (Group unsubscribes)UnsubscribeList، برای فهرست پستی متناظر در Mail.Land؛ Marketing همه ایمیل‌های بازاریابی را مسدود می‌کند

مسدودی‌های SendGrid (blocks) معمولاً امتناع‌های موقت هستند. به‌جای اینکه همه آن‌ها را در فهرست عدم ارسال قرار دهید، پیش از وارد کردن بازبینی‌شان کنید.

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

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

نقطه پایانی خود را در Mail.Land اضافه کنید، رویدادها را انتخاب کنید و سرآیند X-MLND-Signature را با کلید مخفی وب‌هوک خود تأیید کنید. نام رویدادها با SendGrid متفاوت است، پس کنترل‌کننده (handler) خود را به‌روز کنید:

وب‌هوک‌های خود را به Mail.Land هدایت کنید
رویداد SendGridرویداد Mail.Land
deliveredmessage.delivered
deferredmessage.deferred
bouncemessage.bounced
open, clickهنوز در دسترس نیست
spamreportmessage.complained
unsubscribemessage.unsubscribed

تکراری‌ها را بر اساس فیلد event_id حذف کنید: تحویلی که دوباره تلاش می‌شود همان شناسه رویداد را دارد. رویدادهای open و click در SendGrid امروز وبهوک معادلی در Mail.Land ندارند: رویدادهای باز شدن و کلیک در فهرست رویدادها آمده‌اند اما فرستاده نمی‌شوند.

تأیید امضای وب‌هوک

جابه‌جایی گام‌به‌گام

  1. دامنه ارسال خود را در Mail.Land اضافه و تأیید کنید. رکوردهای SendGrid را نگه دارید: به‌جای ساختن رکورد SPF دوم، include:spf.mlnd.net را به رکورد SPF فعلی خود اضافه کنید و فقط یک رکورد DMARC داشته باشید.
  2. فهرست‌های عدم ارسال خود را وارد کنید.
  3. یک کلید sandbox با حالت «فقط ثبت» (log only) بسازید و آزمون‌های یکپارچگی خود را بدون تحویل ایمیل روی Mail.Land اجرا کنید.
  4. پیام‌های واقعی به نشانی‌هایی بفرستید که در اختیار خودتان است و آن‌ها را در گزارش ایمیل‌ها بررسی کنید.
  5. یک برنامه یا بخش کوچکی از ترافیک را منتقل کنید، سپس تحویل، برگشت‌ها و شکایت‌ها را زیر نظر بگیرید.
  6. تا زمانی که هر دو ارائه‌دهنده فعال هستند، لغو اشتراک‌ها، شکایت‌ها و برگشت‌های جدید را از SendGrid به Mail.Land منتقل کنید و پیش از انتقال آخرین بخش ترافیک، یک همگام‌سازی نهایی انجام دهید.
  7. بقیه را منتقل کنید و SendGrid را تا ارسال آخرین پیام‌های زمان‌بندی‌شده و تلاش‌های مجدد آن فعال نگه دارید.

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

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

بله. تأیید یک دامنه در Mail.Land مانع ارسال SendGrid برای آن دامنه نمی‌شود، بنابراین می‌توانید هر دو را هم‌زمان اجرا کنید و ترافیک را به‌تدریج منتقل کنید.

آیا Mail.Land از cc و bcc پشتیبانی می‌کند؟

در فراخوانی ارسال، خیر. به‌جای آن برای هر گیرنده پیامی جداگانه بفرستید.

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

هنوز نه. مستندات برای REST API نمونه‌های آماده کپی به هشت زبان دارد و هر کتابخانه SMTP با رله کار می‌کند.

گروه‌های لغو اشتراک من چه می‌شوند؟

لغو اشتراک‌های هر گروه را با دامنه شمول List برای فهرست پستی متناظر در Mail.Land وارد کنید و به همان فهرست ارسال کنید تا این ترجیح اعمال شود. دامنه شمول Marketing گزینه جایگزین گسترده‌تر است: همه ایمیل‌های بازاریابی به آن نشانی را مسدود می‌کند.

آماده جابه‌جایی از SendGrid هستید؟

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