Last updated: Aug 4, 2025, 11:26 AM UTC

Postmark Email Integration

Overview

NudgeCampaign v4 uses Postmark as its email service provider for sending transactional emails and marketing campaigns. The integration provides reliable email delivery with detailed tracking and analytics.

Configuration

Environment Variables

Configure these variables in your .env file:

POSTMARK_SERVER_TOKEN=your-postmark-server-token
POSTMARK_FROM_EMAIL=hello@nudgecampaign.com
POSTMARK_MESSAGE_STREAM=outbound

Obtaining Postmark Credentials

  1. Sign up for a Postmark account at https://postmarkapp.com
  2. Create a new Server
  3. Navigate to API Tokens and copy your Server API Token
  4. Configure your sender signatures or domain verification
  5. Update the FROM_EMAIL to match your verified sender

Features

1. Email Settings Page

  • Location: /dashboard/settings/email
  • Features:
    • Real-time connection status
    • Email statistics (sent, bounced, opened, clicked)
    • Test email functionality
    • Configuration display

2. Campaign Integration

  • Location: /dashboard/campaigns
  • Features:
    • Test email for each campaign
    • Postmark status indicator
    • Send campaign functionality
    • Real-time feedback

3. API Endpoints

Status Check

  • Endpoint: GET /api/settings/email/status
  • Purpose: Check Postmark connection and fetch statistics
  • Response:
{
  "connected": true,
  "serverName": "Your Server",
  "fromEmail": "hello@nudgecampaign.com",
  "stats": {
    "sent": 150,
    "bounced": 2,
    "opened": 45,
    "clicked": 12
  }
}

Test Email

  • Endpoint: POST /api/settings/email/test
  • Purpose: Send a test email to verify configuration
  • Request Body:
{
  "email": "test@example.com"
}

Campaign Test

  • Endpoint: POST /api/campaigns/{id}/test
  • Purpose: Send test version of a campaign
  • Request Body:
{
  "testEmail": "test@example.com"
}

Campaign Send

  • Endpoint: POST /api/campaigns/{id}/send
  • Purpose: Send campaign to all contacts
  • Response:
{
  "success": true,
  "recipientCount": 250,
  "messageIds": ["..."]
}

UI Components

Email Settings Page

The Email Settings page provides a comprehensive view of the Postmark integration:

  • Connection status with visual indicators
  • Configuration details (masked API token)
  • 30-day email statistics
  • Test email functionality with immediate feedback

Campaign Management

The campaigns page includes:

  • Global test email input field
  • Per-campaign test buttons
  • Postmark integration status indicator
  • Real-time test results

Implementation Details

Authentication

The integration uses Postmark's Server API Token for authentication. This token is passed in the X-Postmark-Server-Token header for all API requests.

Error Handling

  • Connection failures display clear error messages
  • Failed sends provide detailed error information
  • Fallback states for unconfigured environments

Message Streams

Postmark uses message streams to categorize emails:

  • outbound: Transactional emails (default)
  • broadcast: Marketing/bulk emails

Testing

Manual Testing

  1. Navigate to Email Settings page
  2. Verify connection status shows "Connected"
  3. Click "Send Test Email" and enter your email
  4. Check inbox for test message
  5. Navigate to Campaigns page
  6. Enter test email in the test bar
  7. Click "Test" on any campaign
  8. Verify test email received

Automated Testing

# Test connection
curl http://localhost:3002/api/settings/email/status

# Send test email
curl -X POST http://localhost:3002/api/settings/email/test \
  -H "Content-Type: application/json" \
  -d '{"email":"your@email.com"}'

Troubleshooting

Common Issues

  1. "Postmark is not configured"

    • Ensure POSTMARK_SERVER_TOKEN is set in .env
    • Restart the application after setting environment variables

  2. "Invalid Postmark API token"

    • Verify token is correct
    • Check token has necessary permissions
    • Ensure you're using Server API Token, not Account API Token

  3. "Failed to send test email"

    • Verify sender signature or domain is verified in Postmark
    • Check FROM_EMAIL matches verified sender
    • Review Postmark activity feed for detailed errors

Debug Mode

Enable debug logging by setting:

DEBUG=postmark:*

Security Considerations

  1. API Token Security

    • Never commit API tokens to version control
    • Use environment variables for all credentials
    • Mask tokens in UI displays

  2. Rate Limiting

    • Postmark has rate limits (varies by plan)
    • Implement retry logic for transient failures
    • Monitor usage in Postmark dashboard

  3. Email Validation

    • Validate email addresses before sending
    • Handle bounces and complaints appropriately
    • Maintain suppression lists

Future Enhancements

  1. Webhook Integration

    • Handle bounce/complaint webhooks
    • Track email opens and clicks
    • Update contact engagement scores

  2. Template Management

    • Create and manage email templates in Postmark
    • Use template variables for personalization
    • A/B testing support

  3. Advanced Analytics

    • Detailed campaign performance reports
    • Engagement tracking per contact
    • Conversion attribution

Resources