> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Keplars

> Invia email transazionali attraverso Keplars basate su eventi di Dodo Payments.

## Introduzione

Invia email transazionali professionali automaticamente quando si verificano eventi di pagamento e abbonamento. Invia conferme di pagamento, aggiornamenti di abbonamento e notifiche di errore tramite Keplars senza necessità di un server middleware. Dodo Payments chiama l'API di Keplars direttamente utilizzando un gestore di trasformazione JavaScript.

<Info>
  Questa integrazione richiede la tua chiave API di Keplars per l'autenticazione. Trovala nel dashboard di Keplars sotto **Impostazioni → Chiavi API**, e verifica un dominio o indirizzo del mittente sotto **Domini**.
</Info>

## Iniziare

<Steps>
  <Step title="Open the Webhook Section">
    Nel tuo dashboard di Dodo Payments, vai a <b>Webhooks → + Aggiungi Endpoint</b> ed espandi il menu a discesa delle integrazioni.
  </Step>

  <Step title="Select Keplars">
    Scegli la scheda di integrazione <b>Keplars</b>.

    <Frame>
      <img src="https://mintcdn.com/dodopayments/tM0KgwbOo2xwg7zr/images/integrations/keplars/select.png?fit=max&auto=format&n=tM0KgwbOo2xwg7zr&q=85&s=776a4a2228efa0822b15b13d2baaf5bb" alt="Seleziona la scheda di integrazione di Keplars" style={{ maxHeight: '500px', width: 'auto' }} width="1040" height="731" data-path="images/integrations/keplars/select.png" />
    </Frame>
  </Step>

  <Step title="Enter API Key">
    Fornisci la tua chiave API di Keplars. Viene inviata come token Bearer ad ogni richiesta.

    <Frame>
      <img src="https://mintcdn.com/dodopayments/tM0KgwbOo2xwg7zr/images/integrations/keplars/api-key.png?fit=max&auto=format&n=tM0KgwbOo2xwg7zr&q=85&s=f3e0917155715d0587a6012c1bfd3f26" alt="Inserisci l'URL API di Keplars, la chiave API, e iscriviti agli eventi" style={{ maxHeight: '500px', width: 'auto' }} width="982" height="854" data-path="images/integrations/keplars/api-key.png" />
    </Frame>
  </Step>

  <Step title="Configure Transformation">
    Modifica il codice di trasformazione per formattare le email per Keplars. Sostituisci l'indirizzo del mittente e gli ID dei modelli con i tuoi.
  </Step>

  <Step title="Test & Create">
    Testa con payload di esempio e fai clic su <b>Crea</b> per attivare l'invio delle email.
  </Step>

  <Step title="Done!">
    🎉 Gli eventi di pagamento attiveranno ora automaticamente le email transazionali tramite Keplars.
  </Step>
</Steps>

## Esempi di Codice per la Trasformazione

Ogni gestore imposta `webhook.url` all'endpoint di invio ad alta priorità di Keplars e riscrive `webhook.payload` in una richiesta Keplars (la chiave API è inviata automaticamente come token Bearer). Sostituisci `payments@mail.yourdomain.com` con il tuo mittente verificato e `your-keplars-*-template-id` con i tuoi effettivi ID dei modelli.

<Warning>
  `to` deve essere un **array**, anche per un singolo destinatario. Quando utilizzi `template_id`, non inviare anche `subject` o `body`. Il modello li fornisce.
</Warning>

### Email di Conferma Pagamento

```javascript payment_succeeded.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType !== "payment.succeeded") return webhook;

  const data = webhook.payload.data || {};
  const paymentDate = new Date(webhook.payload.timestamp).toLocaleDateString("en-US", {
    year: "numeric", month: "long", day: "numeric",
  });

  webhook.url = "https://api.keplars.com/api/v1/send-email/high";
  webhook.payload = {
    to: [data.customer?.email],
    from: "payments@mail.yourdomain.com",
    template_id: "your-keplars-payment-success-template-id",
    params: {
      customer_name: data.customer?.name,
      amount: ((data.total_amount || 0) / 100).toFixed(2),
      currency: data.currency || "USD",
      payment_id: data.payment_id,
      payment_method: data.payment_method,
      payment_date: paymentDate,
    },
  };
  return webhook;
}
```

### Notifica di Errore di Pagamento

```javascript payment_failed.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType !== "payment.failed") return webhook;

  const data = webhook.payload.data || {};
  const paymentDate = new Date(webhook.payload.timestamp).toLocaleDateString("en-US", {
    year: "numeric", month: "long", day: "numeric",
  });

  webhook.url = "https://api.keplars.com/api/v1/send-email/high";
  webhook.payload = {
    to: [data.customer?.email],
    from: "payments@mail.yourdomain.com",
    template_id: "your-keplars-payment-failed-template-id",
    params: {
      customer_name: data.customer?.name,
      amount: ((data.total_amount || 0) / 100).toFixed(2),
      currency: data.currency || "USD",
      payment_id: data.payment_id,
      error_message: data.error_message || "Your payment could not be processed.",
      payment_date: paymentDate,
    },
  };
  return webhook;
}
```

### Email di Benvenuto per l'Abbonamento

```javascript subscription_active.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType !== "subscription.active") return webhook;

  const data = webhook.payload.data || {};
  const nextBilling = data.next_billing_date
    ? new Date(data.next_billing_date).toLocaleDateString("en-US", {
        year: "numeric", month: "long", day: "numeric",
      })
    : "";

  webhook.url = "https://api.keplars.com/api/v1/send-email/high";
  webhook.payload = {
    to: [data.customer?.email],
    from: "payments@mail.yourdomain.com",
    template_id: "your-keplars-subscription-active-template-id",
    params: {
      customer_name: data.customer?.name,
      subscription_id: data.subscription_id,
      product_id: data.product_id,
      amount: ((data.recurring_pre_tax_amount || 0) / 100).toFixed(2),
      currency: data.currency || "USD",
      billing_interval: data.payment_frequency_interval || "month",
      next_billing_date: nextBilling,
    },
  };
  return webhook;
}
```

### Email di Cancellazione Abbonamento

```javascript subscription_cancelled.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType !== "subscription.cancelled") return webhook;

  const data = webhook.payload.data || {};
  const cancellationDate = new Date(webhook.payload.timestamp).toLocaleDateString("en-US", {
    year: "numeric", month: "long", day: "numeric",
  });

  webhook.url = "https://api.keplars.com/api/v1/send-email/high";
  webhook.payload = {
    to: [data.customer?.email],
    from: "payments@mail.yourdomain.com",
    template_id: "your-keplars-subscription-cancelled-template-id",
    params: {
      customer_name: data.customer?.name,
      subscription_id: data.subscription_id,
      cancellation_date: cancellationDate,
    },
  };
  return webhook;
}
```

## Consigli

* Usa un dominio o indirizzo del mittente verificato per una migliore deliverability.
* Crea un modello dedicato di Keplars per ogni tipo di evento in modo che ciascuna email rimanga in linea con il marchio e il messaggio.
* Personalizza ogni email passando dati del cliente come nome, importo e ID pagamento attraverso `params`.
* Testa prima in modalità sandbox. Gli invii in sandbox sono acquisiti nella Test Inbox di Keplars anziché essere consegnati.

## Risoluzione dei Problemi

<AccordionGroup>
  <Accordion title="Emails not being sent">
    * Verifica che la tua chiave API sia corretta e attiva in Keplars sotto **Impostazioni → Chiavi API**.
    * Verifica che il tuo dominio o indirizzo del mittente sia verificato.
    * Dodo Payments mostra la risposta di errore grezza di Keplars nel log di consegna del webhook. Controllala per i dettagli.
  </Accordion>

  <Accordion title="Template not found">
    * L'`template_id` nel tuo gestore deve corrispondere a un modello attivo nel tuo account Keplars. Verifica l'ID (e che sia attivo) nel dashboard.
  </Accordion>

  <Accordion title="Wrong event triggered">
    * Ogni gestore controlla `webhook.eventType` e ritorna subito se non corrisponde. Assicurati che gli eventi corretti siano sottoscritti sull'endpoint webhook di Dodo Payments.
  </Accordion>
</AccordionGroup>