AWS Email Setup Guide

PhoenixKit provides comprehensive AWS integration for email tracking and event handling. This guide covers the complete setup process for AWS SES, SNS, and SQS services.

Overview

The AWS email infrastructure enables you to:

Track email delivery, opens, clicks, and other events
Process email events in real-time using SQS polling
Store email data with configurable retention policies
Integrate with AWS services for advanced analytics

Quick Start

1. Create AWS Account (if you don't have one)

Go to AWS Console
Sign up for a new account or sign in to existing account
Complete account verification process

2. Create IAM User for PhoenixKit

Navigate to IAM Console
Go to "Users" → "Add user"
Enter user name (e.g., phoenixkit-user)
Select "Programmatic access" type

Attach policies:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "sqs:*",
        "sns:*",
        "ses:*",
        "sts:GetCallerIdentity",
        "ec2:DescribeRegions"
      ],
      "Resource": "*"
    }
  ]
}

3. Get AWS Credentials

After creating the user, download or copy:
- Access Key ID (e.g., AKIAIOSFODNN7EXAMPLE)
- Secret Access Key (e.g., wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY)
Store these credentials securely - you won't be able to see the secret key again

4. Configure in PhoenixKit Admin UI

Navigate to {prefix}/admin/settings/emails
Scroll to "AWS Configuration" section
Enter your AWS credentials:
- Access Key ID: Your 20-character access key
- Secret Access Key: Your secret access key
- Region: Select your preferred AWS region
Click "Verify Credentials" to test connectivity
Click "Save AWS Settings" to persist the configuration

Understanding Credentials Verification
When you click "Verify Credentials", PhoenixKit calls AWS STS GetCallerIdentity to verify:
✅ Credentials are valid (not expired or revoked)
✅ AWS account ID is accessible
✅ Credentials can authenticate with AWS
Permissions are NOT checked during verification. Actual permissions (CreateQueue, CreateTopic, etc.) are verified during "Setup AWS Infrastructure" (next step). If permissions are missing, you'll receive a specific error message indicating which permission is required.

5. Setup AWS Infrastructure

After saving credentials, click "Setup AWS Infrastructure"
PhoenixKit will automatically create:
- SNS Topic for email events
- SQS Main Queue for message processing
- SQS Dead Letter Queue for failed messages
- SES Configuration Set for tracking
Wait for completion (typically 30-60 seconds)

6. Verify Email/Domain in SES

Navigate to SES Console
Go to "Verified identities" → "Email addresses" or "Domains"
Verify the email address you'll use as sender
If using custom domain, verify the domain

7. Enable Email System

Return to PhoenixKit settings
Toggle "Enable Emails" to ON
Configure other settings as needed

8. Understanding AWS Permissions

PhoenixKit requires the following AWS permissions for full email functionality:

Required Permissions (for Setup AWS Infrastructure)

SQS (Simple Queue Service):
- sqs:CreateQueue, sqs:GetQueueAttributes, sqs:SetQueueAttributes
- sqs:ReceiveMessage, sqs:DeleteMessage (for SQS worker)
SNS (Simple Notification Service):
- sns:CreateTopic, sns:Subscribe, sns:SetTopicAttributes
SES (Simple Email Service):
- ses:CreateConfigurationSet, ses:CreateConfigurationSetEventDestination
- ses:SendEmail, ses:SendRawEmail (for sending emails)
STS (Security Token Service):
- sts:GetCallerIdentity (for credentials verification)

Optional Permissions

EC2 ec2:DescribeRegions:
- Used for automatic region discovery in the admin UI
- If not granted, manual region selection from common regions list is available
- NOT required for email functionality

If any required permission is missing, "Setup AWS Infrastructure" will fail with a specific error message indicating which permission is needed. Simply add the permission to your IAM policy and try again.

Detailed Instructions

IAM Configuration

Minimal Required Permissions

For production, use least-privilege permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ses:SendEmail",
        "ses:SendRawEmail",
        "ses:CreateConfigurationSet",
        "ses:CreateConfigurationSetEventDestination",
        "ses:UpdateConfigurationSetEventDestination",
        "ses:DescribeConfigurationSets",
        "ses:GetSendQuota"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "sqs:CreateQueue",
        "sqs:DeleteQueue",
        "sqs:GetQueueAttributes",
        "sqs:SetQueueAttributes",
        "sqs:ReceiveMessage",
        "sqs:DeleteMessage",
        "sqs:ListQueues"
      ],
      "Resource": "arn:aws:sqs:*:*:phoenixkit-*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "sns:CreateTopic",
        "sns:DeleteTopic",
        "sns:Subscribe",
        "sns:ListSubscriptions",
        "sns:GetTopicAttributes",
        "sns:SetTopicAttributes"
      ],
      "Resource": "arn:aws:sns:*:*:phoenixkit-*"
    },
    {
      "Effect": "Allow",
      "Action": "sts:GetCallerIdentity",
      "Resource": "*"
    },
    {
      "Sid": "OptionalEC2ForAutoRegionDiscovery",
      "Effect": "Allow",
      "Action": "ec2:DescribeRegions",
      "Resource": "*"
    }
  ]
}

Note: The ec2:DescribeRegions permission allows PhoenixKit to automatically fetch the list of available AWS regions when configuring SES integration. This is optional - if not granted, PhoenixKit will fall back to a predefined list of common regions.

Environment Variables (Alternative)

You can also configure credentials via environment variables:

# ~/.bashrc or ~/.zshrc
export AWS_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE"
export AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
export AWS_DEFAULT_REGION="eu-north-1"

Region Selection

Choose a region based on:

Data residency requirements (GDPR, CCPA, etc.)
Latency for your users
Service availability (some services vary by region)
Cost considerations (different pricing per region)

Common regions:

us-east-1 (N. Virginia) - highest service availability
us-west-2 (Oregon) - good for APAC users
eu-west-1 (Ireland) - good for European users
ap-southeast-1 (Singapore) - good for Asian users

SES Configuration

Email Verification

Before sending emails, you need to verify:

Email addresses: Send verification email to the address
Domains: Verify DNS records (MX, CNAME, etc.)

Production Considerations

Request Production Access: SES starts in "sandbox mode"
- Request production access via AWS Support
- Alternatively, use verified email addresses in sandbox
Vetting Process: Amazon may review your use case
- Provide details about your email volume and content
- Explain how you handle unsubscribe requests

Monitoring and Troubleshooting

Common Issues

1. "Invalid credentials" error

Verify Access Key ID and Secret Access Key are correct
Ensure IAM user has the correct permissions
Check if the account is in good standing

2. "Access denied" error

Verify IAM permissions for SQS, SNS, and SES
Check resource ARN patterns in policies
Ensure the region is correct

3. SQS polling not working

Ensure SQS polling is enabled in settings
Check SQS queue URL is correct
Verify SNS subscription is active

Logs and Monitoring

AWS CloudTrail: Track API calls
AWS CloudWatch: Monitor metrics and logs
PhoenixKit Logs: Check for email processing errors

Testing Your Setup

Send Test Email:

Swoosh.Email.new()
|> Swoosh.Email.to("test@example.com")
|> Swoosh.Email.from({sender_name, sender_email})
|> Swoosh.Email.subject("Test from PhoenixKit")
|> Swoosh.Email.html_body("<h1>Test Email</h1>")
|> PhoenixKit.Mailer.deliver_email()

Check Event Tracking:
- Look for email events in PhoenixKit admin UI
- Monitor SQS queue for incoming messages
- Check SES event notifications

Advanced Configuration

Custom SQS Polling Settings

Configure these settings in PhoenixKit admin UI:

Polling Interval: How often to check SQS (1-60 seconds)
Max Messages: Messages to process per poll (1-10)
Visibility Timeout: How long messages are hidden (30-43200 seconds)

S3 Archival for Long-term Storage

Enable "S3 Archival" in settings
Configure S3 bucket:
```
aws s3 mb s3://your-phoenixkit-emails
```
Set retention policies for automatic cleanup

Data Retention and Compliance

Retention Period: Configure how long to keep email data
Compression: Enable body compression after X days
GDPR Compliance: Implement data deletion policies
Access Controls: Use IAM roles for access control

Security Best Practices

Production Deployment

Use IAM Roles: Instead of access keys, use IAM roles with EC2 instances
Rotate Credentials: Regularly rotate access keys
Enable CloudTrail: Monitor all API calls
Use KMS: Encrypt sensitive data at rest

Network Security

VPC Endpoints: Use interface VPC endpoints for private connectivity
Security Groups: Restrict access to SQS/SNS endpoints
Network ACLs: Control traffic flow at subnet level

Cost Optimization

Cost Control Measures

SQS: Use long polling to reduce costs
SNS: Use filtered subscriptions to reduce processing
SES: Monitor send quotas and bounce rates
Storage: Use S3 lifecycle policies for automated cleanup

Estimated Costs

Example costs for 10,000 emails/month:

SES: Free (within limits)
SQS: ~$1/month
SNS: ~$1/month
S3: ~$0.50/month (for archival)

Support and Resources

AWS Documentation

PhoenixKit Resources

Email Configuration Guide: /docs/EMAIL_CONFIGURATION.md
AWS Solutions Guide: /docs/AWS_EMAILS_SOLUTIONS.md
Troubleshooting: /docs/AWS_SES_SETUP.md

Getting Help

AWS Support: AWS Support Center
PhoenixKit Issues: GitHub Issues
Community: PhoenixKit Discord/Community forums

Note: Always test your email setup in a non-production environment before deploying to production. Monitor costs and adjust settings as needed.

← Previous Page OAuth & Magic Link Setup

Next Page → Making Pages Live: Real-time Updates & Collaborative Editing