SendGrid

SendGrid, işlemsel ve pazarlama e-postalarını göndermek için bulut tabanlı bir hizmettir. Bu entegrasyonla uygulamanız programatik olarak e-posta gönderebilir (ör. hoş geldin, parola sıfırlama veya bildirimler).

Yapılandırma adımları

Entegrasyonlar listesinden SendGrid seçildiğinde bir yapılandırma iletişim kutusu açılır. Bağlantıyı kurmak için aşağıdaki kimlik bilgilerini sağlamalısınız:

1. API anahtarı

SendGrid hesabınızda oluşturulan kimlik doğrulama jetonudur.

Girdi: Özel SendGrid API anahtarınızı metin alanına yapıştırın.
Yardım: Henüz anahtarınız yoksa iletişim kutusundaki „Where to find API Key?“ bağlantısına tıklayıp oluşturma adımlarını izleyin.

2. Ortam

Bu entegrasyon için ortam bağlamını belirleyin.

Girdi: Environment alanına ortam tanımlayıcısını girin (ör. Production, Staging veya belirli bir yapılandırma etiketi).

Bağlantıyı tamamlama

Alanlar doldurulduktan sonra:

Durum çubuğunu kontrol edin (şu anda Bağlı değil).
Kimlik bilgilerini kaydetmek ve entegrasyonu etkinleştirmek için sağ alttaki siyah Ekle düğmesine tıklayın.

SendGrid entegrasyon yapılandırması

SendGrid entegrasyon API referansı

SendGrid yapılandırması

SendGrid API anahtarını yapılandırma

Belirli bir proje ve ortam için SendGrid API anahtarını yapılandırır.

Mutasyon:

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

E-posta gönderme

Basit e-posta gönderme

Bir veya daha fazla alıcıya e-posta gönderir.

Mutasyon:

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

Yanıt:

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

CC ve BCC ile e-posta gönderme

Mutasyon:

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

Eklerle e-posta gönderme

Mutasyon:

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

Not: Eklerde content alanı Base64 kodlanmış olmalıdır.

Kategori ve etiketlerle e-posta gönderme

Mutasyon:

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

Zamanlanmış e-posta gönderme

Mutasyon:

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

Özel argümanlarla e-posta gönderme

Mutasyon:

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

Toplu e-posta gönderme

Birden fazla e-posta gönderme

Mutasyon:

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

Yanıt:

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

Şablonlarla e-posta

Dinamik şablonla e-posta gönderme

Mutasyon:

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

Yanıt:

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

Kişi yönetimi (gönderim)

Kişi ekleme

Mutasyon:

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

Yanıt:

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

Kişi güncelleme

Mutasyon:

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

Yanıt:

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

Kişi silme

Mutasyon:

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

Yanıt:

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

Analiz ve istatistikler (gönderim)

E-posta istatistiklerini getirme

Sorgu:

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

Yanıt:

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

E-posta doğrulama

Sorgu:

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

Yanıt (SendGrid Premium ile):

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

Yanıt (temel doğrulama – SendGrid Premium yoksa):

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

Not: E-posta doğrulama için SendGrid uç noktası (/v3/validations/email) ek izin gerektirir ve tüm hesaplarda bulunmayabilir. API anahtarınızı bu uç noktaya erişim yoksa (403 hatası), sistem yedek olarak basit regex tabanlı doğrulama kullanır.

Değişkenlerle tam örnekler

GraphQL değişkenleriyle örnek

İstek:

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

Hata işleme

Hata örneği

İstek:

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

Hata yanıtı:

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

Yaygın hatalar

Proje kimliği eksik:

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

Yapılandırma bulunamadı:

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

Geçersiz API anahtarı:

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

Webhooks

Webhook uç noktası

Webhook uç noktası şu adreslerde kullanılabilir:

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

Webhook için SendGrid ayarı

SendGrid’de: Dashboard > Settings > Mail Settings > Event Webhook bölümünü açın.
URL’yi yapılandırın: https://tu-dominio.com/webhooks/sendgrid
Almak istediğiniz olayları seçin.
Doğrulama anahtarını ortam değişkeni WEBHOOK_VERIFICATION_KEY içinde yapılandırın.

Desteklenen olaylar

processed: E-posta işlendi
delivered: E-posta teslim edildi
opened: E-posta açıldı
clicked: Bağlantı tıklandı
bounce: E-posta geri döndü (bounce)
dropped: E-posta düşürüldü
spamreport: Spam olarak bildirildi
unsubscribe: Abonelikten çıkma