DO NOT upgrade any Plunk dependencies unless you’re following their official migration guide and understand the breaking changes. Upgrading without proper migration can break your email sending functionality and template rendering. The current Plunk version in the boilerplate is tested and stable.

This guide covers working with email sending using Plunk in Titan.

Titan includes a complete email infrastructure that allows you to send transactional and marketing emails to your users. The system uses Plunk, a modern email service that provides beautiful email templates, reliable delivery, and detailed analytics.

​
Testing emails locally

You can test email functionality in your local development environment.

  1. Set config.email.enabled to true in config.ts

    // In config.ts
export const config = {
  // ... other config options
  email: {
    enabled: true, // Make sure this is set to true
  },
  // ... other config options
};

  2. Add your Plunk API key to your app’s environment variables

    PLUNK_API_KEY="your_plunk_api_key"

  3. Create email templates

    a. In the Plunk dashboard, go to ‘Templates’

    b. Create templates for each type of email you need (welcome, password reset, notifications, etc.)

    c. Note the template IDs for each template you create

  4. Run your app

    bun run dev

  5. Test sending emails

    You can test sending emails using the provided utility functions:

    // Example of sending an email
import { sendEmail } from '@/lib/email';

await sendEmail({
  to: 'user@example.com',
  templateId: 'your_template_id',
  variables: {
    userName: 'John Doe',
    // other template variables
  },
});

​
Common issues & troubleshooting

​
Emails not being sent

  • Verify your Plunk API key is correct and active
  • Check if config.email.enabled is set to true in your config
  • Look for error messages in your server logs

​
Emails going to spam

  • Ensure you’ve set up domain authentication in Plunk
  • Check your email content for spam triggers (excessive exclamation marks, all caps, spam-like phrases)
  • Gradually increase your sending volume rather than sending a large batch at once

​
Template variables not working

  • Double-check that the variable names in your code match exactly with those in your Plunk templates
  • Verify the format of the variables object you’re passing to the sendEmail function

For transactional emails, always provide a clear way for users to manage their email preferences or unsubscribe.