Getting Started

Minimal Setup

Install the package:
```
composer require async-aws/ses
```

Configure AWS credentials in .env:

AWS_ACCESS_KEY_ID=your_key
AWS_SECRET_ACCESS_KEY=your_secret
AWS_DEFAULT_REGION=us-east-1  # or your preferred region

Basic email send (Laravel integration):

use AsyncAws\Ses\SesClient;
use AsyncAws\Ses\ValueObject\Destination;
use AsyncAws\Ses\ValueObject\Content;

$ses = new SesClient();
$response = $ses->sendEmail([
    'Destination' => new Destination(['ToAddresses' => ['user@example.com']]),
    'Content' => new Content([
        'Simple' => [
            'Subject' => ['Data' => 'Test Email'],
            'Body' => ['Text' => ['Data' => 'Hello from SES!']],
        ],
    ]),
]);

First Use Case: Transactional Emails

Replace Laravel’s default Mail facade with a queueable SES sender:

// app/Providers/AppServiceProvider.php
public function boot()
{
    Mail::extend('ses', function ($app) {
        return new class extends Mailer {
            public function send(Mailable $mailable, Address $to)
            {
                $ses = new SesClient();
                $response = $ses->sendEmail([
                    'Destination' => new Destination(['ToAddresses' => [$to->email]]),
                    'Content' => new Content([
                        'Simple' => [
                            'Subject' => ['Data' => $mailable->subject],
                            'Body' => ['Text' => ['Data' => $mailable->content]],
                        ],
                    ]),
                ]);
                return new MailMessage($response);
            }
        };
    });
}

Use it in your app:

Mail::ses()->to('user@example.com')->send(new OrderConfirmation($order));

Implementation Patterns

1. Async Workflow with Laravel Queues

Leverage Laravel’s queue system for non-blocking email delivery:

// Dispatch a queued email
Mail::ses()->to('user@example.com')->send(new WelcomeEmail($user))
    ->afterCommit(); // Ensures email is sent after DB commit

Queue configuration (config/queue.php):

'connections' => [
    'ses' => [
        'driver' => 'database',
        'table' => 'jobs',
        'queue' => 'ses_emails',
        'after_commit' => true,
    ],
],

2. Email Templates (SESv2)

Use SESv2’s template system for reusable content:

// Store a template in AWS SES Console first
$ses = new SesClient();
$response = $ses->sendEmail([
    'FromEmailAddress' => 'noreply@example.com',
    'Destination' => new Destination(['ToAddresses' => ['user@example.com']]),
    'Content' => new Content([
        'Template' => [
            'TemplateName' => 'welcome_template',
            'TemplateData' => json_encode(['name' => $user->name]),
        ],
    ]),
]);

3. Bulk Emails

Send to multiple recipients efficiently:

$ses = new SesClient();
$response = $ses->sendBulkEmail([
    'FromEmailAddress' => 'noreply@example.com',
    'Destination' => new Destination(['ToAddresses' => ['user1@example.com', 'user2@example.com']]),
    'Content' => new Content([
        'Simple' => [
            'Subject' => ['Data' => 'Bulk Update'],
            'Body' => ['Text' => ['Data' => 'Hello, users!']],
        ],
    ]),
]);

4. Attachments

Add files to emails (SESv2 feature):

$ses = new SesClient();
$response = $ses->sendEmail([
    'FromEmailAddress' => 'noreply@example.com',
    'Destination' => new Destination(['ToAddresses' => ['user@example.com']]),
    'Content' => new Content([
        'Simple' => [
            'Subject' => ['Data' => 'Invoice'],
            'Body' => ['Text' => ['Data' => 'Please find your invoice attached.']],
        ],
    ]),
    'Attachments' => [
        [
            'Data' => base64_encode(file_get_contents('invoice.pdf')),
            'Name' => 'invoice.pdf',
            'ContentType' => 'application/pdf',
        ],
    ],
]);

5. Custom Headers

Add headers for tracking or custom logic:

$ses = new SesClient();
$response = $ses->sendEmail([
    'FromEmailAddress' => 'noreply@example.com',
    'Destination' => new Destination(['ToAddresses' => ['user@example.com']]),
    'Content' => new Content([
        'Simple' => [
            'Subject' => ['Data' => 'Tracking Header'],
            'Body' => ['Text' => ['Data' => 'Check headers!']],
        ],
    ]),
    'Headers' => [
        ['Name' => 'X-Custom-ID', 'Value' => 'order_12345'],
        ['Name' => 'X-Tracking', 'Value' => 'marketing_campaign'],
    ],
]);

6. Error Handling

Wrap SES calls in try-catch blocks:

use AsyncAws\Core\Exception\AwsException;

try {
    $response = $ses->sendEmail([/* ... */]);
} catch (AwsException $e) {
    Log::error('SES Error: ' . $e->getAwsErrorMessage());
    // Retry logic or fallback to another provider
}

7. Multi-Region Support

Configure region-specific clients:

$euSes = new SesClient(['region' => 'eu-west-1']);
$usSes = new SesClient(['region' => 'us-east-1']);

// Send region-specific emails
$euSes->sendEmail([/* ... */]);
$usSes->sendEmail([/* ... */]);

8. Suppression Lists (SESv2)

Manage bounced/complaint lists:

// Add a suppressed destination
$ses->setSuppressedDestination([
    'Destination' => 'user@example.com',
    'Reason' => 'Complaint',
]);

// Delete a suppressed destination
$ses->deleteSuppressedDestination([
    'Destination' => 'user@example.com',
]);

Gotchas and Tips

Pitfalls

AWS SES Sandbox Restrictions:
- New SES accounts start in sandbox mode, limiting emails to verified identities.
- Fix: Request production access from AWS after verifying your domain/email.
- Tip: Use verifyEmailIdentity() to verify addresses programmatically:
```
$ses->verifyEmailIdentity(['EmailAddress' => 'user@example.com']);
```
Quota Limits:
- SES has send rate limits (e.g., 14 emails/sec by default).
- Fix: Monitor SendQuotaExceeded exceptions and adjust limits in AWS Console or use exponential backoff in retries.
Attachment Size Limits:
- SESv2 supports attachments up to 50MB total per email.
- Tip: For larger files, use pre-signed URLs or a file-hosting service.
DKIM Misconfiguration:
- Missing or incorrect DKIM records can cause emails to land in spam.
- Fix: Verify DKIM records in AWS SES Console and use tools like MXToolbox to test.
Region-Specific Features:
- Some SES features (e.g., fips-* regions) require specific configurations.
- Tip: Check the AWS SES Region Table for compatibility.
Async Delays:
- Emails sent via queues may take seconds to minutes to deliver.
- Tip: Use Mail::later() for time-sensitive emails or switch to sync SES calls for critical paths.
PHP 8.2+ Requirement:
- The package drops support for PHP <8.2.
- Fix: Update your PHP version or use an older package version (e.g., 1.13.*).
Null Values in Inputs:
- Optional fields can be explicitly set to null (e.g., ['ReplyToAddresses' => null]).
- Tip: Use null to override default values in SES requests.

Debugging Tips

Enable AWS SDK Debugging: Add to .env:
```
AWS_DEBUG=true
```
Or configure the client:
```
$ses = new SesClient(['debug' => true]);
```

Log SES Responses:

$response = $ses->sendEmail([/* ... */]);
Log::debug('SES Response', ['response' => $response->toArray()]);

Validate Inputs: Use Input\* classes to ensure valid payloads:
```
use AsyncAws\Ses\Input\SendEmailRequest;

$input =
```

Ses Laravel Package