# 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.