انتقل إلى المحتوى الرئيسي
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 WebhookWebhook موقّعة باستخدام 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. وإليك الرسالة نفسها في الواجهتين.

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[]حتى 5 مستلمين في الطلب الواحد مع مفتاح معاملاتي. وللإرسال بالجملة، استخدم الإرسال على دفعات مع مفتاح تسويقي.
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تظهر الوسوم في التحليلات وفي أحداث Webhook.
headerscustomHeaders
attachments[].content, filename, typeattachments[].content, fileName, contentTypeمحتوى بترميز Base64. حتى 10 مرفقات و10 MiB إجمالاً.
attachments[].disposition, content_idattachments[].inline, contentIdinline: true للصورة المضمّنة.
send_at (توقيت Unix، حتى 72 ساعة مقدماً)scheduledAt (تاريخ ووقت UTC، حتى 7 أيام مقدماً)
tracking_settings (open, click)tracking.opens, tracking.clicksبالنسبة إلى تتبّع الفتح، تكون الأولوية لإعدادات التتبّع الخاصة بالنطاق.
asm.group_idلا يوجد في استدعاء الإرسالتُدار حالات إلغاء الاشتراك التسويقية عبر قوائم Mail.Land وحملاتها. استورد حالات إلغاء الاشتراك الجماعية الحالية، كما هو موضح أدناه.
لا يوجد مقابلترويسة X-Idempotency-Keyخلال فترة الاحتفاظ، تعيد المحاولة بالمفتاح نفسه الاستجابة الأصلية بدلاً من الإرسال مجدداً.

تجيب الواجهتان كلتاهما بـ 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 فيحظر كل البريد التسويقي

عمليات الحظر (blocks) في SendGrid غالباً ما تكون رفضاً مؤقتاً. راجعها قبل الاستيراد بدلاً من إدراجها كلها في قائمة منع الإرسال.

وثائق قوائم منع الإرسال

وجّه Webhook الخاصة بك إلى Mail.Land

أضف نقطة النهاية الخاصة بك في Mail.Land، واختر الأحداث، وتحقق من ترويسة X-MLND-Signature باستخدام سر الـ Webhook الخاص بك. تختلف أسماء الأحداث عن أسماء SendGrid، لذا حدّث المعالج (handler) لديك:

وجّه Webhook الخاصة بك إلى Mail.Land
حدث SendGridحدث Mail.Land
deliveredmessage.delivered
deferredmessage.deferred
bouncemessage.bounced
open, clickغير متاح بعد
spamreportmessage.complained
unsubscribemessage.unsubscribed

أزل التكرار بالاعتماد على الحقل event_id: إذ يحمل التسليم المعاد محاولته معرف الحدث نفسه. لا يوجد اليوم في Mail.Land webhook مقابل لحدثَي open وclick في SendGrid: أحداث الفتح والنقر مدرجة في الكتالوج لكنها لا تُرسل.

التحقق من توقيع Webhook

التحويل خطوة بخطوة

  1. أضف نطاق الإرسال الخاص بك في Mail.Land وتحقق منه. واحتفظ بسجلات SendGrid: أضف 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؟

أنشئ حساباً مجانياً وأرسل أول رسالة اختبارية اليوم. وإذا أردت المساعدة، فأخبرنا عن إعداداتك.