راهنمای مهاجرت
مهاجرت از SendGrid به Mail.Land
اغلب تغییر لازم فقط یک میزبان SMTP یا یک فراخوانی API است. این راهنما فیلدهای رایج SendGrid را به Mail.Land نگاشت میکند و تفاوتهایی را که به تغییر کد نیاز دارند فهرست میکند.
# 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 |
|---|---|
| کلید 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 آن را نادیده میگیرد و فقط با کلید احراز هویت میکند.
| تنظیم | SendGrid | Mail.Land |
|---|---|---|
| میزبان | smtp.sendgrid.net | smtp.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 تغییر دهید.
جابهجایی فراخوانی 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.
| SendGrid | Mail.Land | توضیح |
|---|---|---|
Authorization: Bearer <key> | X-API-Key: <key> | سرآیندی متفاوت. |
from.email, from.name | from.email, from.name | نشانی باید روی یک دامنه تأییدشده باشد. |
personalizations[].to[] | to[] | با کلید تراکنشی، حداکثر ۵ گیرنده در هر درخواست. برای ارسال انبوه، از ارسال دستهای با کلید بازاریابی استفاده کنید. |
personalizations[].cc, bcc | ندارد | پشتیبانی نمیشود. برای هر گیرنده پیامی جداگانه بفرستید. |
personalizations[].dynamic_template_data | to[].variables | مقادیر مخصوص هر گیرنده. برای مقادیری که میان همه گیرندگان مشترک است، از variables در سطح بالا استفاده کنید. |
subject | subject | الزامی است، مگر اینکه از قالب استفاده کنید. |
content[] (text/html) | htmlContent | |
content[] (text/plain) | textContent | |
template_id | templateId | ابتدا قالب را در Mail.Land دوباره بسازید؛ شناسه آن تغییر میکند. |
reply_to.email | replyTo | یک رشته ساده حاوی نشانی. |
categories, custom_args | tags | برچسبها در تحلیلها و رویدادهای وبهوک نمایش داده میشوند. |
headers | customHeaders | |
attachments[].content, filename, type | attachments[].content, fileName, contentType | محتوای Base64. حداکثر ۱۰ پیوست و در مجموع ۱۰ MiB. |
attachments[].disposition, content_id | attachments[].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، یک شناسه پیام برای هر گیرنده و فهرست گیرندگان پذیرفتهشده و ردشده است.
ابتدا فهرستهای عدم ارسال خود را وارد کنید
پیش از نخستین ارسال از طریق Mail.Land آنها را وارد کنید تا کسانی که اشتراک خود را لغو کردهاند یا شکایت کردهاند از همان ابتدا در فهرست عدم ارسال بمانند. هر فهرست را از SendGrid بهصورت CSV خروجی بگیرید و سپس آن را با نوع و دامنه شمول متناظر، در داشبورد یا با POST /v1/transactional/suppressions/import، وارد کنید.
| فهرست SendGrid | نوع در Mail.Land | دامنه شمول |
|---|---|---|
| برگشتیها (Bounces) | HardBounce | Global |
| گزارشهای هرزنامه (Spam reports) | Complaint | Global |
| ایمیلهای نامعتبر (Invalid emails) | Invalid | Global |
| لغو اشتراکهای سراسری (Global unsubscribes) | Unsubscribe | Global |
| لغو اشتراکهای گروهی (Group unsubscribes) | Unsubscribe | List، برای فهرست پستی متناظر در Mail.Land؛ Marketing همه ایمیلهای بازاریابی را مسدود میکند |
مسدودیهای SendGrid (blocks) معمولاً امتناعهای موقت هستند. بهجای اینکه همه آنها را در فهرست عدم ارسال قرار دهید، پیش از وارد کردن بازبینیشان کنید.
وبهوکهای خود را به Mail.Land هدایت کنید
نقطه پایانی خود را در Mail.Land اضافه کنید، رویدادها را انتخاب کنید و سرآیند X-MLND-Signature را با کلید مخفی وبهوک خود تأیید کنید. نام رویدادها با SendGrid متفاوت است، پس کنترلکننده (handler) خود را بهروز کنید:
| رویداد SendGrid | رویداد Mail.Land |
|---|---|
delivered | message.delivered |
deferred | message.deferred |
bounce | message.bounced |
open, click | هنوز در دسترس نیست |
spamreport | message.complained |
unsubscribe | message.unsubscribed |
تکراریها را بر اساس فیلد event_id حذف کنید: تحویلی که دوباره تلاش میشود همان شناسه رویداد را دارد. رویدادهای open و click در SendGrid امروز وبهوک معادلی در Mail.Land ندارند: رویدادهای باز شدن و کلیک در فهرست رویدادها آمدهاند اما فرستاده نمیشوند.
جابهجایی گامبهگام
- دامنه ارسال خود را در Mail.Land اضافه و تأیید کنید. رکوردهای SendGrid را نگه دارید: بهجای ساختن رکورد SPF دوم، include:spf.mlnd.net را به رکورد SPF فعلی خود اضافه کنید و فقط یک رکورد DMARC داشته باشید.
- فهرستهای عدم ارسال خود را وارد کنید.
- یک کلید sandbox با حالت «فقط ثبت» (log only) بسازید و آزمونهای یکپارچگی خود را بدون تحویل ایمیل روی Mail.Land اجرا کنید.
- پیامهای واقعی به نشانیهایی بفرستید که در اختیار خودتان است و آنها را در گزارش ایمیلها بررسی کنید.
- یک برنامه یا بخش کوچکی از ترافیک را منتقل کنید، سپس تحویل، برگشتها و شکایتها را زیر نظر بگیرید.
- تا زمانی که هر دو ارائهدهنده فعال هستند، لغو اشتراکها، شکایتها و برگشتهای جدید را از SendGrid به Mail.Land منتقل کنید و پیش از انتقال آخرین بخش ترافیک، یک همگامسازی نهایی انجام دهید.
- بقیه را منتقل کنید و SendGrid را تا ارسال آخرین پیامهای زمانبندیشده و تلاشهای مجدد آن فعال نگه دارید.
پرسشهای متداول
آیا در طول آزمایش میتوانم ارسال از طریق SendGrid را ادامه دهم؟
بله. تأیید یک دامنه در Mail.Land مانع ارسال SendGrid برای آن دامنه نمیشود، بنابراین میتوانید هر دو را همزمان اجرا کنید و ترافیک را بهتدریج منتقل کنید.
آیا Mail.Land از cc و bcc پشتیبانی میکند؟
در فراخوانی ارسال، خیر. بهجای آن برای هر گیرنده پیامی جداگانه بفرستید.
آیا SDK رسمی برای Mail.Land وجود دارد؟
هنوز نه. مستندات برای REST API نمونههای آماده کپی به هشت زبان دارد و هر کتابخانه SMTP با رله کار میکند.
گروههای لغو اشتراک من چه میشوند؟
لغو اشتراکهای هر گروه را با دامنه شمول List برای فهرست پستی متناظر در Mail.Land وارد کنید و به همان فهرست ارسال کنید تا این ترجیح اعمال شود. دامنه شمول Marketing گزینه جایگزین گستردهتر است: همه ایمیلهای بازاریابی به آن نشانی را مسدود میکند.
آماده جابهجایی از SendGrid هستید؟
یک حساب رایگان بسازید و همین امروز نخستین ایمیل آزمایشی خود را بفرستید. اگر به کمک نیاز دارید، درباره پیکربندی خود به ما بگویید.