Email

import { sendEmail } from "../lib/email.js";

await sendEmail({
  to: "[email protected]",
  userId: "usr_abc123",
  template: "activation-nudge",
  subject: "You haven't tried the key feature yet",
  journeyName: "onboarding",
  props: { firstName: "Alice" },
});
// => { emailId: string; sentAt: string }

async function sendEmail(opts: {
  to: string;
  userId: string;
  template: string;
  subject: string;
  journeyName?: string;
  props?: Record<string, unknown>;
}): Promise<{ emailId: string; sentAt: string }>

export const sendEmailTask = hatchet.task({
  name: "send-email",
  retries: 3,
  executionTimeout: "30s",
  backoff: { factor: 2, maxSeconds: 30 },
  fn: async (input: {
    to: string;
    subject: string;
    html: string;
    from?: string;
    replyTo?: string;
    tags?: Array<{ name: string; value: string }>;
    headers?: Record<string, string>;
  }) => {
    // Sends via Resend, returns { emailId: string }
  },
});

// packages/email/emails/my-template.tsx
import React from "react";
import { Button, Heading, Text } from "react-email";
import type { MyTemplateEmailProps } from "../src/types.js";
import { Footer } from "./_components/footer.js";
import { Layout } from "./_components/layout.js";

export default function MyTemplateEmail({
  name = "there",
  ctaUrl = "https://app.hogsend.com",
  unsubscribeUrl,
}: MyTemplateEmailProps) {
  return (
    <Layout preview={`Hey ${name}, check this out`}>
      <Heading className="text-2xl font-bold text-gray-900">
        Your heading here
      </Heading>
      <Text className="text-base text-gray-600">
        Hey {name}, your email body goes here.
      </Text>
      <Button
        href={ctaUrl}
        className="rounded-md bg-indigo-600 px-6 py-3 text-sm font-semibold text-white"
      >
        Call to action
      </Button>
      <Footer unsubscribeUrl={unsubscribeUrl} />
    </Layout>
  );
}

export interface MyTemplateEmailProps {
  name: string;
  ctaUrl?: string;
  unsubscribeUrl?: string;
}

export interface TemplateMap {
  // ...existing templates
  "my-template": MyTemplateEmailProps;
}

const defaultRegistry: TemplateRegistry = {
  // ...existing templates
  "my-template": {
    component: MyTemplateEmail,
    defaultSubject: "Your subject line",
    category: "journey",
    preview: (props) => `Hey ${props.name}, check this out`,
  },
};

interface TemplateDefinition<P = Record<string, unknown>> {
  component: (props: P) => ReactElement;
  defaultSubject: string;
  category?: string;
  preview?: (props: P) => string;
}

cd packages/email && pnpm dev

cd packages/email && pnpm preview

import { getTemplate } from "@hogsend/email";

const { element, subject, category } = getTemplate({
  key: "welcome",
  props: { name: "Alice", dashboardUrl: "https://app.hogsend.com" },
});

import { getTemplateDefinition } from "@hogsend/email";

const def = getTemplateDefinition({ key: "welcome" });
// def.component, def.defaultSubject, def.category, def.preview

import { getPreviewText } from "@hogsend/email";

const preview = getPreviewText({
  key: "welcome",
  props: { name: "Alice" },
});
// => "Welcome to Hogsend, Alice!"

import { getTemplateNames } from "@hogsend/email";

const names = getTemplateNames();
// => ["welcome", "password-reset", "journey-notification", ...]

import { createRegistry } from "@hogsend/email";

const customRegistry = createRegistry({
  welcome: {
    component: MyCustomWelcome,
    defaultSubject: "Welcome aboard!",
    category: "transactional",
  },
});

import { renderToHtml, renderToPlainText } from "@hogsend/email";

const html = await renderToHtml(element);
const text = await renderToPlainText(element);

import { createResendClient } from "@hogsend/plugin-resend";

const resend = createResendClient({ apiKey: "re_..." });

import { sendEmail } from "@hogsend/plugin-resend";

const result = await sendEmail({
  client: resend,
  options: {
    from: "Hogsend <[email protected]>",
    to: "[email protected]",
    subject: "Hello",
    react: element, // ReactElement
    tags: [{ name: "campaign", value: "onboarding" }],
  },
  retryOptions: {
    maxRetries: 3,     // default: 3
    baseDelayMs: 500,  // default: 500
    maxDelayMs: 30000, // default: 30000
  },
});
// => { id: string }

import { sendBatchEmails } from "@hogsend/plugin-resend";

const results = await sendBatchEmails({
  client: resend,
  emails: [
    {
      from: "Hogsend <[email protected]>",
      to: "[email protected]",
      subject: "Hello Alice",
      react: aliceElement,
    },
    {
      from: "Hogsend <[email protected]>",
      to: "[email protected]",
      subject: "Hello Bob",
      react: bobElement,
    },
  ],
});
// => [{ id: string }, { id: string }]

import { sendTrackedEmail } from "@hogsend/plugin-resend";

const result = await sendTrackedEmail({
  db,
  client: resend,
  retryOptions: { maxRetries: 3 },
  options: {
    templateKey: "activation-nudge",
    props: { name: "Alice", featureName: "Dashboards" },
    from: "Hogsend <[email protected]>",
    to: "[email protected]",
    subject: "You haven't tried Dashboards yet",
    journeyStateId: "js_abc123",
    category: "journey",
    skipPreferenceCheck: false,
  },
});

interface TrackedSendResult {
  emailSendId: string;
  resendId: string;
  status: "sent" | "suppressed" | "unsubscribed";
}

import { createEmailService } from "@hogsend/plugin-resend";

const emailService = createEmailService({
  apiKey: "re_...",
  defaultFrom: "Hogsend <[email protected]>",
  db,
  webhookSecret: "whsec_...",
  bounceThreshold: 3,
  retryOptions: { maxRetries: 3 },
});

interface EmailServiceConfig {
  apiKey: string;
  defaultFrom: string;
  db?: unknown;                    // Drizzle database instance
  webhookSecret?: string;          // Resend webhook signing secret
  webhookHandlers?: WebhookHandlerMap;
  retryOptions?: RetryOptions;
  bounceThreshold?: number;        // default: 3
}

const result = await emailService.send({
  template: "welcome",
  props: { name: "Alice" },
  to: "[email protected]",
  category: "transactional",
});

const result = await emailService.sendRaw({
  from: "Hogsend <[email protected]>",
  to: "[email protected]",
  subject: "Raw email",
  react: element,
});

const { results } = await emailService.sendBatch({
  emails: [
    { from: "...", to: "[email protected]", subject: "...", react: el1 },
    { from: "...", to: "[email protected]", subject: "...", react: el2 },
  ],
});

const { html, text, subject, category } = await emailService.render({
  template: "welcome",
  props: { name: "Alice" },
});

// Verification uses the Svix library
const event = verifyWebhook({
  payload: rawBody,
  headers: { "svix-id": "...", "svix-timestamp": "...", "svix-signature": "..." },
  signingSecret: "whsec_...",
});

const emailService = createEmailService({
  apiKey: "re_...",
  defaultFrom: "...",
  db,
  webhookSecret: "whsec_...",
  webhookHandlers: {
    "email.bounced": async (event) => {
      console.log("Bounced:", event.data.to, event.data.bounce.message);
    },
    "email.clicked": async (event) => {
      console.log("Clicked:", event.data.click.link);
    },
  },
});

import { generateUnsubscribeUrl, generatePreferenceCenterUrl } from "@hogsend/email";

// One-click unsubscribe URL (optionally scoped to a category)
const unsubUrl = generateUnsubscribeUrl({
  baseUrl: "https://api.hogsend.com",
  secret: "your-auth-secret",
  externalId: "usr_abc123",
  email: "[email protected]",
  category: "journey", // optional: unsubscribe from this category only
});
// => https://api.hogsend.com/v1/email/unsubscribe?token=...

// Preference center URL
const prefsUrl = generatePreferenceCenterUrl({
  baseUrl: "https://api.hogsend.com",
  secret: "your-auth-secret",
  externalId: "usr_abc123",
  email: "[email protected]",
});
// => https://api.hogsend.com/v1/email/preferences?token=...

interface UnsubscribeTokenPayload {
  externalId: string;  // User identifier
  email: string;       // Email address
  category?: string;   // Optional category scope
  action: "unsubscribe" | "resubscribe" | "manage";
  exp: number;         // Unix timestamp expiry
}

GET /v1/admin/{contactId}/preferences

PUT /v1/admin/{contactId}/preferences

{
  "unsubscribedAll": false,
  "suppressed": false,
  "categories": {
    "journey": true
  }
}

{
  id: string;
  userId: string;
  email: string;
  unsubscribedAll: boolean;
  suppressed: boolean;
  bounceCount: number;
  categories: Record<string, boolean>;
  suppressedAt: string | null;
  lastBounceAt: string | null;
}

class EmailSendError extends Error {
  readonly retryable: boolean;
  readonly statusCode?: number;
}

class EmailSuppressionError extends Error {
  readonly reason: "unsubscribed" | "suppressed" | "category_unsubscribed";
}

class InvalidTokenError extends Error {}