Greenhouse Email

Architecture Overview

src/
  emails/
    components/
      EmailLayout.tsx          # Shared layout: header gradient + body card + footer
      EmailButton.tsx          # Styled CTA button
    constants.ts               # Brand tokens: EMAIL_COLORS, EMAIL_FONTS, LOGO_URL, APP_URL
    [TemplateName]Email.tsx     # One file per template
    [TemplateName]Email.test.tsx # Optional test
  lib/
    email/
      types.ts                 # EmailType union, EmailDomain, interfaces
      templates.ts             # registerTemplate() + registerPreviewMeta()
      delivery.ts              # sendEmail() — central entry point
      context-resolver.ts      # Auto-resolves userName, clientName, locale from PG
      tokens.ts                # ResolvedEmailContext types + DEFAULT_PLATFORM_CONTEXT
      subscriptions.ts         # getSubscribers/addSubscriber for broadcast types
      unsubscribe.ts           # JWT-signed unsubscribe URLs
      rate-limit.ts            # 10 emails/hour per recipient
    ai/
      image-generator.ts       # generateImage() (Imagen 4) + generateAnimation() (Gemini → SVG)
      google-genai.ts          # GoogleGenAI Vertex AI client singleton
  resend.ts                    # Resend client singleton
public/
  images/
    emails/                    # Pre-generated hero/header images for email templates
    banners/                   # Profile banners (7 categories, Imagen 4)
    generated/                 # Ad-hoc generated images
  animations/
    generated/                 # SVG animations (Gemini)
scripts/
  generate-banners.mts         # Batch banner generation script (reference for email images)

Step-by-Step: Creating a New Email

Step 1 — Add the email type to the union

File: src/lib/email/types.ts

Add the new type to EmailType:

export type EmailType =
  | 'password_reset'
  | 'invitation'
  | 'verify_email'
  | 'payroll_export'
  | 'payroll_receipt'
  | 'notification'
  | 'your_new_type'          // ← add here

Step 2 — Create the React Email template

File: src/emails/YourNewEmail.tsx

Mandatory patterns:

import { Heading, Section, Text } from '@react-email/components'

import EmailButton from './components/EmailButton'
import EmailLayout from './components/EmailLayout'
import { EMAIL_COLORS, EMAIL_FONTS } from './constants'

// 1. Define a props interface — every prop has a default for preview
interface YourNewEmailProps {
  recipientName?: string
  someData: string
  locale?: 'es' | 'en'
  unsubscribeUrl?: string       // Only if broadcast type
}

// 2. Export default function with defaults on every prop
export default function YourNewEmail({
  recipientName = 'María González',
  someData = 'Preview value',
  locale = 'es',
  unsubscribeUrl
}: YourNewEmailProps) {
  // 3. Localization via inline t object (NOT i18n library)
  const t = locale === 'en' ? {
    heading: 'English heading',
    greeting: (name?: string) => name ? `Hi ${name},` : 'Hi,',
    cta: 'View in Greenhouse',
    fallback: 'If the button does not work, copy and paste this address into your browser:'
  } : {
    heading: 'Título en español',
    greeting: (name?: string) => name ? `Hola ${name?.split(' ')[0]},` : 'Hola,',
    cta: 'Ver en Greenhouse',
    fallback: 'Si el botón no funciona, copia y pega esta dirección en tu navegador:'
  }

  return (
    // 4. Always wrap in EmailLayout
    <EmailLayout previewText={t.heading} locale={locale} unsubscribeUrl={unsubscribeUrl}>
      {/* 5. Heading — Poppins, 24px, weight 700 */}
      <Heading style={{
        fontFamily: EMAIL_FONTS.heading,
        fontSize: '24px',
        fontWeight: 700,
        color: EMAIL_COLORS.text,
        margin: '0 0 8px',
        lineHeight: '32px'
      }}>
        {t.heading}
      </Heading>

      {/* 6. Greeting text */}
      <Text style={{
        fontSize: '15px',
        color: EMAIL_COLORS.secondary,
        lineHeight: '24px',
        margin: '0 0 20px'
      }}>
        {t.greeting(recipientName)}
      </Text>

      {/* 7. Body content */}
      <Text style={{
        fontSize: '15px',
        color: EMAIL_COLORS.secondary,
        lineHeight: '24px',
        margin: '0 0 28px'
      }}>
        {/* Your content here */}
      </Text>

      {/* 8. CTA button — centered section */}
      <Section style={{ textAlign: 'center' as const, margin: '0 0 28px' }}>
        <EmailButton href="https://greenhouse.efeoncepro.com/path">
          {t.cta}
        </EmailButton>
      </Section>

      {/* 9. Fallback URL for email clients that hide buttons */}
      <Text style={{
        fontSize: '12px',
        color: EMAIL_COLORS.muted,
        lineHeight: '18px',
        margin: '0',
        wordBreak: 'break-all'
      }}>
        {t.fallback} {'https://greenhouse.efeoncepro.com/path'}
      </Text>
    </EmailLayout>
  )
}

Style reference — use these exact tokens:

// Colors (from src/emails/constants.ts)
EMAIL_COLORS.background   // '#F2F4F7' — page background
EMAIL_COLORS.containerBg  // '#FFFFFF' — card background
EMAIL_COLORS.headerBg     // '#022a4e' — Midnight Navy
EMAIL_COLORS.headerAccent // '#0375db' — Core Blue gradient stop
EMAIL_COLORS.primary      // '#0375db' — CTA buttons, links
EMAIL_COLORS.primaryHover // '#025bb0'
EMAIL_COLORS.text         // '#1A1A2E' — headings
EMAIL_COLORS.secondary    // '#344054' — body text
EMAIL_COLORS.muted        // '#667085' — disclaimers, footer
EMAIL_COLORS.border       // '#E4E7EC' — separators
EMAIL_COLORS.success      // '#12B76A' — positive indicators
EMAIL_COLORS.footerBg     // '#F9FAFB'

// Fonts
EMAIL_FONTS.heading  // Poppins — for headings and CTA text
EMAIL_FONTS.body     // DM Sans — for body text

// URLs
LOGO_URL  // 'https://greenhouse.efeoncepro.com/branding/logo-white-email.png'
APP_URL   // 'https://greenhouse.efeoncepro.com'

Data display patterns (for emails with tables/summaries):

// Summary row pattern (from PayrollReceiptEmail)
const summaryRow = (label: string, value: string, emphasis = false) => (
  <table style={{ width: '100%', borderCollapse: 'collapse', borderBottom: `1px solid ${EMAIL_COLORS.border}` }}>
    <tbody>
      <tr>
        <td style={{ padding: '10px 0', fontFamily: EMAIL_FONTS.body, fontSize: '14px', color: EMAIL_COLORS.secondary, fontWeight: 500, width: '55%' }}>
          {label}
        </td>
        <td style={{ padding: '10px 0', fontFamily: EMAIL_FONTS.heading, fontSize: emphasis ? '18px' : '15px', color: EMAIL_COLORS.text, fontWeight: emphasis ? 700 : 600, textAlign: 'right', whiteSpace: 'nowrap' }}>
          {value}
        </td>
      </tr>
    </tbody>
  </table>
)

// Summary card wrapper
<Section style={{
  backgroundColor: '#F8FAFC',
  border: `1px solid ${EMAIL_COLORS.border}`,
  borderRadius: '12px',
  padding: '18px 18px 8px',
  margin: '0 0 24px',
}}>
  {summaryRow('Label', 'Value')}
  {summaryRow('Total', '$1,000', true)}
</Section>

Step 3 — Register the template

File: src/lib/email/templates.ts

Add import at top:

import YourNewEmail from '@/emails/YourNewEmail'

Add registerTemplate() call (after the existing ones, before the preview meta section):

registerTemplate('your_new_type', (context: {
  // List ALL props the template needs
  someData: string
  recipientName?: string
  locale?: 'es' | 'en'
  unsubscribeUrl?: string        // Only for broadcast types
}) => {
  const locale = context.locale || 'es'

  return {
    subject: locale === 'en'
      ? 'English subject — Greenhouse'
      : 'Asunto en español — Greenhouse',
    react: YourNewEmail({
      someData: context.someData,
      recipientName: context.recipientName,
      locale,
      unsubscribeUrl: context.unsubscribeUrl
    }),
    text: buildYourNewPlainText(context)   // Plain text fallback
    // attachments: [...]                   // Optional: for emails with PDF/CSV
  }
})

Plain text builder pattern:

const buildYourNewPlainText = (context: {
  someData: string
  recipientName?: string
  locale?: 'es' | 'en'
}) => {
  const locale = context.locale || 'es'
  const greeting = locale === 'en'
    ? (context.recipientName ? `Hi ${context.recipientName},` : 'Hi,')
    : (context.recipientName ? `Hola ${context.recipientName.split(' ')[0]},` : 'Hola,')

  return [
    greeting,
    '',
    '... plain text body ...',
    '',
    `→ ${process.env.NEXT_PUBLIC_APP_URL || 'https://greenhouse.efeoncepro.com'}/path`,
    '',
    '— Greenhouse by Efeonce Group'
  ].filter(Boolean).join('\n')
}

Step 4 — Register preview metadata

File: src/lib/email/templates.ts (at the end, in the preview meta section)

registerPreviewMeta('your_new_type', {
  label: 'Label descriptivo en español',
  description: 'Descripción breve del email para el admin preview',
  domain: 'finance',   // One of: 'identity' | 'payroll' | 'finance' | 'hr' | 'delivery' | 'system'
  supportsLocale: true,
  defaultProps: {
    someData: 'Valor de ejemplo para preview',
    recipientName: 'María González'
  },
  propsSchema: [
    { key: 'someData', label: 'Datos principales', type: 'text' },
    { key: 'recipientName', label: 'Nombre del destinatario', type: 'text' }
    // type: 'text' | 'number' | 'select' | 'boolean'
    // For select: add options: ['opt1', 'opt2']
  ]
})

Step 5 — Send the email (from API route or service)

import { sendEmail } from '@/lib/email/delivery'

// Pattern A: Direct send (with explicit recipients)
await sendEmail({
  emailType: 'your_new_type',
  domain: 'finance',
  recipients: [{ email: '[email protected]', name: 'User Name', userId: 'user-123' }],
  context: {
    someData: 'actual value'
    // recipientName auto-hydrated by context-resolver if not provided
    // locale auto-hydrated from client_users.locale
  },
  sourceEntity: 'your_feature_name',
  actorEmail: session.user.email
})

// Pattern B: Broadcast (auto-resolves subscribers from email_subscriptions)
await sendEmail({
  emailType: 'your_new_type',
  domain: 'finance',
  // recipients omitted — pulls from email_subscriptions table
  context: { someData: 'actual value' },
  attachments: [{ filename: 'report.pdf', content: pdfBuffer, contentType: 'application/pdf' }]
})

Domain Types

Auto-Hydrated Context

The delivery layer (sendEmail()) auto-resolves these fields for every recipient via PostgreSQL lookup. You do NOT need to provide them — they are injected into the template context automatically:

Caller-provided values take precedence over auto-resolved values.

Broadcast Emails (subscription-based)

For broadcast emails (e.g., payroll_export, notifications that go to all subscribers):

1. Add your type to BROADCAST_EMAIL_TYPES in src/lib/email/delivery.ts (line ~404)
2. Accept unsubscribeUrl?: string in your template props
3. Pass unsubscribeUrl to <EmailLayout>
4. Manage subscribers via src/lib/email/subscriptions.ts:
   • addSubscriber(emailType, email, name?, userId?)
   • removeSubscriber(emailType, email)
   • getSubscribers(emailType) — called automatically by sendEmail() when no recipients provided

Attachments

Templates can return attachments in the EmailTemplateRenderResult:

return {
  subject: '...',
  react: <Component />,
  text: '...',
  attachments: [{
    filename: 'report.pdf',
    content: pdfBuffer,       // Buffer
    contentType: 'application/pdf'
  }]
}

Callers can also pass attachments via sendEmail({ attachments }). Both are merged.

AI Visual Enrichment (Imagen 4 + Gemini)

Emails can include AI-generated hero images to make them visually richer. The project uses Imagen 4 (raster images) via Vertex AI.

Image Design Process (MANDATORY)

Before generating any image, ALWAYS invoke the /greenhouse-ux skill first to get a design brief for the hero image. The UX advisor decides:

• What clay 3D objects best represent the email's purpose
• Which brand colors to use for each object
• The composition and visual metaphor

Process:

1. Invoke /greenhouse-ux — describe the email's purpose and ask for the hero image brief (objects, colors, composition)
2. Receive the Imagen 4 prompt from the UX advisor — it will include the correct objects, brand colors, and white background directives
3. Generate with Imagen 4 using the UX-approved prompt
4. Resize + upload to GCS following the workflow below

Do NOT skip the UX step and write prompts directly — the UX advisor ensures visual coherence with the email design system (white bg, brand navy/blue/teal/green, clay 3D style, semantically relevant objects).

Image Storage: GCS Public Buckets (NOT Vercel)

CRITICAL: Email images MUST be stored in the GCS public media bucket, NOT in public/ served by Vercel. Reasons learned from production:

1. Vercel staging has SSO Protection — the browser cannot load images from Vercel URLs in email previews or real emails
2. NEXT_PUBLIC_APP_URL is not set in Vercel — URL resolution breaks across environments
3. GCS public buckets are accessible without auth, work in all email clients, and are environment-aware

Buckets per environment:

Env var: GREENHOUSE_PUBLIC_MEDIA_BUCKET — set per environment in Vercel.

Workflow for Adding Images to an Email

1. Generate the image using Imagen 4 (via script or API)
2. Resize to 560px width using sips --resampleWidth 560 (macOS) — target under 200KB
3. Upload to BOTH GCS buckets:

   gcloud storage cp image.png gs://efeonce-group-greenhouse-public-media-staging/emails/image.png
   gcloud storage cp image.png gs://efeonce-group-greenhouse-public-media-prod/emails/image.png
   

4. Also commit to public/images/emails/ for local dev and as a git record
5. Reference in the template using the GCS URL resolved from the bucket env var:

const MEDIA_BUCKET = process.env.GREENHOUSE_PUBLIC_MEDIA_BUCKET || 'efeonce-group-greenhouse-public-media-prod'
const HERO_IMAGE_URL = `https://storage.googleapis.com/${MEDIA_BUCKET}/emails/your-image.png`

Image Generation API

Core module: src/lib/ai/image-generator.ts

import { generateImage } from '@/lib/ai/image-generator'

const result = await generateImage(
  'Clay 3D render on a pure white background. [describe objects]...',
  { aspectRatio: '16:9', format: 'png', filename: 'email-hero-name.png' }
)

Batch script: scripts/generate-email-images.mts — run with npx tsx scripts/generate-email-images.mts

Prompt Guidelines for Email Hero Images

Mandatory style: Clay 3D on white background. This is the canonical style for Greenhouse email heroes.

Prompt structure:

Clay 3D render on a pure white background. [Describe the main object in midnight navy (#022a4e)].
[Describe secondary objects using core blue (#0375db) and teal accents].
[Describe small accent in success green (#12B76A) if approval-related].
All objects have rounded edges, matte clay textures, and cast soft diffused shadows
directly below onto the white surface. Minimal composition, centered, professional.
Soft ambient studio lighting from above. Cool neutral shadows, no warm tones.
No text, no people, no logos. 16:9 aspect ratio.

Rules:

• ALWAYS use pure white background — the image sits inside a white email card, must blend seamlessly
• ALWAYS use clay 3D style: matte clay textures, rounded edges, soft diffused shadows
• ALWAYS use brand colors for objects: midnight navy (#022a4e) as primary, core blue (#0375db) as accent, success green (#12B76A) for positive elements
• ALWAYS include: No text, no people, no logos
• ALWAYS include: Cool neutral shadows, no warm tones — prevents Imagen from adding warm tinted backgrounds
• NEVER use dark backgrounds, abstract gradients, glass morphism, or tech-circuit aesthetics — those are for profile banners, not emails
• Choose objects that are semantically related to the email content (calendar for leave, clipboard for review, invoice for finance, etc.)
• Keep composition centered and minimal — the image is small (560×305), complex scenes become noisy

Domain object mapping (clay 3D):

Using Images in EmailLayout

Place the <Img> as the first child inside <EmailLayout>:

import { Img } from '@react-email/components'

const MEDIA_BUCKET = process.env.GREENHOUSE_PUBLIC_MEDIA_BUCKET || 'efeonce-group-greenhouse-public-media-prod'
const HERO_IMAGE_URL = `https://storage.googleapis.com/${MEDIA_BUCKET}/emails/your-image.png`

// Inside the component:
<EmailLayout previewText={t.heading} locale={locale}>
  <Img
    src={HERO_IMAGE_URL}
    alt=""
    width={560}
    height={305}
    style={{
      width: '100%',
      height: 'auto',
      borderRadius: '8px',
      margin: '0 0 24px',
      display: 'block'
    }}
  />
  {/* rest of email content */}
</EmailLayout>

Post-Generation Checklist

• Generated with Imagen 4 (imagen-4.0-generate-001)
• White background, clay 3D style, brand colors
• Resized to 560px width (sips --resampleWidth 560)
• File size under 200KB (PNG)
• Uploaded to staging GCS bucket (gcloud storage cp)
• Uploaded to prod GCS bucket (gcloud storage cp)
• Committed to public/images/emails/ in git (local dev + record)
• Template references GREENHOUSE_PUBLIC_MEDIA_BUCKET env var for URL
• alt="" (decorative), width and height attributes set
• Verified in admin preview (/admin/emails/preview)

Email Client Compatibility Notes

• Always use absolute GCS URLs — never Vercel URLs or relative paths
• Always set width and height attributes — many email clients need them for layout
• Use alt="" for decorative images (screen readers skip them)
• PNG only — Gmail, Outlook, and Apple Mail all support PNG; WebP support is inconsistent
• Max image width: 560px — matches the <Container> max-width in EmailLayout
• Keep file size under 200KB per image — large images get clipped or blocked
• SVG animations do NOT work in email — email clients strip <style> and <script>. Only use raster PNG in emails

Conventions & Rules

1. File naming: PascalCaseEmail.tsx in src/emails/ — always suffix with Email
2. Default props: Every prop MUST have a sensible default for the preview server
3. Localization: Use inline t object pattern, NOT i18n libraries. Spanish is default.
4. Greeting: Spanish uses first name only (name.split(' ')[0]), English uses full name
5. Plain text: Every template MUST have a plain text version for accessibility
6. No external state: Templates are pure functions — no hooks, no fetch, no server calls
7. Inline styles only: React Email does not support CSS classes — all styles are inline objects
8. as const for textAlign: Always cast textAlign: 'center' as const (TypeScript requirement)
9. EmailLayout wraps everything: Never render <Html> or <Body> directly in a template
10. EmailButton for CTAs: Never use raw <Button> from @react-email/components
11. Import from components/: EmailLayout and EmailButton live in src/emails/components/
12. Import constants: Always use EMAIL_COLORS and EMAIL_FONTS from src/emails/constants.ts
13. No emojis in subjects: Keep subjects professional, use em dash (—) as separator
14. Subject pattern: "Descriptive text — Greenhouse" or "Descriptive text — Period/Context"
15. Money formatting: CLP → $1.234.567 (no decimals), USD → US$1,234.56

Checklist for New Email

• Added type to EmailType union in src/lib/email/types.ts
• Created src/emails/[Name]Email.tsx with defaults on all props
• Template uses EmailLayout, EmailButton, EMAIL_COLORS, EMAIL_FONTS
• Localization (es/en) via inline t object
• Registered via registerTemplate() in src/lib/email/templates.ts
• Plain text fallback builder function
• Registered via registerPreviewMeta() for admin preview
• If broadcast: added to BROADCAST_EMAIL_TYPES + accepts unsubscribeUrl
• Sending code uses sendEmail() from src/lib/email/delivery.ts
• Subject follows pattern: "Text — Context" (no emojis)
• If using AI images: clay 3D on white bg, brand colors, resized to 560px, under 200KB
• If using AI images: uploaded to BOTH GCS public buckets (staging + prod), committed to git
• If using AI images: template uses GREENHOUSE_PUBLIC_MEDIA_BUCKET env var for URL resolution
• If email is sent via outbox/notification projection: redeploy ops-worker (bash services/ops-worker/deploy.sh from repo root)
• pnpm build passes
• npx tsc --noEmit passes

ops-worker Cloud Run (CRITICAL for production emails)

IMPORTANT: Emails triggered by outbox events (leave requests, payroll, etc.) are processed by the ops-worker Cloud Run service, NOT by Vercel serverless functions. The ops-worker bundles the email templates at build time via esbuild. If you add or modify email templates, you MUST redeploy the ops-worker or the new templates won't be available in production.

When to redeploy ops-worker:

• Any change to src/lib/email/templates.ts (new registrations)
• Any change to src/emails/*.tsx (new or modified templates)
• Any change to src/lib/sync/projections/notifications.ts (new email dispatch logic)
• Any change to src/lib/email/delivery.ts (delivery behavior)

How to redeploy:

# From the repo root (NOT from services/ops-worker/)
bash services/ops-worker/deploy.sh

Verify deployment:

gcloud run revisions list --service ops-worker --region us-east4 --project efeonce-group --limit 3

Architecture: The ops-worker runs 3 Cloud Scheduler jobs every 5 minutes that process outbox events → notification projection → sendEmail(). Vercel only handles the admin preview API and the test send endpoint — it does NOT process outbox events in production.

Dev Preview

# Start React Email preview server on port 3001
pnpm email:dev

Templates with default props render in the browser for visual testing. Admin preview is available at /api/admin/emails/preview?template=your_new_type&locale=es.

Reference Files