Sending Emails

import { Lettr } from "lettr";

const client = new Lettr(process.env.LETTR_API_KEY!);

const { data, error } = await client.emails.send({
  from: "sender@yourdomain.com",
  from_name: "Your App",
  to: ["recipient@example.com"],
  subject: "Hello from Lettr",
  html: "<h1>Welcome!</h1><p>Thanks for signing up.</p>",
});

if (error) {
  console.error(error.message);
  return;
}

console.log(data.request_id); // unique id for tracking
console.log(data.accepted);   // number of accepted recipients
console.log(data.rejected);   // number of rejected recipients

await client.emails.send({
  from: "sender@yourdomain.com",
  to: ["recipient@example.com"],
  subject: "Plain text update",
  text: "This is a plain text email.",
  // include both html and text for a multipart message
});

await client.emails.send({
  from: "sender@yourdomain.com",
  to: ["customer@example.com"],
  template_slug: "welcome",
  substitution_data: { name: "John" },
  template_version: 2, // optional: pin a version
});

await client.emails.send({
  from: "sender@yourdomain.com",
  to: ["recipient@example.com"],
  subject: "Newsletter",
  html: "<p>...</p>",
  tag: "newsletter",
  metadata: { user_id: "123", campaign: "weekly" },
  headers: { "X-Entity-Ref-ID": "order-456" },
  options: {
    open_tracking: true,
    click_tracking: true,
    transactional: true,
  },
});

await client.emails.send({
  from: "billing@yourdomain.com",
  to: ["customer@example.com"],
  subject: "Your invoice",
  html: "<p>Invoice attached.</p>",
  attachments: [
    {
      name: "invoice.pdf",
      type: "application/pdf",
      data: base64EncodedString, // base64-encoded file content
    },
  ],
});

const { data } = await client.emails.schedule({
  from: "sender@yourdomain.com",
  to: ["recipient@example.com"],
  subject: "Reminder",
  html: "<p>Don't forget!</p>",
  scheduled_at: "2026-06-01T09:00:00Z",
});

// Look up or cancel later
await client.emails.getScheduled(data!.request_id);
await client.emails.cancelScheduled(data!.request_id);

// Or find it again without having kept the id
const { data: page } = await client.emails.listScheduled({ status: "scheduled" });

const { data, error } = await client.emails.send({ /* ... */ });

if (error) {
  switch (error.type) {
    case "validation":
      // 422 — invalid request. Field validation populates error.errors
      // (a field → messages map); precondition 422s (e.g. campaign_not_sendable)
      // leave it empty and carry error.error_code instead.
      if (Object.keys(error.errors).length > 0) {
        console.error("Field errors:", error.errors);
      } else {
        console.error("Precondition failed:", error.error_code);
      }
      break;
    case "api":
      // Other API errors. error.error_code is always present
      // (e.g. "unauthorized", "quota_exceeded", "not_found").
      console.error("API error:", error.error_code, error.message);
      break;
    case "network":
      // Connection failure, timeout, DNS — no response received.
      console.error("Network error:", error.message);
      break;
  }
  return;
}