SendGrid

SendGrid is een cloudservice voor transactionele en marketing-e-mails. Door deze integratie te koppelen kan uw applicatie e-mails programmatisch verzenden (bijvoorbeeld welkomstberichten, wachtwoordresets of meldingen).

Configuratiestappen

Nadat u SendGrid in de integratielijst hebt gekozen, opent er een configuratievenster. U moet de volgende gegevens opgeven om de verbinding tot stand te brengen:

1. API-sleutel

Dit is het authenticatietoken dat in uw SendGrid-account is gegenereerd.

Invoer: Plak uw privé SendGrid API-sleutel in het tekstveld.
Help: Als u er geen hebt, klikt u op de link “Where to find API Key?” in het venster voor instructies.

2. Omgeving

Geef de omgevingscontext voor deze integratie op.

Invoer: Voer de omgevingsidentificatie (bijv. Production, Staging of een specifiek configuratielabel) in het veld Environment in.

Verbinding afronden

Wanneer de velden zijn ingevuld:

Controleer de statusbalk (nu Not Connected).
Klik rechtsonder op de zwarte knop Add om de gegevens op te slaan en de integratie te activeren.

SendGrid-integratieconfiguratie

API-referentie SendGrid-integratie

SendGrid-configuratie {#sendgrid-configuration}

SendGrid API-sleutel configureren {#sendgrid-configure-api-key}

Configureert de SendGrid API-sleutel voor een specifiek project en een specifieke omgeving.

Mutatie:

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

E-mail verzenden {#sending-emails}

Eenvoudige e-mail verzenden {#send-simple-email}

Verstuurt een e-mail aan een of meer ontvangers.

Mutatie:

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

Antwoord:

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

E-mail met CC en BCC {#send-email-with-cc-and-bcc}

Mutatie:

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 met bijlagen {#send-email-with-attachments}

Mutatie:

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

Opmerking: Het veld content in bijlagen moet Base64-gecodeerd zijn.

E-mail met categorieën en tags {#send-email-with-categories-and-tags}

Mutatie:

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

Geplande e-mail {#send-email-programmed}

Mutatie:

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 met aangepaste argumenten {#send-email-with-custom-args}

Mutatie:

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

Bulkmail {#send-bulk-emails}

Meerdere e-mails verzenden {#send-multiple-emails}

Mutatie:

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

Antwoord:

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

E-mails met sjablonen {#send-emails-with-templates}

E-mail met dynamisch sjabloon {#send-email-using-dynamic-template}

Mutatie:

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

Antwoord:

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

Contactbeheer {#send-contact-management}

Contact toevoegen {#send-add-contact}

Mutatie:

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

Antwoord:

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

Contact bijwerken {#send-update-contact}

Mutatie:

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

Antwoord:

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

Contact verwijderen {#send-delete-contact}

Mutatie:

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

Antwoord:

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

Analyse en statistieken {#send-analytics-and-statistics}

E-mailstatistieken ophalen {#send-get-email-stats}

Query:

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

Antwoord:

{
  "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-mail valideren {#send-validate-email}

Query:

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

Antwoord (met SendGrid Premium):

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

Antwoord (basisvalidatie — wanneer SendGrid Premium niet beschikbaar is):

{
  "data": {
    "sendgrid_validateEmail": {
      "valid": true,
      "score": 0.8,
      "local": "test",
      "domain": "example.com",
      "reason": "Basisvalidatie (SendGrid premium-validatie niet beschikbaar)",
      "suggestions": []
    }
  }
}

Opmerking: Het SendGrid-e-mailvalidatie-endpoint (/v3/validations/email) vereist speciale rechten en is mogelijk niet voor alle accounts beschikbaar. Als uw API-sleutel geen toegang heeft tot dit endpoint (fout 403), gebruikt het systeem automatisch basisvalidatie op basis van reguliere expressies als fallback.

Volledige voorbeelden met variabelen {#complete-examples-with-variables}

Voorbeeld met GraphQL-variabelen {#example-with-graphql-variables}

Aanvraag:

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

Foutafhandeling {#error-handling}

Voorbeeldfout {#error-example}

Aanvraag:

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

Foutantwoord:

{
  "errors": [
    {
      "message": "validatiefout: minimaal één ontvanger is vereist",
      "path": ["sendgrid_sendEmail"]
    }
  ],
  "data": null
}

Veelvoorkomende fouten {#common-errors}

Project-ID ontbreekt:

{
  "errors": [{
    "message": "project-ID is vereist in de context"
  }]
}

Configuratie niet gevonden:

{
  "errors": [{
    "message": "sendgrid-configuratie niet gevonden voor project: xxx, omgeving: master"
  }]
}

Ongeldige API-sleutel:

{
  "errors": [{
    "message": "SendGrid API-fout: status 401, body: ..."
  }]
}

Webhooks {#webhooks}

Webhook-endpoint {#webhooks-endpoint}

Het webhook-endpoint is beschikbaar op:

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

Configuratie in SendGrid {#sendgrid-configuration-webhooks}

Ga naar SendGrid Dashboard > Settings > Mail Settings > Event Webhook
Configureer de URL: https://uw-domein.com/webhooks/sendgrid
Selecteer de gebeurtenissen die u wilt ontvangen
Configureer de verificatiesleutel in de omgevingsvariabele WEBHOOK_VERIFICATION_KEY

Ondersteunde gebeurtenissen {#supported-events}

processed: E-mail verwerkt
delivered: E-mail afgeleverd
opened: E-mail geopend
clicked: Link geklikt
bounce: E-mail teruggekaatst
dropped: E-mail verworpen
spamreport: Als spam gerapporteerd
unsubscribe: Uitschrijving