Configuring Email Delivery with AWS SESv2 in PropertyWebBuilder: SMTP and API Methods

Configure AWS SESv2 in PropertyWebBuilder by setting SMTP environment variables for standard ActionMailer delivery or AWS SES credentials for API-based sending via the Pwb::SES module.

PropertyWebBuilder provides a flexible email delivery architecture designed to work with Amazon SES v2 through two distinct paths. Whether you prefer traditional SMTP relay or direct API integration, the codebase in etewiah/property_web_builder supports both methods through environment-driven configuration and a dedicated helper module.

How PropertyWebBuilder Handles Email Delivery

The repository implements a dual-strategy approach that lets operators choose between SMTP delivery (compatible with standard Rails ActionMailer) and SES v2 API delivery (for programmatic access to advanced features).

Core Email Components

• config/initializers/amazon_ses.rb – Defines the Pwb::SES helper module, which constructs an Aws::SESV2::Client and exposes utility methods for account management and test sending.
• config/environments/production.rb – Configures ActionMailer delivery settings, automatically selecting SMTP when SMTP_ADDRESS is present or falling back to test mode.
• app/mailers/pwb/application_mailer.rb – Serves as the base mailer class that inherits the globally configured delivery method.
• lib/tasks/ses.rake – Provides rake task wrappers for command-line SES diagnostics.

SMTP Delivery Configuration

When SMTP_ADDRESS is defined in your environment, config/environments/production.rb (lines 97-108) automatically configures ActionMailer to use Amazon SES's SMTP endpoint:

config.action_mailer.delivery_method = :smtp
config.action_mailer.smtp_settings = {
  address: ENV["SMTP_ADDRESS"],
  port:    ENV.fetch("SMTP_PORT", 587).to_i,
  user_name: ENV["SMTP_USERNAME"],
  password:  ENV["SMTP_PASSWORD"],
  domain:    ENV.fetch("SMTP_DOMAIN") { ENV.fetch("MAILER_HOST") { ENV.fetch("APP_HOST", "example.com") } },
  authentication: ENV.fetch("SMTP_AUTH", "plain").to_sym,
  enable_starttls_auto: true
}

This configuration requires no code changes to existing mailers. Any class inheriting from Pwb::ApplicationMailer automatically routes through the SES SMTP interface.

SES v2 API Delivery

The Pwb::SES module (defined in config/initializers/amazon_ses.rb) provides direct SDK access when AWS credentials are present. The module lazily initializes an Aws::SESV2::Client and exposes these key methods:

• account_info – Retrieves sending quotas and account status.
• verified_identities – Lists verified domains and email addresses.
• identity_verified?(identity) – Validates specific sender identities.
• send_test_email(to:, from: nil) – Dispatches test messages via the API.

This approach bypasses ActionMailer entirely, enabling features like suppression list management and bulk sending workflows that aren't available through SMTP.

Configuration Steps for AWS SESv2

Setting up email delivery requires environment variables and identity verification in the AWS console.

Required Environment Variables

Variable	Required For	Description
SMTP_ADDRESS	SMTP	SES SMTP endpoint (e.g., email-smtp.us-east-1.amazonaws.com)
SMTP_PORT	SMTP	Typically 587 for TLS
SMTP_USERNAME	SMTP	SMTP credentials from AWS console
SMTP_PASSWORD	SMTP	SMTP password from AWS console
AWS_SES_ACCESS_KEY_ID	API	IAM access key for SES v2
AWS_SES_SECRET_ACCESS_KEY	API	IAM secret key for SES v2
AWS_SES_REGION	Both	AWS region (e.g., us-east-1)
DEFAULT_FROM_EMAIL	Both	Fallback sender address
MAILER_HOST	Both	Host for generating email links

Selecting Your Delivery Mode

1. For SMTP delivery: Populate all SMTP_* variables. The application automatically detects SMTP_ADDRESS and configures ActionMailer accordingly.

2. For API delivery: Set AWS_SES_ACCESS_KEY_ID, AWS_SES_SECRET_ACCESS_KEY, and AWS_SES_REGION. The Pwb::SES module becomes available for custom logic and diagnostics.

Verifying Identities

Before sending, verify your domain or email address in the Amazon SES console. You can confirm verification status programmatically:

rails console
> Pwb::SES.identity_verified?("noreply@mydomain.com")

# => true

Testing the Configuration

Test SMTP delivery through a standard mailer:

Pwb::NotificationMailer.new_user_welcome(user).deliver_now

Test API delivery using the helper module:

Pwb::SES.send_test_email(to: "you@example.com")

Code Examples for AWS SESv2 Integration

Environment Variable Setup

Create a .env file or configure your deployment platform with these values:

# SMTP Configuration

SMTP_ADDRESS=email-smtp.us-east-1.amazonaws.com
SMTP_PORT=587
SMTP_USERNAME=AKIAIOSFODNN7EXAMPLE
SMTP_PASSWORD=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

# SES v2 API Configuration

AWS_SES_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SES_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
AWS_SES_REGION=us-east-1

# Application Settings

DEFAULT_FROM_EMAIL=noreply@mydomain.com
MAILER_HOST=app.mydomain.com

Sending Test Emails via the API

The repository includes rake tasks in lib/tasks/ses.rake for command-line testing:

namespace :ses do
  desc "Send a test email using the SES v2 API"
  task :test, [:to] => :environment do |t, args|
    to = args[:to] || ENV["DEFAULT_TO"]
    raise "Recipient address required" unless to

    result = Pwb::SES.send_test_email(to: to)
    puts result.inspect
  end
end

Execute from the terminal:

bundle exec rake ses:test[admin@example.com]

Using ActionMailer with SMTP

Create a mailer inheriting from the base class:

# app/mailers/pwb/notification_mailer.rb

class Pwb::NotificationMailer < Pwb::ApplicationMailer
  def new_user_welcome(user)
    @user = user
    mail(
      to: @user.email,
      subject: "Welcome to PropertyWebBuilder"
    )
  end
end

Queue the email using Active Job:

Pwb::NotificationMailer.new_user_welcome(current_user).deliver_later

Because config.action_mailer.delivery_method is set to :smtp when SMTP_ADDRESS exists, the message routes through Amazon SES's SMTP endpoint without additional configuration.

Checking SES Quotas Programmatically

Monitor your sending limits before bulk operations:

info = Pwb::SES.account_info

if info[:error]
  Rails.logger.error "SES configuration error: #{info[:error]}"
else
  quota = info[:send_quota]
  Rails.logger.info "SES quota: #{quota[:max_24_hour_send]} emails per day"
  Rails.logger.info "Max send rate: #{quota[:max_send_rate]} per second"
end

Summary

• PropertyWebBuilder supports AWS SESv2 through both SMTP (ActionMailer) and API (Pwb::SES module) interfaces.
• SMTP configuration requires SMTP_ADDRESS, SMTP_USERNAME, and SMTP_PASSWORD environment variables, automatically detected in config/environments/production.rb.
• API configuration requires AWS_SES_ACCESS_KEY_ID and AWS_SES_SECRET_ACCESS_KEY, enabling direct SDK access through config/initializers/amazon_ses.rb.
• The SES v2 API provides advanced features like quota monitoring and suppression list management that SMTP cannot access.
• Always verify sender identities in the AWS console before deploying to production.
• Use Pwb::SES.send_test_email or the ses:test rake task to validate connectivity without triggering full mailer workflows.

Frequently Asked Questions

What is the difference between SMTP and API delivery in PropertyWebBuilder?

SMTP delivery uses the standard ActionMailer stack configured in config/environments/production.rb, treating Amazon SES as a traditional mail relay. It works with any Rails mailer without code changes. API delivery uses the Aws::SESV2::Client directly through the Pwb::SES module, providing access to sending statistics, bulk operations, and suppression lists that aren't available via SMTP.

Which environment variables are required for AWS SESv2?

For SMTP, you need SMTP_ADDRESS, SMTP_USERNAME, and SMTP_PASSWORD. For API access, you need AWS_SES_ACCESS_KEY_ID and AWS_SES_SECRET_ACCESS_KEY. Both methods require AWS_SES_REGION (or AWS_REGION) and benefit from DEFAULT_FROM_EMAIL for proper sender identification.

How do I verify my SES identity is configured correctly?

Call Pwb::SES.verified_identities from the Rails console to list verified domains and addresses, or use Pwb::SES.identity_verified?("your@email.com") to check a specific identity. You can also run Pwb::SES.account_info to confirm API connectivity and view your sending quota.

Can I use both SMTP and API methods simultaneously?

Yes. The configurations are independent. You can use SMTP for standard application mailers while using the SES v2 API for background jobs, bulk newsletters, or administrative functions that require detailed sending analytics. The Pwb::SES module remains available regardless of your SMTP settings.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}