@lovable.dev/email-js

Utilities for Lovable email hooks and delivery.

Installation

npm install @lovable.dev/email-js

Usage

Sending with a run_id (build-context emails)

When sending from a webhook where a build run exists, pass the run_id from the payload. You can override the idempotency key (defaults to run_id).

import { parseEmailWebhookPayload, sendLovableEmail } from "@lovable.dev/email-js";
import { verifyWebhookRequest, type EmailWebhookPayload } from "@lovable.dev/webhooks-js";

const apiKey = Deno.env.get("LOVABLE_API_KEY");

export async function handleWebhook(req: Request) {
  if (!apiKey) {
    throw new Error("Missing Lovable API key");
  }

  const { body } = await verifyWebhookRequest<EmailWebhookPayload>({
    req,
    secret: apiKey,
  });
  const payload = parseEmailWebhookPayload(body);
  if (payload.version !== "1") {
    throw new Error(`Unsupported payload version: ${payload.version}`);
  }
  if (!payload.run_id) {
    throw new Error("Missing run_id");
  }

  const apiBaseUrl = payload.data?.api_base_url ?? "https://api.lovable.dev";

  await sendLovableEmail(
    {
      run_id: payload.run_id,
      to: payload.data?.email ?? "",
      from: "My App <[email protected]>",
      subject: "Welcome",
      html: "<p>Hello</p>",
      text: "Hello",
      purpose: "transactional",
    },
    { apiKey, apiBaseUrl },
  );
}

Sending without a run_id (runtime-triggered emails)

For transactional emails sent outside a build context (e.g., webhook handlers, admin actions, database triggers), run_id is not required. Provide an idempotency_key with purpose: "transactional" and the API creates a transactional run automatically:

await sendLovableEmail(
  {
    to: "[email protected]",
    from: "App <[email protected]>",
    sender_domain: "notify.example.com",
    subject: "Your request was approved",
    html: "<p>Approved!</p>",
    text: "Approved!",
    purpose: "transactional",
    idempotency_key: `approval-${requestId}`,
    unsubscribe_token: token,
  },
  { apiKey },
);