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

> 通过Keplars根据Dodo Payments事件发送事务性邮件。

## 介绍

当支付和订阅事件发生时，自动发送专业的事务性邮件。通过Keplars传递支付确认、订阅更新和失败通知，无需中间件服务器。Dodo Payments使用JavaScript转换处理程序直接调用Keplars API。

<Info>
  此集成要求您的Keplars API密钥进行身份验证。在Keplars仪表板的**设置 → API 密钥**下找到，并在**域**下验证发件人域或地址。
</Info>

## 入门指南

<Steps>
  <Step title="Open the Webhook Section">
    在您的Dodo Payments仪表板中，导航到<b>Webhook → + 添加端点</b>并展开集成下拉菜单。
  </Step>

  <Step title="Select Keplars">
    选择<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="选择Keplars集成卡" style={{ maxHeight: '500px', width: 'auto' }} width="1040" height="731" data-path="images/integrations/keplars/select.png" />
    </Frame>
  </Step>

  <Step title="Enter API Key">
    提供您的Keplars API密钥。它会在每次请求时作为Bearer令牌发送。

    <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="输入Keplars API URL、API密钥并订阅事件" style={{ maxHeight: '500px', width: 'auto' }} width="982" height="854" data-path="images/integrations/keplars/api-key.png" />
    </Frame>
  </Step>

  <Step title="Configure Transformation">
    编辑转换代码以格式化发送给Keplars的邮件。用您自己的替换占位符发件人地址和模板ID。
  </Step>

  <Step title="Test & Create">
    使用示例负载进行测试，然后单击<b>创建</b>激活邮件发送。
  </Step>

  <Step title="Done!">
    🎉 付款事件现在将自动通过Keplars触发事务性邮件。
  </Step>
</Steps>

## 转换代码示例

每个处理程序将`webhook.url`设置为Keplars高优先级发送端点，并将`webhook.payload`重写为Keplars请求（API密钥会自动作为Bearer令牌发送）。用您的已验证发件人替换`payments@mail.yourdomain.com`，用您的实际模板ID替换`your-keplars-*-template-id`。

<Warning>
  `to`必须是一个**数组**，即使只是一个接收者。在使用`template_id`时，请**不要**同时发送`subject`或`body`。模板提供了它们。
</Warning>

### 付款确认邮件

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

### 付款失败通知

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

### 订阅欢迎邮件

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

### 订阅取消邮件

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

## 提示

* 使用已验证的发件人域或地址以提高送达率。
* 为每种事件类型创建一个专用的Keplars模板，以确保每封电子邮件保持品牌和信息一致。
* 通过传递客户数据（如姓名、金额和付款ID）进行个性化。
* 先在沙箱模式下测试。沙箱发送会被捕捉到Keplars测试收件箱而不是被直接送达。

## 故障排除

<AccordionGroup>
  <Accordion title="Emails not being sent">
    * 验证您的API密钥在Keplars中的正确性和活动状态，路径为**设置 → API 密钥**。
    * 验证您的发件人域或地址是否已验证。
    * Dodo Payments在Webhook交付日志中显示原始的Keplars错误响应。查看以获取详细信息。
  </Accordion>

  <Accordion title="Template not found">
    * 您的处理程序中的`template_id`必须与您在Keplars账号中的一个活动模板匹配。在仪表板中验证ID（并确认它是活动的）。
  </Accordion>

  <Accordion title="Wrong event triggered">
    * 每个处理程序检查`webhook.eventType`并如果不匹配则提前返回。确保在Dodo Payments的Webhook端点中订阅了正确的事件。
  </Accordion>
</AccordionGroup>