@crossplatformai/email

Shared email module providing a unified interface for sending emails across CrossPlatform.ai projects.

Features

• ✅ Framework-agnostic: Works with Hono, Next.js, Express, or any framework
• ✅ Email providers: Postmark, Mock (for development)
• ✅ Type-safe: Full TypeScript support
• ✅ Lightweight runtime: Only React Email dependencies for templates
• ✅ React Email: Beautiful, responsive email templates built with React Email

Installation

npm install @crossplatformai/email

Usage

Basic Setup

import { createEmailProvider } from '@crossplatformai/email';
import type { EmailConfig } from '@crossplatformai/email';
import { reactEmailRenderer } from '@crossplatformai/email/react';

const emailProvider = createEmailProvider(
  {
    provider: 'postmark',
    apiKey: process.env.POSTMARK_API_KEY,
    from: '[email protected]',
    appName: 'My App',
    isDevelopment: process.env.NODE_ENV === 'development',
  },
  reactEmailRenderer,
);

// Send emails
await emailProvider.sendVerificationCode('[email protected]', '123456');
await emailProvider.sendWelcome('[email protected]');

With React Email Renderer

import { createEmailProvider } from '@crossplatformai/email';
import { reactEmailRenderer } from '@crossplatformai/email/react';

const emailProvider = createEmailProvider(
  {
    provider: 'postmark',
    apiKey: process.env.POSTMARK_API_KEY,
    from: '[email protected]',
    appName: 'My App',
    isDevelopment: process.env.NODE_ENV === 'development',
  },
  reactEmailRenderer,
);

With Hono (API Framework)

import { Hono } from 'hono';
import { createEmailProvider } from '@crossplatformai/email';
import { reactEmailRenderer } from '@crossplatformai/email/react';

const app = new Hono();
const emailProvider = createEmailProvider(
  {
    provider: 'postmark',
    apiKey: process.env.POSTMARK_API_KEY,
    from: '[email protected]',
    appName: 'My App',
  },
  reactEmailRenderer,
);

app.post('/send-verification', async (c) => {
  const { email, code } = await c.req.json();

  try {
    await emailProvider.sendVerificationCode(email, code);
    return c.json({ success: true });
  } catch (error) {
    return c.json({ error: 'Failed to send email' }, 500);
  }
});

With Next.js (Route Handler)

import { NextResponse } from 'next/server';
import { createEmailProvider } from '@crossplatformai/email';
import { reactEmailRenderer } from '@crossplatformai/email/react';

const emailProvider = createEmailProvider(
  {
    provider: 'postmark',
    apiKey: process.env.POSTMARK_API_KEY,
    from: '[email protected]',
    appName: 'My App',
  },
  reactEmailRenderer,
);

export async function POST(request: Request) {
  const { email, code } = await request.json();

  try {
    await emailProvider.sendVerificationCode(email, code);
    return NextResponse.json({ success: true });
  } catch (error) {
    return NextResponse.json(
      { error: 'Failed to send email' },
      { status: 500 },
    );
  }
}

Configuration

Environment Variables

# Email provider configuration
EMAIL_PROVIDER=postmark        # Email provider (postmark or mock)
POSTMARK_API_KEY=your-api-key  # Postmark API key
[email protected]  # From email address
WEB_URL=https://yourdomain.com # Base URL for email links
POSTMARK_API_URL=https://api.postmarkapp.com # Optional: custom Postmark API URL

EmailConfig Interface

interface EmailConfig {
  provider?: 'postmark' | 'mock'; // Email provider
  apiKey?: string; // API key for provider
  from?: string; // From email address
  isDevelopment?: boolean; // Development mode flag
  isTest?: boolean; // Test mode flag
  appName: string; // App name for email branding
  colors?: EmailColorTokens; // Custom color tokens
  renderer?: EmailRenderer; // Email renderer for templates
}

Providers

PostmarkEmailProvider

Production-ready email provider using Postmark API:

• Sends real emails via Postmark
• Requires API key
• Full HTML and text email support

MockEmailProvider

Development/testing provider that logs emails to console:

• No actual emails sent
• Logs email content to console
• Perfect for development and testing

Development Mode (Mock Provider)

const emailProvider = createEmailProvider({
  provider: 'mock', // No actual emails sent
  isDevelopment: true,
});

// Logs to console instead of sending emails
await emailProvider.sendVerificationCode('[email protected]', '123456');
// Console: [MOCK EMAIL] Verification code for [email protected]: 123456 (expires in 60 minutes)

API Reference

createEmailProvider(config, renderer?)

Factory function to create an email provider instance.

Parameters:

• config: EmailConfig - Configuration object
• renderer?: EmailRenderer - Optional email renderer (required for Postmark)

Returns: EmailProvider

Subpath Exports

• @crossplatformai/email - Main exports (createEmailProvider, types, providers, colors)
• @crossplatformai/email/providers - Provider implementations (PostmarkEmailProvider, MockEmailProvider)
• @crossplatformai/email/react - React Email renderer and templates
• @crossplatformai/email/types - TypeScript type definitions

Testing

# Run tests
pnpm test

# Run tests with coverage
pnpm test --coverage

License

SEE LICENSE IN LICENSE