SendGrid

Introduzione

L’integrazione SendGrid invia un’email transazionale tramite la Mail Send API di SendGrid quando si verifica un evento di Dodo Payments. Ogni email utilizza uno dei tuoi template dinamici di SendGrid, compilato con i dati dell’evento, così puoi confermare i pagamenti, dare il benvenuto ai nuovi abbonati e ricontattare i clienti in caso di pagamenti non riusciti.

Questa integrazione richiede una chiave API di SendGrid con il permesso Mail Send, un mittente verificato in SendGrid e un template dinamico per ogni email che invii. Devi inoltre avere accesso a Developer → Webhooks nella dashboard di Dodo Payments.

Iniziare

Open the Webhook Section

Nella dashboard di Dodo Payments, vai a Sviluppatore → Webhook e fai clic su Aggiungi endpoint.

Finestra di dialogo Aggiungi endpoint con SendGrid selezionato nel menu a discesa Integrazione e i passaggi per connettere SendGrid

Select SendGrid

In Integration, seleziona SendGrid. La dashboard compila Endpoint URL e il codice di trasformazione per SendGrid, mentre il pannello How to connect SendGrid mostra i passaggi di configurazione.

Enter API Key

In SendGrid, vai a Settings → API Keys e fai clic su Create API Key. Scegli Restricted Access con il permesso Mail Send, oppure Full Access. SendGrid mostra la chiave, che inizia con SG., una sola volta. Incollala in API key. Dodo Payments la invia come bearer token nell’header Authorization di ogni richiesta a SendGrid.

Select Events

In Subscribed events, seleziona solo gli eventi gestiti dalla tua trasformazione. Un evento che la trasformazione lascia invariato raggiunge SendGrid nel formato di Dodo Payments e SendGrid lo rifiuta.

Configure Transformation

In Transformation code, modifica l’handler per formattare le email per la Mail Send API di SendGrid. Parti dagli esempi e sostituisci ogni template_id con l’ID del tuo template dinamico, che inizia con d-.

Test & Create

In Test this code, seleziona un tipo di evento e fai clic su Simulate per visualizzare in anteprima la richiesta a SendGrid. Quindi fai clic su Create endpoint.

Done

Dodo Payments ora invia un’email tramite SendGrid per ogni evento sottoscritto. Per visualizzare ogni invio e la risposta di SendGrid, apri la scheda Logs in Developer → Webhooks.

Esempi di codice di trasformazione

Ogni handler imposta webhook.url sull’endpoint Mail Send e passa i dati dell’evento a un template dinamico tramite dynamic_template_data. Gli importi di Dodo Payments sono espressi nell’unità minima della valuta, quindi gli esempi li dividono per 100. Per le valute senza decimali, come JPY e KRW, utilizza l’importo così com’è.

Email di conferma del pagamento

Invia una ricevuta quando un pagamento va a buon fine (payment.succeeded):

payment_confirmation.js

function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const p = webhook.payload.data;
    webhook.url = "https://api.sendgrid.com/v3/mail/send";
    webhook.payload = {
      personalizations: [
        {
          to: [{ email: p.customer.email }],
          dynamic_template_data: {
            customer_name: p.customer.name,
            payment_amount: (p.total_amount / 100).toFixed(2),
            payment_id: p.payment_id,
            payment_date: new Date(webhook.payload.timestamp).toLocaleDateString(),
            currency: p.currency || "USD"
          }
        }
      ],
      from: {
        email: "payments@yourdomain.com",
        name: "Your Company"
      },
      template_id: "d-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    };
  }
  return webhook;
}

Email di benvenuto per l’abbonamento

Dai il benvenuto a un cliente quando un abbonamento diventa attivo (subscription.active):

subscription_welcome.js

function handler(webhook) {
  if (webhook.eventType === "subscription.active") {
    const s = webhook.payload.data;
    webhook.url = "https://api.sendgrid.com/v3/mail/send";
    webhook.payload = {
      personalizations: [
        {
          to: [{ email: s.customer.email }],
          dynamic_template_data: {
            customer_name: s.customer.name,
            subscription_id: s.subscription_id,
            product_id: s.product_id,
            amount: (s.recurring_pre_tax_amount / 100).toFixed(2),
            frequency: s.payment_frequency_interval,
            next_billing: new Date(s.next_billing_date).toLocaleDateString()
          }
        }
      ],
      from: {
        email: "welcome@yourdomain.com",
        name: "Your Company"
      },
      template_id: "d-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    };
  }
  return webhook;
}

Notifica di pagamento non riuscito

Chiedi al cliente di riprovare quando un pagamento non va a buon fine (payment.failed):

payment_failure.js

function handler(webhook) {
  if (webhook.eventType === "payment.failed") {
    const p = webhook.payload.data;
    webhook.url = "https://api.sendgrid.com/v3/mail/send";
    webhook.payload = {
      personalizations: [
        {
          to: [{ email: p.customer.email }],
          dynamic_template_data: {
            customer_name: p.customer.name,
            payment_amount: (p.total_amount / 100).toFixed(2),
            error_message: p.error_message || "Payment processing failed",
            payment_id: p.payment_id,
            retry_link: `https://yourdomain.com/retry-payment/${p.payment_id}`
          }
        }
      ],
      from: {
        email: "support@yourdomain.com",
        name: "Your Company Support"
      },
      template_id: "d-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    };
  }
  return webhook;
}

Suggerimenti

Utilizza i template dinamici di SendGrid per personalizzare i contenuti.
Passa i dati del pagamento richiesti dal template in dynamic_template_data.
Imposta un indirizzo from che corrisponda a un mittente verificato e un name del mittente.
Riutilizza gli ID dei template, così le email dello stesso tipo mantengono lo stesso formato.
Includi un link per annullare l’iscrizione in ogni email che contiene contenuti di marketing.
Per ignorare un evento nel codice, imposta webhook.cancel = true prima di restituire il webhook. I log registrano un invio ignorato come riuscito.

Risoluzione dei problemi

Emails Not Being Sent

Verifica che la chiave API disponga del permesso Mail Send. Per sostituirla, modifica l’endpoint e incolla una nuova chiave in API key.
Verifica che ogni template_id appartenga a un template dinamico attivo.
Verifica che gli indirizzi email dei destinatari siano validi.
Verifica i limiti e le quote di invio SendGrid previsti dal tuo piano.
Apri la scheda Logs in Developer → Webhooks e leggi la risposta di SendGrid relativa all’invio non riuscito.

Transformation Errors

Verifica che il payload corrisponda al formato Mail Send di SendGrid.
Verifica che siano presenti tutti i campi obbligatori: personalizations con almeno un indirizzo to e from.
Verifica che le chiavi in dynamic_template_data corrispondano alle variabili del template, come {{customer_name}}.
Verifica che ogni indirizzo from sia verificato in SendGrid.

External Integrations

Messaging

Workflow Automation

CRM

Email

Analytics

Pricing

Introduzione

Iniziare

Esempi di codice di trasformazione

Email di conferma del pagamento

Email di benvenuto per l’abbonamento

Notifica di pagamento non riuscito

Suggerimenti

Risoluzione dei problemi

​Introduzione

​Iniziare

​Esempi di codice di trasformazione

​Email di conferma del pagamento

​Email di benvenuto per l’abbonamento

​Notifica di pagamento non riuscito

​Suggerimenti

​Risoluzione dei problemi

Introduzione

Iniziare

Esempi di codice di trasformazione

Email di conferma del pagamento

Email di benvenuto per l’abbonamento

Notifica di pagamento non riuscito

Suggerimenti

Risoluzione dei problemi