إضافة تكامل SendGrid

SendGrid هي خدمة سحابية لتسليم رسائل البريد الإلكتروني الترويجية والتسويقية. يتيح ربط هذا التكامل لتطبيقك إرسال رسائل البريد الإلكتروني برمجيًا (على سبيل المثال، رسائل الترحيب أو إعادة تعيين كلمة المرور أو الإشعارات).

خطوات التكوين

بعد تحديد SendGrid من قائمة التكاملات، ستظهر نافذة منبثقة للتكوين. يجب عليك تقديم بيانات الاعتماد التالية لإنشاء الاتصال:

1. مفتاح API

هذا هو رمز المصادقة الذي تم إنشاؤه داخل حساب SendGrid الخاص بك.

الإدخال: الصق مفتاح API الخاص لـ SendGrid في حقل النص.
مساعدة: إذا لم يكن لديك واحد، انقر على رابط “أين أجد مفتاح API؟” المقدم في النافذة المنبثقة للحصول على إرشادات حول كيفية إنشائه.

2. البيئة

حدد سياق البيئة لهذا التكامل.

الإدخال: أدخل معرف البيئة (على سبيل المثال، Production أو Staging أو علامة تكوين محددة) في حقل البيئة.

إنهاء الاتصال

بمجرد ملء الحقول:

راجع شريط الحالة (يعرض حاليًا Not Connected).
انقر على الزر الأسود Add في أسفل اليمين لحفظ بيانات الاعتماد وتنشيط التكامل.

تكوين SendGrid

تكامل SendGrid

مرجع API تكامل SendGrid

تكوين SendGrid

تكوين مفتاح API لـ SendGrid

يكوّن مفتاح API لـ SendGrid لمشروع وبيئة محددين.

Mutation:

mutation {
  sendgrid_configureSendGrid (
    apiKey: "SG._api_key_here"
  )
}

إرسال رسائل البريد الإلكتروني

إرسال بريد إلكتروني بسيط

يرسل بريدًا إلكترونيًا إلى مستلم واحد أو عدة مستلمين.

Mutation:

mutation sendgrid_sendEmail {
  sendgrid_sendEmail (
    email: {
    from: {
        email: "sender@archie.com",
        name: "Sender Name"
      },
      subject: "Test Email",
      to: {
        email: "recipient@gmail.com",
        name: "Recipient Name"
      },
      content: {
        type: "text/html",
        value: "<h1>Hello World</h1><p>This is a test email.</p>"
      }
    }
  ) {
    messageId
    success
  }
}

Response:

{
  "data": {
    "sendgrid_sendEmail": {
      "messageId": "sent-1234567890",
      "success": true
    }
  }
}

إرسال بريد إلكتروني مع CC و BCC

Mutation:

mutation sendgrid_sendEmail {
  sendgrid_sendEmail (
    email: {
      from: {
        email: "sender@example.com"
        name: "Sender Name"
      }
      to: [
        {
          email: "recipient@example.com"
          name: "Recipient Name"
        }
      ]
      cc: [
        {
          email: "cc@example.com"
          name: "CC Recipient"
        }
      ]
      bcc: [
        {
          email: "bcc@example.com"
        }
      ]
      subject: "Email with CC and BCC"
      content: [
        {
          type: "text/html"
          value: "<h1>Hello</h1><p>This email has CC and BCC recipients.</p>"
        }
      ]
    }
  ) {
    messageId
    success
  }
}

إرسال بريد إلكتروني مع مرفقات

Mutation:

mutation sendgrid_sendEmail {
  sendgrid_sendEmail(
    email: {
      from: {
        email: "sender@example.com"
        name: "Sender Name"
      }
      to: [
        {
          email: "recipient@example.com"
          name: "Recipient Name"
        }
      ]
      subject: "Email with Attachment"
      content: [
        {
          type: "text/html"
          value: "<h1>Hello</h1><p>Please find attached file.</p>"
        }
      ]
      attachments: [
        {
          content: "SGVsbG8gV29ybGQ="
          type: "text/plain"
          filename: "document.txt"
          disposition: "attachment"
        }
      ]
    }
  ) {
    messageId
    success
  }
}

ملاحظة: يجب أن يكون حقل content في المرفقات مشفرًا بـ Base64.

إرسال بريد إلكتروني مع الفئات والعلامات

Mutation:

mutation sendgrid_sendEmail {
  sendgrid_sendEmail(
    email: {
      from: {
        email: "sender@example.com"
        name: "Sender Name"
      }
      to: [
        {
          email: "recipient@example.com"
          name: "Recipient Name"
        }
      ]
      subject: "Categorized Email"
      content: [
        {
          type: "text/html"
          value: "<h1>Hello</h1>"
        }
      ]
      categories: ["transactional", "notification"]
      tags: ["important", "urgent"]
    }
  ) {
    messageId
    success
  }
}

إرسال بريد إلكتروني مجدول

Mutation:

mutation sendgrid_sendEmail {
  sendgrid_sendEmail(
    email: {
      from: {
        email: "sender@example.com"
        name: "Sender Name"
      }
      to: [
        {
          email: "recipient@example.com"
          name: "Recipient Name"
        }
      ]
      subject: "Scheduled Email"
      content: [
        {
          type: "text/html"
          value: "<h1>Hello</h1>"
        }
      ]
      sendAt: "2025-12-25T10:00:00Z"
    }
  ) {
    messageId
    success
  }
}

إرسال بريد إلكتروني مع وسائط مخصصة

Mutation:

mutation sendgrid_sendEmail {
  sendgrid_sendEmail(
    email: {
      from: {
        email: "sender@example.com"
        name: "Sender Name"
      }
      to: [
        {
          email: "recipient@example.com"
          name: "Recipient Name"
        }
      ]
      subject: "Email with Custom Args"
      content: [
        {
          type: "text/html"
          value: "<h1>Hello</h1>"
        }
      ]
      customArgs: {
        orderId: "12345"
        userId: "67890"
        campaignId: "abc123"
      }
    }
  ) {
    messageId
    success
  }
}

إرسال رسائل بريد إلكتروني جماعية

إرسال رسائل بريد إلكتروني متعددة

Mutation:

mutation sendgrid_sendBulkEmail {
  sendgrid_sendBulkEmail(
    emails: {
      emails: [
        {
          from: {
            email: "sender@example.com"
            name: "Sender Name"
          }
          to: [
            {
              email: "recipient1@example.com"
              name: "Recipient 1"
            }
          ]
          subject: "Bulk Email 1"
          content: [
            {
              type: "text/html"
              value: "<h1>Email 1</h1>"
            }
          ]
        }
        {
          from: {
            email: "sender@example.com"
            name: "Sender Name"
          }
          to: [
            {
              email: "recipient2@example.com"
              name: "Recipient 2"
            }
          ]
          subject: "Bulk Email 2"
          content: [
            {
              type: "text/html"
              value: "<h1>Email 2</h1>"
            }
          ]
        }
      ]
    }
  ) {
    messageIds
    success
  }
}

Response:

{
  "data": {
    "sendgrid_sendBulkEmail": {
      "messageIds": ["sent-1234567890", "sent-1234567891"],
      "success": true
    }
  }
}

إرسال رسائل بريد إلكتروني بقوالب

إرسال بريد إلكتروني باستخدام قالب ديناميكي

Mutation:

mutation sendgrid_sendTemplate {
  sendgrid_sendTemplate(
    email: {
      from: {
        email: "sender@example.com"
        name: "Sender Name"
      }
      to: [
        {
          email: "recipient@example.com"
          name: "Recipient Name"
        }
      ]
      templateId: "d-1234567890abcdef"
      substitutions: {
        name: "John Doe"
        orderNumber: "12345"
        totalAmount: "$99.99"
      }
    }
  ) {
    messageId
    success
  }
}

Response:

{
  "data": {
    "sendgrid_sendTemplate": {
      "messageId": "sent-1234567890",
      "success": true
    }
  }
}

إدارة جهات الاتصال

إضافة جهة اتصال

Mutation:

mutation sendgrid_addContact {
  sendgrid_addContact(
    contact: {
      email: "newcontact@example.com"
      firstName: "John"
      lastName: "Doe"
      customFields: {
        company: "Acme Corp"
        phone: "+1234567890"
        position: "Developer"
      }
      listIds: ["list-id-1", "list-id-2"]
    }
  )
}

Response:

{
  "data": {
    "sendgrid_addContact": true
  }
}

تحديث جهة اتصال

Mutation:

mutation sendgrid_updateContact {
  sendgrid_updateContact(
    contact: {
      email: "existing@example.com"
      firstName: "Jane"
      lastName: "Smith"
      customFields: {
        company: "New Company"
        phone: "+0987654321"
      }
    }
  )
}

Response:

{
  "data": {
    "sendgrid_updateContact": true
  }
}

حذف جهة اتصال

Mutation:

mutation sendgrid_deleteContact {
  sendgrid_deleteContact(
    email: "contact@example.com"
  )
}

Response:

{
  "data": {
    "sendgrid_deleteContact": true
  }
}

التحليلات والإحصائيات

الحصول على إحصائيات البريد الإلكتروني

Query:

query sendgrid_getEmailStats {
  sendgrid_getEmailStats (
    startDate: "2025-01-01"
    endDate: "2025-01-31"
  ) {
    opens
    clicks
    bounces
    spamReports
    delivered
    startDate
    endDate
  }
}

Response:

{
  "data": {
    "sendgrid_getEmailStats": {
      "opens": 150,
      "clicks": 75,
      "bounces": 5,
      "spamReports": 2,
      "delivered": 1000,
      "startDate": "2025-01-01T00:00:00Z",
      "endDate": "2025-01-31T00:00:00Z"
    }
  }
}

التحقق من صحة البريد الإلكتروني

Query:

query sendgrid_validateEmail {
  sendgrid_validateEmail (
    email: "test@example.com"
  ) {
    valid
    score
    local
    domain
    reason
    suggestions
  }
}

Response (مع SendGrid Premium):

{
  "data": {
    "sendgrid_validateEmail": {
      "valid": true,
      "score": 0.95,
      "local": "test",
      "domain": "example.com",
      "reason": "",
      "suggestions": []
    }
  }
}

Response (التحقق الأساسي - SendGrid Premium غير متاح):

{
  "data": {
    "sendgrid_validateEmail": {
      "valid": true,
      "score": 0.8,
      "local": "test",
      "domain": "example.com",
      "reason": "Basic validation (SendGrid premium validation not available)",
      "suggestions": []
    }
  }
}

ملاحظة: نقطة نهاية التحقق من صحة البريد الإلكتروني SendGrid (/v3/validations/email) تتطلب أذونات خاصة وقد لا تكون متاحة في جميع الحسابات. إذا لم يكن لمفتاح API الخاص بك حق الوصول إلى نقطة النهاية هذه (خطأ 403)، سيستخدم النظام تلقائيًا التحقق الأساسي المستند إلى regex كبديل.

أمثلة كاملة مع متغيرات

مثال مع متغيرات GraphQL

Request:

{
  "query": "mutation SendEmail($email: EmailInput!) { sendgrid_sendEmail(email: $email) { messageId success } }",
  "variables": {
    "email": {
      "from": {
        "email": "sender@example.com",
        "name": "Sender Name"
      },
      "to": [
        {
          "email": "recipient@example.com",
          "name": "Recipient Name"
        }
      ],
      "subject": "Test Email",
      "content": [
        {
          "type": "text/html",
          "value": "<h1>Hello World</h1>"
        }
      ]
    }
  }
}

معالجة الأخطاء

مثال على خطأ

Request:

{
  "query": "mutation { sendgrid_sendEmail(email: { from: { email: \"invalid\" }, to: [], subject: \"Test\", content: [] }) { messageId success } }"
}

Response Error:

{
  "errors": [
    {
      "message": "validation error: at least one recipient is required",
      "path": ["sendgrid_sendEmail"]
    }
  ],
  "data": null
}

أخطاء شائعة

معرف المشروع مفقود:

{
  "errors": [{
    "message": "project ID is required in context"
  }]
}

التكوين غير موجود:

{
  "errors": [{
    "message": "sendgrid configuration not found for project: xxx, environment: master"
  }]
}

مفتاح API غير صالح:

{
  "errors": [{
    "message": "sendgrid API error: status 401, body: ..."
  }]
}

Webhooks

نقطة نهاية Webhooks

نقطة نهاية Webhooks متاحة على:

HTTP: POST http://localhost:8080/webhooks/sendgrid
Lambda: POST /webhooks/sendgrid

تكوين SendGrid

انتقل إلى SendGrid Dashboard > Settings > Mail Settings > Event Webhook
قم بتكوين URL: https://your-domain.com/webhooks/sendgrid
حدد الأحداث التي ترغب في استلامها
قم بتكوين مفتاح التحقق في متغير البيئة WEBHOOK_VERIFICATION_KEY

الأحداث المدعومة

processed: تم معالجة البريد الإلكتروني
delivered: تم تسليم البريد الإلكتروني
opened: تم فتح البريد الإلكتروني
clicked: تم النقر على الرابط
bounce: تم إرجاع البريد الإلكتروني
dropped: تم إسقاط البريد الإلكتروني
spamreport: تم الإبلاغ عنه كبريد مزعج
unsubscribe: إلغاء الاشtraك