AWS SES Setup

TrackPost uses your own AWS SES account for sending emails. This gives you complete control over your sending reputation and costs.

Why BYO SES?

BYO SES (Bring Your Own Simple Email Service) means you connect your AWS SES account to TrackPost. Benefits include:

• Full Reputation Control - Your sending reputation is independent of other users
• Cost Savings - Pay AWS’s low email rates (1000 emails = $0.10)
• AWS Tools Access - Use AWS’s deliverability dashboard and reputation monitoring
• No Shared IPs - Your own dedicated sending infrastructure
• Regional Control - Choose AWS regions close to your users

Setup Overview

1. AWS Account - Create or use existing AWS account
2. Credentials - Generate IAM user with SES permissions
3. Domain Verification - Prove you own your sending domain
4. DNS Configuration - Add SPF, DKIM, and DMARC records
5. Testing - Send test emails to verify setup

Prerequisites

Before you begin:

• AWS account (free tier works fine)
• A domain you own (e.g., yourcompany.com)
• DNS management access (via your registrar or DNS provider)
• TrackPost account

Quick Setup (CLI)

The fastest way to configure AWS:

# Install the CLI
npm install -g @trackpost/cli

# Run interactive setup
trackpost aws setup

The CLI will:

1. Ask for your AWS credentials
2. Select your preferred region
3. Test the connection
4. Configure SNS for webhooks

Manual Setup

Step 1: Create AWS IAM User

1. Log in to AWS Console
2. Navigate to IAM → Users → Create user
3. Enter a username (e.g., trackpost-ses)
4. Select Attach policies directly
5. Create an inline policy with the following permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ses:SendEmail",
        "ses:SendRawEmail",
        "ses:GetSendQuota",
        "ses:GetIdentityVerificationAttributes",
        "ses:GetIdentityNotificationAttributes",
        "ses:VerifyEmailIdentity",
        "ses:VerifyDomainIdentity",
        "ses:SetIdentityNotificationTopic",
        "ses:SetIdentityFeedbackForwardingEnabled"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "sns:CreateTopic",
        "sns:Subscribe",
        "sns:Publish",
        "sns:ConfirmSubscription"
      ],
      "Resource": "*"
    }
  ]
}

6. Create access keys for this user
7. Save the Access Key ID and Secret Access Key securely

Step 2: Add Credentials to TrackPost

1. Log in to your TrackPost Dashboard
2. Go to Settings → AWS Configuration
3. Enter your credentials:
   • Access Key ID: From step above
   • Secret Access Key: From step above
   • AWS Region: Choose your preferred SES region

Available Regions

Step 3: Verify Your Domain

1. In the TrackPost dashboard, go to Domains
2. Click Add Domain
3. Enter your domain (e.g., yourcompany.com)
4. Click Add Domain

TrackPost will provide DNS records to add. You’ll see:

• TXT Record for domain verification
• TXT Records for SPF
• TXT Records for DKIM

Step 4: Configure DNS Records

Add these records to your domain’s DNS:

Example DNS Configuration

Step 5: Wait for Verification

DNS changes can take 5 minutes to 48 hours to propagate globally. Check status in:

• TrackPost Dashboard - Shows verification status
• DNS Propagation Checkers - whatsmydns.net

Once verified, the status changes from “Pending” to “Verified”.

Detailed Guides

For step-by-step walkthroughs of specific setup tasks:

Domain Setup

Complete guide to domain verification including:

• Adding domains to TrackPost
• DNS configuration by provider (Cloudflare, GoDaddy, Route53, etc.)
• Troubleshooting verification issues

Authentication

AWS credential management:

• IAM user creation
• Permission policies
• Security best practices
• Rotating credentials

Deliverability

Optimize your email delivery:

• SPF, DKIM, and DMARC explained
• DNS record configuration
• Testing authentication
• Reputation monitoring

AWS SES Limits

AWS imposes default limits that increase over time:

Sending Limits

Requesting Limit Increases

1. Go to AWS SES Console
2. Click Account dashboard
3. Click Request increase for the desired limit
4. Fill out the form with:
   • Use case description
   • Website URL
   • Opt-in process explanation
   • Bounce/complaint handling

Sandbox vs. Production

Sandbox Mode (Default)

• Can only send to verified email addresses
• Cannot send to arbitrary recipients
• Used for testing and development

Production Access

• Can send to any email address
• Required for live applications
• Requires manual approval from AWS

To request production access:

1. Go to AWS SES Console → Account dashboard
2. Click Request production access
3. Complete the form explaining your use case
4. Wait for AWS approval (usually 24 hours)

Testing Your Setup

Test Email via Dashboard

1. Go to Emails in the dashboard
2. Click Send Test Email
3. Fill in the form and click Send

Test via CLI

trackpost send \
  --to [email protected] \
  --from [email protected] \
  --subject "Test from TrackPost" \
  --html "<h1>It works!</h1>"

Test via API

curl -X POST https://api.trackpost.de/v1/emails \
  -H "Authorization: Bearer tp_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "[email protected]",
    "from": "[email protected]",
    "subject": "Test",
    "html": "<h1>It works!</h1>"
  }'

Verify Authentication Headers

After sending, check your email headers:

Authentication-Results: mx.google.com;
       spf=pass (google.com: domain of ... designates ...);
       dkim=pass [email protected];
       dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=yourcompany.com

Look for spf=pass, dkim=pass, and dmarc=pass.

Common Issues

“AWS credentials invalid” Error

• Double-check Access Key ID and Secret Access Key
• Verify the IAM user has SES and SNS permissions
• Check that the AWS region matches your SES configuration

Domain verification stuck on “Pending”

• DNS propagation can take up to 48 hours
• Use whatsmydns.net to check globally
• Verify records are added to the correct domain
• Ensure no typos in record names or values

Emails going to spam

• Ensure SPF, DKIM, and DMARC are all configured correctly
• Check email content for spam triggers
• Warm up your domain reputation gradually
• Monitor AWS SES reputation dashboard

“Sandbox access” Error

• New AWS accounts start in sandbox mode
• Request production access from AWS SES console
• While in sandbox, verify recipient email addresses first

Best Practices

1. Use Dedicated IAM User - Don’t use root account credentials
2. Rotate Keys Regularly - Change API keys every 90 days
3. Monitor Reputation - Check AWS SES dashboard weekly
4. Handle Bounces - Process bounce notifications immediately
5. Warm Up Gradually - Start with low volume, increase slowly
6. Keep DNS Updated - Monitor and update DNS records as needed

Next Steps

• Domain Setup Guide - Step-by-step domain verification
• Authentication Guide - Credential management
• Deliverability Guide - SPF, DKIM, DMARC setup
• Templates - Create email templates
• Troubleshooting - Common issues and solutions