157 lines
4.1 KiB
Markdown
157 lines
4.1 KiB
Markdown
# Amazon SES Configuration
|
|
|
|
This document describes how to configure Amazon SES for outbound email in Towerops.
|
|
|
|
## Required Environment Variables
|
|
|
|
The following environment variables must be set in production:
|
|
|
|
```bash
|
|
# AWS Credentials (required)
|
|
AWS_ACCESS_KEY_ID=your-access-key-id
|
|
AWS_SECRET_ACCESS_KEY=your-secret-access-key
|
|
|
|
# AWS Region (optional, defaults to us-east-1)
|
|
AWS_REGION=us-east-1
|
|
```
|
|
|
|
## AWS IAM Permissions
|
|
|
|
The IAM user or role needs the following SES permissions:
|
|
|
|
```json
|
|
{
|
|
"Version": "2012-10-17",
|
|
"Statement": [
|
|
{
|
|
"Effect": "Allow",
|
|
"Action": [
|
|
"ses:SendEmail",
|
|
"ses:SendRawEmail"
|
|
],
|
|
"Resource": "*"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## SES Setup Steps
|
|
|
|
1. **Verify Your Domain in SES**
|
|
- Go to AWS Console > SES > Verified identities
|
|
- Click "Create identity" > Domain
|
|
- Add your domain (e.g., `towerops.net`)
|
|
- Add the required DNS records (DKIM, MAIL FROM)
|
|
- Wait for verification (can take up to 72 hours)
|
|
|
|
2. **Verify the From Email Address**
|
|
- In SES Console, verify `hi@towerops.net` (or your chosen from address)
|
|
- Check the verification email and click the confirmation link
|
|
|
|
3. **Move Out of SES Sandbox (Production)**
|
|
- By default, SES is in sandbox mode (can only send to verified addresses)
|
|
- Request production access: AWS Console > SES > Account dashboard > Request production access
|
|
- Fill out the form with your use case
|
|
- Approval typically takes 24 hours
|
|
|
|
4. **Create IAM User for Towerops**
|
|
```bash
|
|
aws iam create-user --user-name towerops-ses
|
|
aws iam attach-user-policy --user-name towerops-ses --policy-arn arn:aws:iam::aws:policy/AmazonSESFullAccess
|
|
aws iam create-access-key --user-name towerops-ses
|
|
```
|
|
|
|
Save the `AccessKeyId` and `SecretAccessKey` from the output.
|
|
|
|
## Configuration in Towerops
|
|
|
|
The from email address is configured via application config (not environment variable):
|
|
|
|
**In `config/runtime.exs` or `config/prod.exs`:**
|
|
```elixir
|
|
config :towerops, :mailer_from, {"Towerops", "hi@towerops.net"}
|
|
```
|
|
|
|
Or set it dynamically via environment variable by adding to `config/runtime.exs`:
|
|
```elixir
|
|
config :towerops, :mailer_from,
|
|
{System.get_env("MAILER_FROM_NAME") || "Towerops",
|
|
System.get_env("MAILER_FROM_EMAIL") || "hi@towerops.net"}
|
|
```
|
|
|
|
## Testing Email Configuration
|
|
|
|
### In Development (using IEx)
|
|
|
|
```elixir
|
|
# Start the application
|
|
iex -S mix
|
|
|
|
# Test sending an email
|
|
alias Towerops.Accounts.UserNotifier
|
|
user = %{email: "test@example.com"}
|
|
UserNotifier.deliver_update_email_instructions(user, "http://example.com/test")
|
|
```
|
|
|
|
### In Production
|
|
|
|
Check the logs for successful delivery:
|
|
```
|
|
[info] User email sent to test@example.com: Update email instructions
|
|
```
|
|
|
|
Or check for errors:
|
|
```
|
|
[error] Failed to send user email to test@example.com: <reason>
|
|
```
|
|
|
|
## Monitoring
|
|
|
|
- Monitor bounce rates in AWS SES Console
|
|
- Set up SNS notifications for bounces and complaints
|
|
- Check CloudWatch metrics for email sending
|
|
|
|
## Troubleshooting
|
|
|
|
### "Email address not verified" error
|
|
- Ensure the from address is verified in SES
|
|
- If in sandbox mode, ensure recipient is also verified
|
|
|
|
### "Access denied" error
|
|
- Check IAM permissions
|
|
- Verify AWS credentials are correct
|
|
- Ensure credentials have SES permissions
|
|
|
|
### "MessageRejected" error
|
|
- Check SES sending limits
|
|
- Verify domain DKIM records are set up
|
|
- Check if account is in sandbox mode
|
|
|
|
### "Throttling" error
|
|
- SES has sending limits (default: 1 email/second)
|
|
- Request limit increase in AWS Console
|
|
|
|
## Current Configuration
|
|
|
|
**Adapter**: `Swoosh.Adapters.ExAwsSES`
|
|
**Default Region**: `us-east-1`
|
|
**Default From**: `{"Towerops", "hi@towerops.net"}`
|
|
|
|
## Alternative: SMTP Configuration
|
|
|
|
If you prefer SMTP over API (not recommended), you can use:
|
|
|
|
```elixir
|
|
config :towerops, Towerops.Mailer,
|
|
adapter: Swoosh.Adapters.SMTP,
|
|
relay: "email-smtp.us-east-1.amazonaws.com",
|
|
port: 587,
|
|
username: System.get_env("SES_SMTP_USERNAME"),
|
|
password: System.get_env("SES_SMTP_PASSWORD"),
|
|
tls: :always,
|
|
auth: :always
|
|
```
|
|
|
|
SMTP credentials can be generated in AWS Console > SES > SMTP settings.
|
|
|
|
**Note**: API method is preferred as it's more reliable and doesn't require managing SMTP credentials.
|