> ## Documentation Index
> Fetch the complete documentation index at: https://blueprint.codeandcreed.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Emails

> Setup automated emails with Plunk

<Warning>
  **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.
</Warning>

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

<Note>
  You can test email functionality in your local development environment.
</Note>

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

   ```typescript theme={null}
   // 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

   ```txt theme={null}
   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

   ```bash theme={null}
   bun run dev
   ```

5. Test sending emails

   You can test sending emails using the provided utility functions:

   ```typescript theme={null}
   // 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

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