Email Provider Configuration

This document explains how to configure and switch between email providers in the HungryHub server application.

Available Providers

The application supports two email providers:

1. AWS SES (Default)
2. SendGrid

Configuration

The email provider is configured using the EMAIL_PROVIDER environment variable. If not set, AWS SES is used by default.

AWS SES Configuration

AWS SES is the default email provider when EMAIL_PROVIDER is not set or is set to aws_ses. It supports two authentication methods:

1. IAM Role-based Authentication (Recommended for production)

export EMAIL_PROVIDER=aws_ses  # Optional, this is the default
export SKIP_AWS_KEYS=true

2. Credential-based Authentication

export EMAIL_PROVIDER=aws_ses  # Optional, this is the default
export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key

SendGrid Configuration

To use SendGrid, set the email provider and API key:

export EMAIL_PROVIDER=sendgrid
export SENDGRID_API_KEY=your_sendgrid_api_key

Switching Email Providers

Via Environment Variables (Primary Method)

Set the EMAIL_PROVIDER environment variable and restart the server:

# Switch to SendGrid
export EMAIL_PROVIDER=sendgrid
export SENDGRID_API_KEY=your_sendgrid_api_key

# Switch to AWS SES (or remove EMAIL_PROVIDER to use default)
export EMAIL_PROVIDER=aws_ses

# Use default (AWS SES)
unset EMAIL_PROVIDER

Environment Variables

*Required if not using IAM role authentication for AWS SES

Server Restart

Important: After changing the EMAIL_PROVIDER environment variable, you must restart the server for the changes to take effect. This is because the email configuration is loaded during the Rails initialization process in production environments only.

Configuration Details

Production Environment Only

Email provider configuration is only applied in production environments. In development and test environments, the default Rails mailer configuration is used.

Email Address Configuration

The application automatically configures sender email addresses based on the selected provider:

AWS SES (aws_ses)

• Uses specific verified identities: @hungryhub.net domain
• FINANCE_EMAIL_SENDER: finance@hungryhub.net
• BOOKINGS_EMAIL: bookings@hungryhub.net
• NO_REPLY_EMAIL: bookings@hungryhub.net

SendGrid (sendgrid)

• Uses single verified identity: no-reply@hungryhub.email
• All sender emails use: no-reply@hungryhub.email
• Reply-to addresses remain unchanged for proper routing

Error Handling and Logging

The email configuration includes comprehensive error handling:

• Invalid email providers are rejected with detailed error messages
• Configuration errors are reported to APM for monitoring
• Fallback mechanisms ensure service continuity
• All configuration changes are logged for debugging

Asset Precompilation

The email configuration is automatically skipped during asset precompilation when IS_PRECOMPILE=1 is set.

Troubleshooting

Common Issues

1. SendGrid authentication failed

   • Verify SENDGRID_API_KEY is set correctly
   • Check SendGrid API key permissions
   • Ensure EMAIL_PROVIDER=sendgrid is set

2. AWS SES authentication failed

   • For IAM role: Ensure the role has SES permissions and SKIP_AWS_KEYS=true
   • For credentials: Verify AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY are correct
   • Ensure EMAIL_PROVIDER=aws_ses or leave unset for default

3. Email provider not changing

   • Ensure you restart the server after changing environment variables
   • Check application logs for configuration errors
   • Verify you’re running in production environment

4. Configuration errors during startup

   • Check that required environment variables are set
   • Verify the EMAIL_PROVIDER value is either ‘sendgrid’ or ‘aws_ses’
   • Review application logs for detailed error messages
   • Check APM dashboard for reported configuration errors

5. Sender email verification issues

   • For AWS SES: Ensure all @hungryhub.net addresses are verified in SES console
   • For SendGrid: Ensure no-reply@hungryhub.email is verified in SendGrid dashboard
   • Check email provider logs for authentication/verification errors

Checking Current Configuration

Since the configuration is determined by environment variables, you can check:

# Check current email provider setting
echo $EMAIL_PROVIDER

# Check if SendGrid API key is set
echo $SENDGRID_API_KEY

# Check AWS configuration
echo $AWS_ACCESS_KEY_ID
echo $SKIP_AWS_KEYS

Monitoring and Logs

The email configuration process generates logs that can help with troubleshooting:

# Check application logs for email configuration
tail -f log/hh-server.log | grep "Email provider"

# Look for configuration errors
tail -f log/hh-server.log | grep -i "email.*error"

Common log messages:

• Email provider configuration loaded - Successful configuration
• Using SendGrid sender configuration - SendGrid mode active
• Using AWS SES sender configuration - AWS SES mode active
• Failed to configure sender emails - Configuration error with fallback

File Locations

• Email provider configuration: config/initializers/3_email_provider_config.rb
• AWS SDK configuration: config/initializers/2_amazon_ses_aws.rb
• Production email config: config/environments/production.rb

Security Notes

• Store API keys and credentials as environment variables, never in code
• Use IAM roles instead of access keys when possible in AWS environments
• Regularly rotate API keys and credentials
• Monitor email sending logs for suspicious activity
• Ensure environment variables are properly secured in your deployment environment

Development vs Production

• Development/Test: Email configuration is not applied, uses Rails defaults
• Production: Email provider configuration is active and required
• Asset Precompilation: Email configuration is automatically skipped