aidevops 2.52.1

package/.agent/services/email/ses.md

@@ -0,0 +1,399 @@
+---
+description: Amazon SES email service integration
+mode: subagent
+tools:
+  read: true
+  write: false
+  edit: false
+  bash: true
+  glob: true
+  grep: true
+  webfetch: true
+---
+
+# Amazon SES Provider Guide
+
+<!-- AI-CONTEXT-START -->
+
+## Quick Reference
+
+- **Type**: AWS cloud email service
+- **Auth**: AWS IAM credentials (access key + secret key)
+- **Config**: `configs/ses-config.json`
+- **Commands**: `ses-helper.sh [accounts|quota|stats|monitor|verified-emails|verified-domains|verify-email|verify-domain|dkim|reputation|suppressed|send-test|audit] [account] [args]`
+- **Key metrics**: Bounce rate < 5%, Complaint rate < 0.1%
+- **Regions**: us-east-1, eu-west-1, etc.
+- **Test addresses**: success@simulator.amazonses.com, bounce@simulator.amazonses.com
+- **DKIM**: Enable for all domains
+- **IAM policy**: ses:GetSendQuota, ses:SendEmail, sesv2:ListSuppressedDestinations
+<!-- AI-CONTEXT-END -->
+
+Amazon Simple Email Service (SES) is a cloud-based email sending service designed to help digital marketers and application developers send marketing, notification, and transactional emails.
+
+## Provider Overview
+
+### **Amazon SES Characteristics:**
+
+- **Service Type**: Cloud-based email delivery service
+- **Global Regions**: Multiple AWS regions available
+- **Authentication**: AWS IAM credentials required
+- **API Support**: Comprehensive REST API and AWS CLI
+- **Pricing**: Pay-per-use with volume discounts
+- **Deliverability**: High deliverability with reputation management
+- **Compliance**: GDPR, HIPAA, and other compliance standards
+
+### **Best Use Cases:**
+
+- **Transactional emails** (order confirmations, password resets)
+- **Marketing campaigns** with high deliverability requirements
+- **Application notifications** and alerts
+- **Email reputation management** and monitoring
+- **Multi-tenant applications** with separate email domains
+- **Development and testing** with sandbox mode
+
+## 🔧 **Configuration**
+
+### **Setup Configuration:**
+
+```bash
+# Copy template
+cp configs/ses-config.json.txt configs/ses-config.json
+
+# Edit with your actual AWS credentials and settings
+```
+
+### **Multi-Account Configuration:**
+
+```json
+{
+  "accounts": {
+    "production": {
+      "aws_access_key_id": "YOUR_PRODUCTION_AWS_ACCESS_KEY_ID_HERE",
+      "aws_secret_access_key": "YOUR_PRODUCTION_AWS_SECRET_ACCESS_KEY_HERE",
+      "region": "us-east-1",
+      "description": "Production SES account",
+      "verified_domains": ["yourdomain.com"],
+      "verified_emails": ["noreply@yourdomain.com"]
+    },
+    "staging": {
+      "aws_access_key_id": "YOUR_STAGING_AWS_ACCESS_KEY_ID_HERE",
+      "aws_secret_access_key": "YOUR_STAGING_AWS_SECRET_ACCESS_KEY_HERE",
+      "region": "us-east-1",
+      "description": "Staging/Development SES account",
+      "verified_domains": ["staging.yourdomain.com"],
+      "verified_emails": ["test@yourdomain.com"]
+    }
+  }
+}
+```
+
+### **AWS CLI Setup:**
+
+```bash
+# Install AWS CLI
+brew install awscli  # macOS
+sudo apt-get install awscli  # Linux
+
+# Verify installation
+aws --version
+
+# The helper script will use credentials from the config file
+# No need to run 'aws configure' - credentials are managed per account
+```
+
+## 🚀 **Usage Examples**
+
+### **Basic Commands:**
+
+```bash
+# List all SES accounts
+./.agent/scripts/ses-helper.sh accounts
+
+# Get sending quota
+./.agent/scripts/ses-helper.sh quota production
+
+# Get sending statistics
+./.agent/scripts/ses-helper.sh stats production
+
+# Monitor email delivery
+./.agent/scripts/ses-helper.sh monitor production
+```
+
+### **Identity Management:**
+
+```bash
+# List verified email addresses
+./.agent/scripts/ses-helper.sh verified-emails production
+
+# List verified domains
+./.agent/scripts/ses-helper.sh verified-domains production
+
+# Verify new email address
+./.agent/scripts/ses-helper.sh verify-email production newuser@yourdomain.com
+
+# Verify new domain
+./.agent/scripts/ses-helper.sh verify-domain production newdomain.com
+
+# Check identity verification status
+./.agent/scripts/ses-helper.sh verify-identity production yourdomain.com
+```
+
+### **DKIM Configuration:**
+
+```bash
+# Get DKIM attributes
+./.agent/scripts/ses-helper.sh dkim production yourdomain.com
+
+# Enable DKIM for domain
+./.agent/scripts/ses-helper.sh enable-dkim production yourdomain.com
+
+# Check DKIM status for email
+./.agent/scripts/ses-helper.sh dkim production noreply@yourdomain.com
+```
+
+### **Reputation & Deliverability:**
+
+```bash
+# Check account reputation
+./.agent/scripts/ses-helper.sh reputation production
+
+# List suppressed destinations (bounces/complaints)
+./.agent/scripts/ses-helper.sh suppressed production
+
+# Get details for suppressed email
+./.agent/scripts/ses-helper.sh suppression-details production user@example.com
+
+# Remove email from suppression list
+./.agent/scripts/ses-helper.sh remove-suppression production user@example.com
+```
+
+### **Testing & Debugging:**
+
+```bash
+# Send test email
+./.agent/scripts/ses-helper.sh send-test production noreply@yourdomain.com test@example.com "Test Subject" "Test message body"
+
+# Debug delivery issues for specific email
+./.agent/scripts/ses-helper.sh debug production problematic@example.com
+
+# Audit complete SES configuration
+./.agent/scripts/ses-helper.sh audit production
+
+# Test with SES simulator addresses
+./.agent/scripts/ses-helper.sh send-test production noreply@yourdomain.com success@simulator.amazonses.com "Success Test"
+./.agent/scripts/ses-helper.sh send-test production noreply@yourdomain.com bounce@simulator.amazonses.com "Bounce Test"
+```
+
+## 🛡️ **Security Best Practices**
+
+### **AWS Credentials Security:**
+
+- **IAM users**: Create dedicated IAM users for SES access
+- **Minimal permissions**: Grant only required SES permissions
+- **Access keys rotation**: Rotate access keys regularly
+- **Secure storage**: Store credentials in secure configuration files
+- **Environment separation**: Use different AWS accounts for prod/staging
+
+### **SES-Specific Security:**
+
+```bash
+# Recommended IAM policy for SES helper script
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": [
+        "ses:GetSendQuota",
+        "ses:GetSendStatistics",
+        "ses:ListIdentities",
+        "ses:ListVerifiedEmailAddresses",
+        "ses:GetIdentityVerificationAttributes",
+        "ses:GetIdentityDkimAttributes",
+        "ses:GetIdentityNotificationAttributes",
+        "ses:SendEmail",
+        "ses:SendRawEmail",
+        "sesv2:GetSuppressedDestination",
+        "sesv2:ListSuppressedDestinations",
+        "sesv2:DeleteSuppressedDestination"
+      ],
+      "Resource": "*"
+    }
+  ]
+}
+```
+
+### **Email Security:**
+
+- **DKIM signing**: Enable DKIM for all verified domains
+- **SPF records**: Configure proper SPF records
+- **DMARC policy**: Implement DMARC for domain protection
+- **Bounce handling**: Monitor and handle bounces properly
+- **Complaint handling**: Process complaints promptly
+
+## 🔍 **Troubleshooting**
+
+### **Common Issues:**
+
+#### **Authentication Errors:**
+
+```bash
+# Check AWS credentials
+aws sts get-caller-identity
+
+# Verify region configuration
+aws configure get region
+
+# Test SES access
+./.agent/scripts/ses-helper.sh quota production
+```
+
+#### **Sending Limits:**
+
+```bash
+# Check current quota
+./.agent/scripts/ses-helper.sh quota production
+
+# Monitor sending rate
+./.agent/scripts/ses-helper.sh stats production
+
+# Request limit increase through AWS Support if needed
+```
+
+#### **Delivery Issues:**
+
+```bash
+# Check reputation
+./.agent/scripts/ses-helper.sh reputation production
+
+# Look for suppressed destinations
+./.agent/scripts/ses-helper.sh suppressed production
+
+# Debug specific email
+./.agent/scripts/ses-helper.sh debug production problematic@example.com
+
+# Check bounce/complaint rates
+./.agent/scripts/ses-helper.sh monitor production
+```
+
+#### **Verification Problems:**
+
+```bash
+# Check verification status
+./.agent/scripts/ses-helper.sh verify-identity production yourdomain.com
+
+# Re-verify domain
+./.agent/scripts/ses-helper.sh verify-domain production yourdomain.com
+
+# Check DNS records
+dig TXT _amazonses.yourdomain.com
+```
+
+## 📊 **Monitoring & Analytics**
+
+### **Key Metrics to Monitor:**
+
+```bash
+# Daily monitoring routine
+./.agent/scripts/ses-helper.sh monitor production
+
+# Key metrics include:
+# - Send quota utilization
+# - Bounce rate (should be < 5%)
+# - Complaint rate (should be < 0.1%)
+# - Reputation score
+# - Suppressed destinations count
+```
+
+### **Automated Monitoring:**
+
+```bash
+# Create monitoring script
+#!/bin/bash
+ACCOUNT="production"
+BOUNCE_THRESHOLD=5.0
+COMPLAINT_THRESHOLD=0.1
+
+# Get current stats
+STATS=$(./.agent/scripts/ses-helper.sh stats $ACCOUNT)
+
+# Parse and alert if thresholds exceeded
+# (Add your alerting logic here)
+```
+
+### **Performance Optimization:**
+
+- **Send rate optimization**: Gradually increase sending volume
+- **List hygiene**: Remove bounced and complained addresses
+- **Content optimization**: Avoid spam trigger words
+- **Authentication setup**: Implement SPF, DKIM, and DMARC
+- **Reputation monitoring**: Monitor sender reputation regularly
+
+## 🔄 **Backup & Compliance**
+
+### **Configuration Backup:**
+
+```bash
+# Export SES configuration
+./.agent/scripts/ses-helper.sh audit production > ses-config-backup-$(date +%Y%m%d).txt
+
+# Backup verified identities
+./.agent/scripts/ses-helper.sh verified-emails production > verified-emails-backup.txt
+./.agent/scripts/ses-helper.sh verified-domains production > verified-domains-backup.txt
+```
+
+### **Compliance Considerations:**
+
+- **Data retention**: Configure appropriate data retention policies
+- **Bounce processing**: Implement proper bounce and complaint handling
+- **Unsubscribe handling**: Provide easy unsubscribe mechanisms
+- **Privacy compliance**: Follow GDPR, CAN-SPAM, and other regulations
+- **Audit trails**: Maintain logs of email sending activities
+
+## 📚 **Best Practices**
+
+### **Email Deliverability:**
+
+1. **Warm up gradually**: Start with small volumes and increase slowly
+2. **Monitor metrics**: Keep bounce rate < 5%, complaint rate < 0.1%
+3. **Clean lists regularly**: Remove invalid and unengaged addresses
+4. **Authenticate properly**: Set up SPF, DKIM, and DMARC
+5. **Content quality**: Avoid spam triggers and maintain good content
+
+### **Account Management:**
+
+- **Separate environments**: Use different accounts for prod/staging
+- **Monitor quotas**: Track sending limits and request increases proactively
+- **Handle bounces**: Process bounces and complaints promptly
+- **Regular audits**: Perform regular configuration audits
+- **Documentation**: Document all configurations and procedures
+
+### **Development Workflow:**
+
+- **Test thoroughly**: Use SES simulator addresses for testing
+- **Staging environment**: Test all changes in staging first
+- **Gradual rollout**: Deploy email changes gradually
+- **Monitor closely**: Watch metrics closely after changes
+- **Rollback plan**: Have rollback procedures ready
+
+## 🎯 **AI Assistant Integration**
+
+### **Automated Email Management:**
+
+- **Delivery monitoring**: Automated monitoring of email delivery metrics
+- **Reputation tracking**: Automated reputation and compliance monitoring
+- **Issue detection**: Automated detection of delivery issues
+- **Bounce processing**: Automated bounce and complaint handling
+- **Performance optimization**: Automated recommendations for improvement
+
+### **Troubleshooting Automation:**
+
+- **Delivery debugging**: Automated diagnosis of delivery issues
+- **Configuration validation**: Automated SES configuration checks
+- **Performance analysis**: Automated analysis of sending patterns
+- **Alert generation**: Automated alerts for threshold breaches
+- **Report generation**: Automated delivery and performance reports
+
+---
+
+**Amazon SES provides enterprise-grade email delivery with comprehensive monitoring and management capabilities, making it ideal for applications requiring reliable email delivery.** 🚀