fediversion/docs/AWS_SES_BROWSER_AGENT.md

AWS SES Setup - Browser Agent Handoff

Objective

Configure AWS SES for the Elmeg platform to enable transactional emails (verification, password reset).

Domain: elmeg.xyz
Production URL: https://elmeg.xyz
Sender Email: noreply@elmeg.xyz

---

Step 1: Verify Domain in SES

1. Go to: https://console.aws.amazon.com/ses
2. Select region US East (N. Virginia) us-east-1 from top-right dropdown
3. Left sidebar → Verified identities → Click Create identity
4. Select Domain
5. Enter: elmeg.xyz
6. Keep "Use a custom MAIL FROM domain" unchecked
7. Click Create identity
8. Copy the DNS records shown:
   • 1 TXT record (for verification)
   • 3 CNAME records (for DKIM)
9. Save these records - they need to be added to elmeg.xyz DNS

---

Step 2: Add DNS Records

Go to the DNS provider for elmeg.xyz and add:

Type	Name	Value
TXT	_amazonses.elmeg.xyz	(from SES console)
CNAME	xxxx._domainkey.elmeg.xyz	(DKIM 1 from SES)
CNAME	xxxx._domainkey.elmeg.xyz	(DKIM 2 from SES)
CNAME	xxxx._domainkey.elmeg.xyz	(DKIM 3 from SES)

Wait for verification (can take 5-72 hours).

---

Step 3: Request Production Access

By default SES is in sandbox mode (can only send to verified emails).

1. In SES console → Account dashboard (left sidebar)
2. Find "Your account is in the Amazon SES sandbox" banner
3. Click Request production access
4. Fill form:
   • Mail type: Transactional
   • Website URL: https://elmeg.xyz
   • Use case description:

     "Transactional emails for user account lifecycle on a live music rating platform. Emails include: account verification, password reset, and account notifications. Expected volume: under 1000 emails/month initially."

5. Submit and wait for approval (~24 hours)

---

Step 4: Create IAM User for SES

1. Go to: https://console.aws.amazon.com/iam

2. Left sidebar → Users → Create user

3. User name: elmeg-ses-sender

4. Click Next

5. Select Attach policies directly

6. Click Create policy (opens new tab):

   • Select JSON tab
   • Paste:

   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Effect": "Allow",
               "Action": ["ses:SendEmail", "ses:SendRawEmail"],
               "Resource": "*"
           }
       ]
   }
   

   • Click Next
   • Policy name: SES-SendEmail-Only
   • Click Create policy

7. Back on user creation, refresh policies, search SES-SendEmail-Only, select it

8. Click Next → Create user

---

Step 5: Create Access Key

1. Click on user elmeg-ses-sender
2. Tab: Security credentials
3. Scroll to Access keys → Create access key
4. Select: Application running outside AWS
5. Click Next → Create access key
6. SAVE BOTH VALUES:
   • Access key ID: AKIA...
   • Secret access key: ...
7. Click Done

---

Step 6: Return Values

Return these values to the user:

AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=...
AWS_SES_REGION=us-east-1
EMAIL_FROM=noreply@elmeg.xyz
FRONTEND_URL=https://elmeg.xyz

Also return the DNS records that need to be added for domain verification.

---

Notes

• Never share or commit AWS keys
• SES sandbox removal takes ~24hrs
• Domain verification DNS propagation can take up to 72hrs
• DKIM is required or emails will be marked as spam