aidevops 2.52.1 → 2.53.2

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

@@ -1,399 +0,0 @@
----
-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.** 🚀