SendGrid

المقدمة

يرسل تكامل SendGrid رسالة بريد إلكتروني للمعاملات عبر SendGrid’s Mail Send API عند حدوث حدث في Dodo Payments. تستخدم كل رسالة أحد قوالب SendGrid الديناميكية، مع تعبئته بالبيانات الواردة من الحدث، بحيث يمكنك تأكيد الدفعات، والترحيب بالمشتركين الجدد، والمتابعة بشأن الدفعات الفاشلة.

يتطلب هذا التكامل مفتاح SendGrid API يتضمن إذن Mail Send، ومرسلًا تم التحقق منه في SendGrid، وقالبًا ديناميكيًا لكل رسالة بريد إلكتروني ترسلها. تحتاج أيضًا إلى الوصول إلى Developer → Webhooks في لوحة تحكم Dodo Payments.

البدء

Open the Webhook Section

في لوحة تحكم Dodo Payments، انتقل إلى Developer → Webhooks وانقر على Add endpoint.

Add endpoint dialog with SendGrid selected in the Integration dropdown and the How to connect SendGrid steps

Select SendGrid

في Integration، اختر SendGrid. تملأ لوحة التحكم Endpoint URL ورمز التحويل الخاص بـ SendGrid، ويعرض قسم How to connect SendGrid خطوات الإعداد.

Enter API Key

في SendGrid، انتقل إلى Settings → API Keys وانقر على Create API Key. اختر Restricted Access مع إذن Mail Send، أو Full Access. يعرض SendGrid المفتاح، الذي يبدأ بـ SG.، مرة واحدة فقط. الصقه في API key. يرسله Dodo Payments باعتباره bearer token في ترويسة Authorization لكل طلب إلى SendGrid.

Select Events

في Subscribed events، اختر فقط الأحداث التي يعالجها رمز التحويل الخاص بك. يصل الحدث الذي يتركه رمز التحويل دون تغيير إلى SendGrid بتنسيق Dodo Payments، ويرفضه SendGrid.

Configure Transformation

ضمن Transformation code، حرّر handler لتنسيق رسائل البريد الإلكتروني وفق SendGrid’s Mail Send API. ابدأ من الأمثلة، واستبدل كل template_id بمعرّف القالب الديناميكي الخاص بك، الذي يبدأ بـ d-.

Test & Create

ضمن Test this code، اختر نوع حدث وانقر على Simulate لمعاينة الطلب المرسل إلى SendGrid. ثم انقر على Create endpoint.

Done

يرسل Dodo Payments الآن رسالة بريد إلكتروني عبر SendGrid لكل حدث مشترك فيه. لرؤية كل عملية إرسال واستجابة SendGrid، افتح علامة التبويب Logs ضمن Developer → Webhooks.

أمثلة على Transformation Code

يعيّن كل handler webhook.url إلى Mail Send endpoint ويمرّر بيانات الحدث إلى قالب ديناميكي عبر dynamic_template_data. تكون مبالغ Dodo Payments بوحدة العملة الأصغر، لذلك تقسم الأمثلة المبلغ على 100. بالنسبة إلى العملات ذات المنازل العشرية الصفرية مثل JPY وKRW، استخدم المبلغ كما هو.

رسالة تأكيد الدفع

أرسل إيصالًا عند نجاح الدفع (payment.succeeded):

payment_confirmation.js

function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const p = webhook.payload.data;
    webhook.url = "https://api.sendgrid.com/v3/mail/send";
    webhook.payload = {
      personalizations: [
        {
          to: [{ email: p.customer.email }],
          dynamic_template_data: {
            customer_name: p.customer.name,
            payment_amount: (p.total_amount / 100).toFixed(2),
            payment_id: p.payment_id,
            payment_date: new Date(webhook.payload.timestamp).toLocaleDateString(),
            currency: p.currency || "USD"
          }
        }
      ],
      from: {
        email: "payments@yourdomain.com",
        name: "Your Company"
      },
      template_id: "d-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    };
  }
  return webhook;
}

رسالة ترحيب بالاشتراك

رحّب بالعميل عند تنشيط الاشتراك (subscription.active):

subscription_welcome.js

function handler(webhook) {
  if (webhook.eventType === "subscription.active") {
    const s = webhook.payload.data;
    webhook.url = "https://api.sendgrid.com/v3/mail/send";
    webhook.payload = {
      personalizations: [
        {
          to: [{ email: s.customer.email }],
          dynamic_template_data: {
            customer_name: s.customer.name,
            subscription_id: s.subscription_id,
            product_id: s.product_id,
            amount: (s.recurring_pre_tax_amount / 100).toFixed(2),
            frequency: s.payment_frequency_interval,
            next_billing: new Date(s.next_billing_date).toLocaleDateString()
          }
        }
      ],
      from: {
        email: "welcome@yourdomain.com",
        name: "Your Company"
      },
      template_id: "d-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    };
  }
  return webhook;
}

إشعار بفشل الدفع

اطلب من العميل إعادة المحاولة عند فشل الدفع (payment.failed):

payment_failure.js

function handler(webhook) {
  if (webhook.eventType === "payment.failed") {
    const p = webhook.payload.data;
    webhook.url = "https://api.sendgrid.com/v3/mail/send";
    webhook.payload = {
      personalizations: [
        {
          to: [{ email: p.customer.email }],
          dynamic_template_data: {
            customer_name: p.customer.name,
            payment_amount: (p.total_amount / 100).toFixed(2),
            error_message: p.error_message || "Payment processing failed",
            payment_id: p.payment_id,
            retry_link: `https://yourdomain.com/retry-payment/${p.payment_id}`
          }
        }
      ],
      from: {
        email: "support@yourdomain.com",
        name: "Your Company Support"
      },
      template_id: "d-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    };
  }
  return webhook;
}

نصائح

استخدم قوالب SendGrid الديناميكية لتخصيص المحتوى.
مرّر بيانات الدفع التي يحتاج إليها قالبك في dynamic_template_data.
عيّن عنوان from يطابق مرسلًا تم التحقق منه، وname للمرسل.
أعد استخدام معرّفات القوالب للحفاظ على التنسيق نفسه لرسائل البريد الإلكتروني من النوع نفسه.
أدرج رابط إلغاء الاشتراك في أي رسالة بريد إلكتروني تحتوي على محتوى تسويقي.
لتخطي حدث في التعليمة البرمجية، عيّن webhook.cancel = true قبل إرجاع webhook. تسجّل السجلات عملية التسليم المتخطاة باعتبارها ناجحة.

استكشاف الأخطاء وإصلاحها

Emails Not Being Sent

تحقّق من أن مفتاح API يتضمن إذن Mail Send. لاستبداله، حرّر endpoint والصق مفتاحًا جديدًا في API key.
تحقّق من أن كل template_id ينتمي إلى قالب ديناميكي نشط.
تحقّق من صلاحية عناوين البريد الإلكتروني للمستلمين.
تحقّق من حدود الإرسال والحصص في SendGrid ضمن خطتك.
افتح علامة التبويب Logs ضمن Developer → Webhooks واقرأ استجابة SendGrid لعملية التسليم الفاشلة.

Transformation Errors

تحقّق من أن payload يطابق تنسيق SendGrid’s Mail Send.
تحقّق من وجود جميع الحقول المطلوبة: personalizations مع عنوان to واحد على الأقل، وfrom.
تحقّق من أن المفاتيح في dynamic_template_data تطابق المتغيرات في قالبك، مثل {{customer_name}}.
تحقّق من أن كل عنوان from تم التحقق منه في SendGrid.

External Integrations

Messaging

Workflow Automation

CRM

Email

Analytics

Pricing

المقدمة

البدء

أمثلة على Transformation Code

رسالة تأكيد الدفع

رسالة ترحيب بالاشتراك

إشعار بفشل الدفع

نصائح

استكشاف الأخطاء وإصلاحها

​المقدمة

​البدء

​أمثلة على Transformation Code

​رسالة تأكيد الدفع

​رسالة ترحيب بالاشتراك

​إشعار بفشل الدفع

​نصائح

​استكشاف الأخطاء وإصلاحها

المقدمة

البدء

أمثلة على Transformation Code

رسالة تأكيد الدفع

رسالة ترحيب بالاشتراك

إشعار بفشل الدفع

نصائح

استكشاف الأخطاء وإصلاحها