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

Postmark Setup Documentation - Build v1

Setup Date: 2025-08-02
Purpose: Complete Postmark configuration for NudgeCampaign MVP
Service: Postmark Email API (postmarkapp.com)
Framework Learning: This should be Phase 0 - Prerequisites Setup in future builds

Postmark Setup Objectives

Based on Phase 9 tech stack analysis, we need Postmark configured for:

  • Transactional email delivery (welcome emails, notifications)
  • High deliverability rates (99%+ inbox placement)
  • Email analytics and tracking
  • Production-ready email infrastructure

Step-by-Step Postmark Setup Guide

Step 1: Create Postmark Account

  1. Visit Postmark: Go to https://postmarkapp.com
  2. Sign Up: Click "Start sending for free" or "Sign up"
  3. Account Details:
    • Business email address (recommend: your@yourdomain.com)
    • Company name: "NudgeCampaign" or your company name
    • Choose plan: Start with free tier (100 emails/month)

Step 2: Create Server for NudgeCampaign

  1. Access Dashboard: After signup, you'll see the dashboard
  2. Create Server:
    • Click "Create a Server"
    • Server Name: "NudgeCampaign MVP"
    • Description: "Email delivery for NudgeCampaign email marketing platform"
    • Color: Choose any color for identification

Step 3: Configure Server Settings

  1. Server Settings: Click on your server name
  2. Configure Domain:
    • Add your domain (if you have one) OR
    • Use Postmark's shared domain for testing
  3. Sender Signature:
    • From Email: Use your verified email address
    • From Name: "Your Name from NudgeCampaign"
    • Reply-To: Same as From Email (initially)

Step 4: Get API Credentials

  1. API Tokens: In server settings, find "API Tokens" section
  2. Server API Token: Copy this - we'll need it for environment variables
  3. Account API Token: Also copy this for account-level operations

Step 5: Verify Email Address

  1. Add Sender Signature: Go to "Sender Signatures" in your server
  2. Add Email: Add your from email address
  3. Verify: Check your email and click verification link
  4. Confirm: Email should show "Confirmed" status

Configuration Values Needed

Please provide these values once you complete the setup:

# Copy these values from your Postmark dashboard
POSTMARK_SERVER_API_TOKEN=your-server-api-token-here
POSTMARK_ACCOUNT_API_TOKEN=your-account-api-token-here
POSTMARK_FROM_EMAIL=your-verified-email@yourdomain.com
POSTMARK_FROM_NAME="Your Name from NudgeCampaign"

What I'll Do With These Credentials

Once you provide the values, I will:

  1. Update Environment Variables: Add to .env file
  2. Configure Docker Services: Update email service configuration
  3. Create Email Service: Build Postmark integration service
  4. Test Email Delivery: Send test emails through Postmark
  5. Implement Templates: Create email templates for welcome series

Setup Progress Tracking

  • Postmark account created
  • Server "NudgeCampaign MVP" created
  • Sender signature added and verified
  • API tokens copied
  • Credentials provided to development environment
  • Domain configured (optional for MVP)
  • Test email sent successfully MessageID: 6c7252bc-d290-460d-99f4-d486728eb148

Received Credentials

POSTMARK_SERVER_API_TOKEN=58c0f839-45de-443e-b0ac-4a8dfc18cfec
POSTMARK_FROM_EMAIL=lindsay@knowcode.tech
POSTMARK_FROM_NAME="Lindsay from NudgeCampaign"

Status: Ready for integration into Docker environment and application

Important Security Notes

  • Never commit API tokens to git (they're in .env which is gitignored)
  • Use server tokens for sending emails (not account tokens)
  • Keep tokens secure - they provide full access to send emails
  • Rotate tokens if compromised

Next Steps After Setup

Once you provide the credentials:

  1. I'll configure the Docker environment with Postmark
  2. Create email service integration
  3. Test email delivery
  4. Continue with application development

Please proceed with Postmark setup and provide the API credentials when ready!