SendGrid

Introdução

A integração com o SendGrid envia um e-mail transacional pela Mail Send API do SendGrid quando ocorre um evento do Dodo Payments. Cada e-mail usa um dos seus templates dinâmicos do SendGrid, preenchido com dados do evento, para que você possa confirmar pagamentos, dar boas-vindas a novos assinantes e fazer o acompanhamento de pagamentos que falharam.

Esta integração exige uma chave de API do SendGrid com a permissão Mail Send, um remetente verificado no SendGrid e um template dinâmico para cada e-mail enviado. Você também precisa ter acesso a Developer → Webhooks no dashboard do Dodo Payments.

Começando

Open the Webhook Section

No dashboard do Dodo Payments, acesse Developer → Webhooks e clique em Add endpoint.

Caixa de diálogo Add endpoint com SendGrid selecionado no menu suspenso Integration e as etapas How to connect SendGrid

Select SendGrid

Em Integration, selecione SendGrid. O dashboard preenche o Endpoint URL e o código de transformação para o SendGrid, e o painel How to connect SendGrid exibe as etapas de configuração.

Enter API Key

No SendGrid, acesse Settings → API Keys e clique em Create API Key. Escolha Restricted Access com a permissão Mail Send, ou Full Access. O SendGrid exibe a chave, que começa com SG., apenas uma vez. Cole-a em API key. O Dodo Payments a envia como um bearer token no cabeçalho Authorization de cada requisição ao SendGrid.

Select Events

Em Subscribed events, selecione apenas os eventos tratados pela sua transformação. Um evento que a transformação deixa inalterado chega ao SendGrid no formato do Dodo Payments, e o SendGrid o rejeita.

Configure Transformation

Em Transformation code, edite o handler para formatar os e-mails para a Mail Send API do SendGrid. Comece pelos exemplos e substitua cada template_id pelo ID do seu próprio template dinâmico, que começa com d-.

Test & Create

Em Test this code, selecione um tipo de evento e clique em Simulate para visualizar a requisição ao SendGrid. Em seguida, clique em Create endpoint.

Done

O Dodo Payments agora envia um e-mail pelo SendGrid para cada evento inscrito. Para ver cada entrega e a resposta do SendGrid, abra a aba Logs em Developer → Webhooks.

Exemplos de código de transformação

Cada handler define webhook.url como o endpoint de envio e passa os dados do evento para um template dinâmico por meio de dynamic_template_data. Os valores do Dodo Payments estão na menor unidade da moeda, por isso os exemplos dividem por 100. Para moedas sem casas decimais, como JPY e KRW, use o valor como está.

E-mail de confirmação de pagamento

Envie um recibo quando um pagamento for aprovado (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;
}

E-mail de boas-vindas à assinatura

Dê boas-vindas a um cliente quando uma assinatura se tornar ativa (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ção de falha no pagamento

Peça ao cliente que tente novamente quando um pagamento falhar (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;
}

Dicas

Use templates dinâmicos do SendGrid para personalizar o conteúdo.
Passe os dados de pagamento necessários para o seu template em dynamic_template_data.
Defina um endereço from que corresponda a um remetente verificado e um name de remetente.
Reutilize os IDs dos templates para que os e-mails do mesmo tipo mantenham o mesmo formato.
Inclua um link de cancelamento de assinatura em qualquer e-mail que contenha conteúdo de marketing.
Para ignorar um evento no código, defina webhook.cancel = true antes de retornar o webhook. Os logs registram uma entrega ignorada como bem-sucedida.

Solução de problemas

Emails Not Being Sent

Verifique se a chave de API tem a permissão Mail Send. Para substituí-la, edite o endpoint e cole uma nova chave em API key.
Verifique se cada template_id pertence a um template dinâmico ativo.
Verifique se os endereços de e-mail dos destinatários são válidos.
Verifique os limites e as cotas de envio do SendGrid para o seu plano.
Abra a aba Logs em Developer → Webhooks e leia a resposta do SendGrid para a entrega que falhou.

Transformation Errors

Verifique se o payload corresponde ao formato Mail Send do SendGrid.
Verifique se todos os campos obrigatórios estão presentes: personalizations com pelo menos um endereço to e from.
Verifique se as chaves em dynamic_template_data correspondem às variáveis do seu template, como {{customer_name}}.
Verifique se cada endereço from está verificado no SendGrid.

External Integrations

Messaging

Workflow Automation

CRM

Email

Analytics

Pricing

Introdução

Começando

Exemplos de código de transformação

E-mail de confirmação de pagamento

E-mail de boas-vindas à assinatura

Notificação de falha no pagamento

Dicas

Solução de problemas

​Introdução

​Começando

​Exemplos de código de transformação

​E-mail de confirmação de pagamento

​E-mail de boas-vindas à assinatura

​Notificação de falha no pagamento

​Dicas

​Solução de problemas

Introdução

Começando

Exemplos de código de transformação

E-mail de confirmação de pagamento

E-mail de boas-vindas à assinatura

Notificação de falha no pagamento

Dicas

Solução de problemas