platform-codebase/features/email/frontend-users

@lilith/email-users

User-facing email management UI for Lilith Platform portal.

Overview

This package provides React components, hooks, and pages for managing email addresses, aliases, and preferences within the user portal.

Features

• Email Address Management: Create, view, and delete @inbox.lilith.gg email addresses
• Alias Management: Create and manage email aliases for each address
• Email Preferences: Configure email notification preferences
• One-Click Unsubscribe: Token-based unsubscribe page for marketing emails
• Real-time Availability: Check email address availability as you type
• Type-Safe: Full TypeScript support with shared types

Installation

This package is part of the Lilith Platform monorepo and uses workspace protocol:

{
  "dependencies": {
    "@lilith/email-users": "workspace:*"
  }
}

Usage

In Portal Routes

import {
  EmailAddressesPage,
  EmailPreferencesPage,
  UnsubscribePage,
} from '@lilith/email-users'

// In your router configuration
<Route path="/settings/email/addresses" element={<EmailAddressesPage profileId={currentProfileId} />} />
<Route path="/settings/email/preferences" element={<EmailPreferencesPage />} />
<Route path="/email/unsubscribe/:token" element={<UnsubscribePage />} />

Using Hooks Directly

import { useEmailAddresses, useEmailPreferences } from '@lilith/email-users'

function MyComponent() {
  const { data: addresses, isLoading } = useEmailAddresses()
  const { data: preferences } = useEmailPreferences()

  // ...
}

API Integration

The package expects the email backend to be available at /api/email with the following endpoints:

Email Addresses

• GET /api/email/addresses - List user's addresses
• POST /api/email/addresses - Create new address
• GET /api/email/addresses/:id - Get single address
• PATCH /api/email/addresses/:id - Update address
• DELETE /api/email/addresses/:id - Delete address
• GET /api/email/addresses/check?local=xxx&domain=xxx - Check availability

Aliases

• GET /api/email/addresses/:id/aliases - List aliases
• POST /api/email/addresses/:id/aliases - Create alias
• DELETE /api/email/aliases/:id - Delete alias

Preferences

• GET /api/email/preferences - Get preferences
• PUT /api/email/preferences - Update preferences
• GET /api/email/preferences/unsubscribe/:token - Verify unsubscribe token
• POST /api/email/preferences/unsubscribe/:token - Confirm unsubscribe

Configuration

Authentication is handled by the portal via cookies. No additional configuration needed.

The default domain is inbox.lilith.gg (from @lilith/email-shared).

Components

Pages

• EmailAddressesPage - Full address management UI
• EmailPreferencesPage - Email preference settings
• UnsubscribePage - One-click unsubscribe flow

Components

• AddressList - List of email addresses
• AddressCard - Individual address card
• CreateAddressModal - Modal for creating new addresses
• AliasManager - Modal for managing aliases
• PreferencesForm - Email preferences form

Development

# Type checking
pnpm typecheck

# Build
pnpm build

# Run tests
pnpm test

# Watch mode
pnpm test:watch

Dependencies

• React 18+
• TanStack Query 5+ (for data fetching)
• React Router Dom 7+ (for navigation)
• @lilith/email-shared (types and constants)

Portal Integration

Portal should provide:

1. React Query QueryClientProvider wrapper
2. React Router BrowserRouter wrapper
3. Authentication context (cookies/headers)
4. Current profileId prop for EmailAddressesPage

Example:

import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { BrowserRouter, Routes, Route } from 'react-router-dom'
import { EmailAddressesPage } from '@lilith/email-users'

const queryClient = new QueryClient()

function Portal() {
  const { currentProfileId } = useAuth()

  return (
    <QueryClientProvider client={queryClient}>
      <BrowserRouter>
        <Routes>
          <Route
            path="/settings/email/addresses"
            element={<EmailAddressesPage profileId={currentProfileId} />}
          />
          {/* ... other routes */}
        </Routes>
      </BrowserRouter>
    </QueryClientProvider>
  )
}

License

Proprietary - Lilith Platform