SendGrid

SendGrid est un service cloud pour l’envoi d’e-mails transactionnels et marketing. Connecter cette intégration permet à votre application d’envoyer des e-mails par programmation (par ex. e-mails de bienvenue, réinitialisation de mot de passe ou notifications).

Étapes de configuration

Après avoir sélectionné SendGrid dans la liste des intégrations, une fenêtre de configuration s’affiche. Vous devez fournir les identifiants suivants pour établir la connexion :

1. Clé API

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

Saisie : Collez votre clé API privée SendGrid dans le champ de texte.
Aide : Si vous n’en avez pas, cliquez sur le lien « Where to find API Key? » dans la fenêtre pour savoir comment la générer.

2. Environnement

Indiquez le contexte d’environnement pour cette intégration.

Saisie : Saisissez l’identifiant d’environnement (par ex. Production, Staging ou une balise de configuration précise) dans le champ Environment.

Finaliser la connexion

Une fois les champs remplis :

Vérifiez la barre d’état (elle affiche actuellement Non connecté).
Cliquez sur le bouton noir Ajouter en bas à droite pour enregistrer les identifiants et activer l’intégration.

Configuration de l’intégration SendGrid

Référence de l’API d’intégration SendGrid

Configuration SendGrid

Configurer la clé API SendGrid

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

Réponse :

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

Envoyer un e-mail avec CC et CCI

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

Remarque : Le champ content des 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
  }
}

Réponse :

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

Envoi d’e-mails avec modèles

Envoyer un e-mail avec 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
  }
}

Réponse :

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

Gestion des contacts (envoi)

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

Réponse :

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

Réponse :

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

Supprimer un contact

Mutation :

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

Réponse :

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

Analyses et statistiques (envoi)

Obtenir les statistiques d’e-mail

Requête :

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

Réponse :

{
  "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 une adresse e-mail

Requête :

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

Réponse (avec SendGrid Premium) :

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

Réponse (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": []
    }
  }
}

Remarque : Le point de terminaison de validation d’e-mail SendGrid (/v3/validations/email) nécessite des autorisations spéciales et peut ne pas être disponible sur tous les comptes. Si votre clé API n’a pas accès à ce point de terminaison (erreur 403), le système utilisera automatiquement une validation de base basée sur des expressions régulières en secours.

Exemples complets avec variables

Exemple avec des variables GraphQL

Requête :

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

Requête :

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

Réponse d’erreur :

{
  "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 introuvable :

{
  "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 des webhooks

Le point de terminaison des webhooks est disponible à l’adresse suivante :

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

Configuration SendGrid

Allez dans SendGrid Dashboard > Settings > Mail Settings > Event Webhook
Configurez l’URL : https://tu-dominio.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 délivré
opened : E-mail ouvert
clicked : Lien cliqué
bounce : E-mail rejeté (rebond)
dropped : E-mail abandonné
spamreport : Signalé comme spam
unsubscribe : Désabonnement