Email & Webhook Integration Guide

This guide explains how to use the email service and webhook handler in your Mindful Auth template for sending transactional emails via Postmark API.

Get Started with Postmark

Create an account at https://www.postmarkapp.com/?via=mindfulauth (affiliate link).

The template includes two key components for email integration:

• src/lib/email.ts – Email service that sends transactional emails via Postmark
• src/pages/api/public/webhooks/mauth-webhook.ts – Webhook handler that receives events from Mindful Auth and triggers emails

Prerequisites

1. Postmark Account – Create an account at postmarkapp.com (affiliate link)
2. Verified Sender – Add and verify your sender email address in Postmark
3. API Token – Generate a server API token from Postmark
4. Mindful Auth Account – Have your Mindful Auth instance configured and running

Setup Instructions

1. Configure Environment Variables

Add the following environment variables to your .env or deployment configuration:

POSTMARK_API_TOKEN=your_postmark_server_api_token
EMAIL_FROM=Your App Name <no-reply@example.com>

Notes:

• Replace your_postmark_server_api_token with your actual Postmark server API token
• EMAIL_FROM must be a verified sender address in Postmark (format: Display Name <email@example.com>)

2. Configure Webhook in Mindful Auth

In your Mindful Auth dashboard:

1. Go to Webhooks settings
2. Add a new webhook with:
   • URL: https://app.yourdomain.com/api/public/webhooks/mauth-webhook
   • Events: Select verify_email, password_reset, and magic_login
3. Save the webhook configuration

Replace yourdomain.com with your actual domain.

3. Deploy

Deploy your application to make the webhook endpoint publicly accessible:

npm run build
npm run deploy  # or your deployment command

How It Works

Email Service (src/lib/email.ts)

The email service provides three main functions for sending transactional emails:

sendVerificationEmail()

Sends an email with a link for users to verify their email address.

await sendVerificationEmail(
  apiToken,
  'no-reply@example.com',
  'user@example.com',
  'John Doe',
  'https://app.example.com/email-verified/abc123'
);

sendPasswordResetEmail()

Sends an email with a link for users to reset their password.

await sendPasswordResetEmail(
  apiToken,
  'no-reply@example.com',
  'user@example.com',
  'John Doe',
  'https://app.example.com/reset-password/token123'
);

sendMagicLinkEmail()

Sends a magic link that allows users to sign in without a password.

await sendMagicLinkEmail(
  apiToken,
  'no-reply@example.com',
  'user@example.com',
  'John Doe',
  'https://app.example.com/verify-magic-link/token123'
);

Webhook Handler (src/pages/api/public/webhooks/mauth-webhook.ts)

The webhook handler receives events from Mindful Auth and automatically sends the appropriate emails.

Supported Events

1. verify_email

• Triggered when a user signs up or requests email verification
• Sends a verification email with confirmation link

2. password_reset

• Triggered when a user requests a password reset
• Sends an email with a password reset link

3. magic_login

• Triggered when a user requests a magic link login
• Sends an email with a one-time sign-in link

Webhook Payload Structure

All webhook payloads follow this base structure:

{
  "event_type": "verify_email|password_reset|magic_login",
  "recordid": "unique_record_id",
  "email": "user@example.com",
  "name": "User Name",
  "verificationLink": "https://...",  // for verify_email
  "resetLink": "https://...",         // for password_reset
  "magicLoginLink": "https://..."     // for magic_login
}

Testing

Test the Webhook Endpoint

You can test if the webhook endpoint is accessible by visiting:

https://app.yourdomain.com/api/public/webhooks/mauth-webhook

A successful response will return:

{
  "status": "Webhook endpoint is active",
  "method": "POST",
  "note": "This endpoint accepts POST requests from Mindful Auth"
}

Send a Test Email

To manually test the email service, create a test script:

import { sendVerificationEmail } from '@/lib/email';

const apiToken = process.env.POSTMARK_API_TOKEN;
const emailFrom = process.env.EMAIL_FROM;

await sendVerificationEmail(
  apiToken,
  emailFrom,
  'test@example.com',
  'Test User',
  'https://app.example.com/verify/test123'
);

Postmark Test Mode

For development, you can use Postmark’s test API tokens to send emails without actually delivering them. Check Postmark’s documentation for test token setup.

Environment Variables Reference

Variable	Required	Description
POSTMARK_API_TOKEN	Yes	Your Postmark server API token
EMAIL_FROM	Yes	Verified sender address (format: Name <email@domain.com>)

Troubleshooting

Emails Not Being Sent

1. Check environment variables – Verify POSTMARK_API_TOKEN and EMAIL_FROM are set correctly
2. Verify sender address – Ensure EMAIL_FROM is verified in Postmark
3. Check logs – Review application logs for error messages
4. Test Postmark connectivity – Make a direct API call to verify the token works

Webhook Not Being Called

1. Verify webhook URL – Test the endpoint is publicly accessible
2. Check webhook configuration – Confirm the URL is correct in Mindful Auth
3. Enable events – Ensure required events are selected in webhook settings
4. Review logs – Check application logs for incoming webhook requests

Email Delivery Issues

1. Check spam folder – Verify emails aren’t being filtered
2. Review Postmark activity – Check Postmark dashboard for delivery status
3. Validate email addresses – Ensure recipient addresses are correct
4. HTML/Text content – Review email templates in src/lib/email.ts

Customization

Modify Email Templates

Edit the email content in src/lib/email.ts. Each function has HtmlBody and TextBody properties:

export async function sendVerificationEmail(...) {
  await sendEmail(apiToken, {
    // ... other properties
    HtmlBody: `
      <h2>Custom Subject</h2>
      <p>Your custom message here</p>
    `,
    TextBody: `Custom text version`,
  });
}