SendGrid Entegrasyonu Ekleme

SendGrid, işlemsel ve pazarlama e-postalarını teslim etmek için bulut tabanlı bir hizmettir. Bu entegrasyonun bağlanması, uygulamanızın programatik olarak e-posta göndermesine olanak tanır (örneğin, hoş geldiniz e-postaları, şifre sıfırlama veya bildirimler).

Yapılandırma Adımları

Entegrasyon listesinden SendGrid’i seçtikten sonra bir yapılandırma modu açılacaktır. Bağlantıyı kurmak için aşağıdaki kimlik bilgilerini sağlamalısınız:

1. API Anahtarı

Bu, SendGrid hesabınız içinde oluşturulan kimlik doğrulama belirtecidir.

Giriş: Özel Send Grid API Anahtarınızı metin alanına yapıştırın.
Yardım: Yoksa, nasıl oluşturulacağına dair talimatlar için modda sağlanan “API Anahtarı nerede bulunur?” bağlantısına tıklayın.

2. Ortam

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

Giriş: Ortam alanına ortam tanımlayıcısını girin (örneğin, Production, Staging veya belirli bir yapılandırma etiketi).

Bağlantıyı Tamamlama

Alanlar doldurulduktan sonra:

Durum çubuğunu gözden geçirin (şu anda Not Connected gösteriyor).
Kimlik bilgilerini kaydetmek ve entegrasyonu etkinleştirmek için sağ alt köşedeki siyah Add düğmesine tıklayın.

SendGrid Yapılandırması

SendGrid Entegrasyonu

SendGrid Entegrasyonu 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.

Mutation:

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

E-posta Gönderme

Basit E-posta Gönder

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

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 ve BCC ile E-posta Gönder

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

Ekli E-posta Gönder

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

Not: Ek dosyalardaki content alanı Base64 ile kodlanmış olmalıdır.

Kategoriler ve Etiketlerle E-posta Gönder

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

Zamanlanmış E-posta Gönder

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

Özel Argümanlarla E-posta Gönder

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

Toplu E-posta Gönderme

Birden Fazla E-posta Gönder

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

Şablonlarla E-posta Gönderme

Dinamik Şablon Kullanarak E-posta Gönder

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

Kişi Yönetimi

Kişi Ekle

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

Kişi Güncelle

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

Kişi Sil

Mutation:

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

Response:

{
  "data": {
    "send

grid_deleteContact": true
  }
}

Analitik ve İstatistikler

E-posta İstatistiklerini Al

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

E-postayı Doğrula

Query:

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

Response (SendGrid Premium ile):

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

Response (Temel doğrulama - SendGrid Premium kullanılamıyorsa):

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

Not: SendGrid e-posta doğrulama uç noktası (/v3/validations/email) özel izinler gerektirir ve tüm hesaplarda kullanılamayabilir. API anahtarınızın bu uç noktaya erişimi yoksa (hata 403), sistem otomatik olarak yedek olarak regex tabanlı temel doğrulama kullanır.

Değişkenlerle Tam Örnekler

GraphQL Değişkenleriyle Örnek

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

Hata İşleme

Hata Örneği

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
}

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

API anahtarı geçersiz:

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

Webhooks

Webhooks Uç Noktası

Webhooks uç noktası şu adreste mevcuttur:

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

SendGrid Yapılandırması

SendGrid Dashboard > Settings > Mail Settings > Event Webhook’a gidin
URL’yi yapılandırın: https://alan-adiniz.com/webhooks/sendgrid
Almak istediğiniz olayları seçin
Doğrulama anahtarını WEBHOOK_VERIFICATION_KEY ortam değişkeninde yapılandırın

Desteklenen Olaylar

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