Ajouter l'Intégration SendGrid

SendGrid est un service basé sur le cloud pour la livraison d’e-mails transactionnels et marketing. La connexion de cette intégration permet à votre application d’envoyer des e-mails par programmation (par exemple, e-mails de bienvenue, réinitialisations de mot de passe ou notifications).

Étapes de Configuration

Après avoir sélectionné SendGrid dans la liste des intégrations, un modal de configuration apparaîtra. Vous devez fournir les informations d’identification suivantes pour établir la connexion :

1. Clé API

Il s’agit du jeton d’authentification généré dans votre compte SendGrid.

Entrée : Collez votre clé API SendGrid privée dans le champ de texte.
Aide : Si vous n’en avez pas, cliquez sur le lien “Où trouver la clé API ?” fourni dans le modal pour obtenir des instructions sur la façon de la générer.

2. Environnement

Spécifiez le contexte d’environnement pour cette intégration.

Entrée : Entrez l’identifiant d’environnement (par exemple, Production, Staging ou une balise de configuration spécifique) dans le champ Environnement.

Finaliser la Connexion

Une fois les champs remplis :

Examinez la barre d’état (affichant actuellement Not Connected).
Cliquez sur le bouton noir Add en bas à droite pour enregistrer les informations d’identification et activer l’intégration.

Configuration SendGrid

Intégration SendGrid

Référence API d’Intégration SendGrid

Configuration de SendGrid

Configurer la Clé API SendGrid

Configure la clé API SendGrid pour un projet et un environnement spécifiques.

Mutation:

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

Envoi d’E-mails

Envoyer un E-mail Simple

Envoie un e-mail à un ou plusieurs destinataires.

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

Envoyer un E-mail avec CC et 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
  }
}

Envoyer un E-mail avec Pièces Jointes

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

Note : Le champ content dans les pièces jointes doit être encodé en Base64.

Envoyer un E-mail avec Catégories et Balises

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

Envoyer un E-mail Programmé

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

Envoyer un E-mail avec Arguments Personnalisés

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

Envoi d’E-mails en Masse

Envoyer Plusieurs E-mails

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

Envoyer des E-mails avec Modèles

Envoyer un E-mail en utilisant un Modèle Dynamique

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

Gestion des Contacts

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

Response:

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

Mettre à Jour un Contact

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

Supprimer un Contact

Mutation:

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

Response:

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

Analytiques et Statistiques

Obtenir les Statistiques des E-mails

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

Valider un E-mail

Query:

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

Response (avec SendGrid Premium) :

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

Response (Validation de base - lorsque SendGrid Premium n’est pas disponible) :

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

Note : L’endpoint de validation d’e-mail SendGrid (/v3/validations/email) nécessite des autorisations spéciales et peut ne pas être disponible dans tous les comptes. Si votre clé API n’a pas accès à cet endpoint (erreur 403), le système utilisera automatiquement une validation de base basée sur regex comme solution de secours.

Exemples Complets avec Variables

Exemple avec Variables GraphQL

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

Gestion des Erreurs

Exemple d’Erreur

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
}

Erreurs Courantes

ID de projet manquant :

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

Configuration non trouvée :

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

Clé API invalide :

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

Webhooks

Point de Terminaison Webhooks

Le point de terminaison webhooks est disponible à :

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

Configuration SendGrid

Allez à SendGrid Dashboard > Settings > Mail Settings > Event Webhook
Configurez l’URL : https://votre-domaine.com/webhooks/sendgrid
Sélectionnez les événements que vous souhaitez recevoir
Configurez la clé de vérification dans la variable d’environnement WEBHOOK_VERIFICATION_KEY

Événements Pris en Charge

processed: E-mail traité
delivered: E-mail livré
opened: E-mail ouvert
clicked: Lien cliqué
bounce: E-mail retourné
dropped: E-mail abandonné
spamreport: Signalé comme spam
unsubscribe: Désabonnement