SendGrid

SendGrid היא שירות מבוסס ענן למסירת דוא”ל עסקי ושיווקי. חיבור האינטגרציה מאפשר לאפליקציה שלכם לשלוח הודעות דוא”ל באופן פרוגרמטי (למשל הודעות פתיחה, איפוס סיסמה או התראות).

שלבי התצורה

לאחר בחירת SendGrid מרשימת האינטגרציות, יופיע חלון תצורה. יש להזין את פרטי האימות הבאים כדי ליצור את החיבור:

1. מפתח API

זהו אסימון האימות שנוצר בחשבון SendGrid שלכם.

קלט: הדביקו את מפתח ה-API הפרטי של SendGrid בשדה הטקסט.
עזרה: אם אין לכם מפתח, לחצו על הקישור “Where to find API Key?” בחלון כדי לראות כיצד ליצור אותו.

2. סביבה

הגדירו את הקשר הסביבתי לאינטגרציה זו.

קלט: הזינו את מזהה הסביבה (למשל Production, Staging או תג תצורה) בשדה Environment.

השלמת החיבור

לאחר מילוי השדות:

בדקו את שורת הסטטוס (מציגה כעת Not Connected).
לחצו על הכפתור השחור Add בפינה הימנית התחתונה כדי לשמור את פרטי האימות ולהפעיל את האינטגרציה.

תצורת אינטגרציית SendGrid

מדריך API לאינטגרציית SendGrid

תצורת SendGrid {#sendgrid-configuration}

הגדרת מפתח API של SendGrid {#sendgrid-configure-api-key}

מגדיר את מפתח ה-API של SendGrid לפרויקט ולסביבה מסוימים.

Mutation:

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

שליחת דוא”ל {#sending-emails}

שליחת דוא”ל פשוט {#send-simple-email}

שולח הודעת דוא”ל לנמען אחד או מספר נמענים.

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
  }
}

תגובה:

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

דוא”ל עם עותק ועותק מוסתר {#send-email-with-cc-and-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
  }
}

דוא”ל עם קבצים מצורפים {#send-email-with-attachments}

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.

דוא”ל עם קטגוריות ותגיות {#send-email-with-categories-and-tags}

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
  }
}

דוא”ל מתוזמן {#send-email-programmed}

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
  }
}

דוא”ל עם ארגומנטים מותאמים {#send-email-with-custom-args}

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
  }
}

שליחה המונית {#send-bulk-emails}

שליחת מספר הודעות {#send-multiple-emails}

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
  }
}

תגובה:

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

דוא”ל עם תבניות {#send-emails-with-templates}

שליחה עם תבנית דינמית {#send-email-using-dynamic-template}

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
  }
}

תגובה:

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

ניהול אנשי קשר {#send-contact-management}

הוספת איש קשר {#send-add-contact}

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"]
    }
  )
}

תגובה:

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

עדכון איש קשר {#send-update-contact}

Mutation:

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

תגובה:

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

מחיקת איש קשר {#send-delete-contact}

Mutation:

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

תגובה:

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

אנליטיקה וסטטיסטיקה {#send-analytics-and-statistics}

סטטיסטיקות דוא”ל {#send-get-email-stats}

שאילתה:

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

תגובה:

{
  "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"
    }
  }
}

אימות כתובת דוא”ל {#send-validate-email}

שאילתה:

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

תגובה (עם SendGrid Premium):

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

תגובה (אימות בסיסי — כאשר 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), המערכת תשתמש אוטומטית באימות בסיסי מבוסס ביטויים רגולריים.

דוגמאות מלאות עם משתנים {#complete-examples-with-variables}

דוגמה עם משתני GraphQL {#example-with-graphql-variables}

בקשה:

{
  "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>"
        }
      ]
    }
  }
}

טיפול בשגיאות {#error-handling}

דוגמת שגיאה {#error-example}

בקשה:

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

שגיאת תגובה:

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

שגיאות נפוצות {#common-errors}

חסר מזהה פרויקט:

{
  "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 {#webhooks-endpoint}

נקודת הקצה זמינה ב:

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

תצורה ב-SendGrid {#sendgrid-configuration-webhooks}

עברו ל-SendGrid Dashboard > Settings > Mail Settings > Event Webhook
הגדירו את הכתובת: https://your-domain.com/webhooks/sendgrid
בחרו את האירועים שברצונכם לקבל
הגדירו את מפתח האימות במשתנה הסביבה WEBHOOK_VERIFICATION_KEY

אירועים נתמכים {#supported-events}

processed: הדוא”ל עובד
delivered: נמסר
opened: נפתח
clicked: לחיצה על קישור
bounce: החזרה
dropped: הושמט
spamreport: דווח כספאם
unsubscribe: ביטול הרשמה