SendGrid

SendGrid to usługa w chmurze do dostarczania wiadomości transakcyjnych i marketingowych. Połączenie tej integracji pozwala aplikacji wysyłać e‑maile programowo (np. powitalne, reset hasła lub powiadomienia).

Kroki konfiguracji

Po wybraniu SendGrid z listy integracji pojawi się modal konfiguracji. Musisz podać następujące dane uwierzytelniające, aby nawiązać połączenie:

1. Klucz API

To token uwierzytelniający wygenerowany w koncie SendGrid.

Pole: Wklej prywatny klucz API SendGrid w pole tekstowe.
Pomoc: Jeśli go nie masz, kliknij link „Where to find API Key?” w modalu, aby zobaczyć instrukcję generowania.

2. Środowisko

Określ kontekst środowiska dla tej integracji.

Pole: Wpisz identyfikator środowiska (np. Production, Staging lub konkretną etykietę konfiguracji) w polu Environment.

Finalizacja połączenia

Gdy pola są uzupełnione:

Sprawdź pasek statusu (obecnie Not Connected).
Kliknij czarny przycisk Add w prawym dolnym rogu, aby zapisać dane i aktywować integrację.

Konfiguracja integracji SendGrid

Dokumentacja API integracji SendGrid

Konfiguracja SendGrid {#sendgrid-configuration}

Konfiguracja klucza API SendGrid {#sendgrid-configure-api-key}

Konfiguruje klucz API SendGrid dla konkretnego projektu i środowiska.

Mutacja:

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

Wysyłanie wiadomości e‑mail {#sending-emails}

Wyślij prosty e‑mail {#send-simple-email}

Wysyła wiadomość do jednego lub wielu odbiorców.

Mutacja:

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

Odpowiedź:

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

E‑mail z DW i UDW {#send-email-with-cc-and-bcc}

Mutacja:

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

E‑mail z załącznikami {#send-email-with-attachments}

Mutacja:

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

Uwaga: Pole content w załącznikach musi być zakodowane w Base64.

E‑mail z kategoriami i tagami {#send-email-with-categories-and-tags}

Mutacja:

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

Zaplanowany e‑mail {#send-email-programmed}

Mutacja:

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

E‑mail z niestandardowymi argumentami {#send-email-with-custom-args}

Mutacja:

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

Wysyłka masowa {#send-bulk-emails}

Wyślij wiele wiadomości {#send-multiple-emails}

Mutacja:

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

Odpowiedź:

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

Wiadomości z szablonami {#send-emails-with-templates}

Wyślij e‑mail z szablonem dynamicznym {#send-email-using-dynamic-template}

Mutacja:

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

Odpowiedź:

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

Zarządzanie kontaktami {#send-contact-management}

Dodaj kontakt {#send-add-contact}

Mutacja:

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

Odpowiedź:

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

Zaktualizuj kontakt {#send-update-contact}

Mutacja:

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

Odpowiedź:

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

Usuń kontakt {#send-delete-contact}

Mutacja:

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

Odpowiedź:

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

Analityka i statystyki {#send-analytics-and-statistics}

Pobierz statystyki e‑mail {#send-get-email-stats}

Zapytanie:

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

Odpowiedź:

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

Walidacja adresu e‑mail {#send-validate-email}

Zapytanie:

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

Odpowiedź (SendGrid Premium):

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

Odpowiedź (walidacja podstawowa — gdy SendGrid Premium jest niedostępny):

{
  "data": {
    "sendgrid_validateEmail": {
      "valid": true,
      "score": 0.8,
      "local": "test",
      "domain": "example.com",
      "reason": "Walidacja podstawowa (walidacja premium SendGrid niedostępna)",
      "suggestions": []
    }
  }
}

Uwaga: Endpoint walidacji e‑mail SendGrid (/v3/validations/email) wymaga specjalnych uprawnień i może być niedostępny dla wszystkich kont. Jeśli klucz API nie ma dostępu do tego endpointu (błąd 403), system automatycznie użyje walidacji podstawowej opartej na wyrażeniach regularnych jako zapasowej.

Pełne przykłady ze zmiennymi {#complete-examples-with-variables}

Przykład ze zmiennymi GraphQL {#example-with-graphql-variables}

Żądanie:

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

Obsługa błędów {#error-handling}

Przykład błędu {#error-example}

Żądanie:

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

Odpowiedź z błędem:

{
  "errors": [
    {
      "message": "błąd walidacji: wymagany jest co najmniej jeden odbiorca",
      "path": ["sendgrid_sendEmail"]
    }
  ],
  "data": null
}

Typowe błędy {#common-errors}

Brak ID projektu:

{
  "errors": [{
    "message": "ID projektu jest wymagane w kontekście"
  }]
}

Nie znaleziono konfiguracji:

{
  "errors": [{
    "message": "nie znaleziono konfiguracji sendgrid dla projektu: xxx, środowisko: master"
  }]
}

Nieprawidłowy klucz API:

{
  "errors": [{
    "message": "błąd API sendgrid: status 401, treść: ..."
  }]
}

Webhooks {#webhooks}

Endpoint webhooków {#webhooks-endpoint}

Endpoint webhooków jest dostępny pod:

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

Konfiguracja w SendGrid {#sendgrid-configuration-webhooks}

Przejdź do SendGrid Dashboard > Settings > Mail Settings > Event Webhook
Ustaw URL: https://twoja-domena.com/webhooks/sendgrid
Wybierz zdarzenia, które chcesz otrzymywać
Skonfiguruj klucz weryfikacji w zmiennej środowiskowej WEBHOOK_VERIFICATION_KEY

Obsługiwane zdarzenia {#supported-events}

processed: Wiadomość przetworzona
delivered: Wiadomość dostarczona
opened: Wiadomość otwarta
clicked: Kliknięto link
bounce: Odbicie wiadomości
dropped: Wiadomość odrzucona
spamreport: Zgłoszono jako spam
unsubscribe: Rezygnacja z subskrypcji