Skip to main content

Welcome Email for Daily Newsletter Subscribers

Overview​

When a user subscribes to the daily newsletter through SendGrid, they automatically receive a personalized welcome email using SendGrid's dynamic templates. This feature ensures new subscribers receive a warm welcome while preventing duplicate emails through intelligent subscription state checking.

Key Features​

  • Automatic Delivery: Welcome emails are sent automatically when users subscribe to the daily newsletter segment
  • Localized Templates: Each locale has its own welcome template (e.g., English, Spanish, French)
  • Duplicate Prevention: System checks existing subscription status to avoid sending multiple welcome emails
  • Graceful Degradation: Subscription succeeds even if welcome email delivery fails
  • Template-Based: Uses SendGrid dynamic templates for easy content management

How It Works​

Subscription Flow​

  1. User subscribes to the daily newsletter via API (e.g., POST /subscriptions)
  2. System checks if user is already subscribed to the daily segment
  3. If user is new to daily segment:
    • Processes the subscription
    • Identifies appropriate welcome template based on locale
    • Sends welcome email via SendGrid
  4. If user is already subscribed:
    • Updates subscription (if needed)
    • Skips welcome email

Template Naming Convention​

Welcome email templates in SendGrid must follow this naming pattern:

WELCOME-<LOCALE>

Examples:

  • WELCOME-EN for English
  • WELCOME-ES for Spanish
  • WELCOME-FR for French
  • WELCOME-PT for Portuguese
  • WELCOME-IT for Italian
  • WELCOME-PL for Polish

Template Structure​

Welcome email templates are simple and only require the recipient's email in the to field. No additional dynamic template data is needed.

Template Requirements:

  • Must have an active version (version with active == 1)
  • Subject line defined in the active version
  • No dynamic data variables required (recipient email is in to field automatically)

Implementation Details​

Components​

1. Template Retrieval (Sendgrid::API.templates)​

Fetches all dynamic templates from the SendGrid account with caching for performance.

# Retrieves templates with caching
API.templates
# Force refresh
API.templates(force: true)

2. Welcome Letter Concern (Sendgrid::WelcomeLetter)​

A Rails concern that provides welcome email functionality:

module Sendgrid
  module WelcomeLetter
    # Find welcome template for a locale
    def welcome_letter_for(locale:)
      # Returns WelcomeTemplate object for the locale
    end
    
    # Send welcome email
    def send_welcome_letter_for(email:, locale:)
      # Sends the welcome email
    end
    
    # Send transactional email with template
    def send_transactional_email(template, personalization:)
      # Low-level email sending
    end
  end
end

3. Job Integration (ProcessSubscriptionRequestJob)​

The subscription processing job checks subscription status and triggers welcome emails:

def perform(request_params, provider = nil)
  # ... validation ...
  
  # Check if should send welcome letter (before subscription)
  should_send_welcome_letter = should_send_sendgrid_welcome_letter?
  
  # Process subscription
  service.subscribe_from_request(request)
  
  # Send welcome letter if needed (after subscription)
  send_sendgrid_welcome_letter if should_send_welcome_letter
end

Conditions for Sending Welcome Email​

Welcome email is sent only when ALL conditions are met:

  1. Provider is SendGrid: Only applies to SendGrid subscriptions
  2. Subscription type is 'daily': Only for daily newsletter segment
  3. Locale is present: User must have a locale specified
  4. User not already subscribed: User must not currently be in the daily segment

Error Handling​

The implementation uses graceful error handling:

  • Template not found: Logs warning, subscription proceeds
  • Email sending fails: Logs error, subscription proceeds
  • Status check fails: Assumes new user, sends welcome email anyway

This ensures that subscription requests always succeed, even if the welcome email cannot be delivered.

Setting Up Templates​

1. Create Dynamic Templates in SendGrid​

For each supported locale, create a dynamic template in your SendGrid account:

  1. Log into SendGrid dashboard
  2. Navigate to Email API > Dynamic Templates
  3. Create a new template with name: WELCOME-<LOCALE> (e.g., WELCOME-EN)
  4. Design your welcome email content
  5. Ensure the template has an active version

2. Template Content Guidelines​

  • Subject Line: Set a clear, welcoming subject line
  • Content: Include welcome message, value proposition, and next steps
  • Personalization: Recipient email is automatically included (no variables needed)
  • Branding: Match your brand's visual identity
  • Call-to-Action: Guide users on what to do next

3. Testing Templates​

Before deploying, test your templates:

# In Rails console
service = Sendgrid::Service.new
template = service.welcome_letter_for(locale: 'en')
# => Returns template object with id, name, versions

# Send test email (in development/staging)
service.send_welcome_letter_for(
  email: '[email protected]',
  locale: 'en'
)

Monitoring​

Logging​

The system logs welcome email activity at various levels:

# Info level: Email being sent
"Sending welcome letter to [email protected] for locale en"
"Sending 'Welcome to Aleteia' email to 1 recipient(s)"

# Warning level: Template issues
"Cannot send welcome letter: Welcome template not found for locale: it"

# Error level: Send failures
"Failed to send Sendgrid welcome letter: API error"

Metrics to Monitor​

  • Welcome email send success rate
  • Template not found errors (indicates missing locale templates)
  • Send failures (indicates SendGrid API issues)
  • Duplicate prevention effectiveness (users already subscribed count)

API Reference​

Sendgrid::API.templates(force: false)​

Retrieves all dynamic templates from SendGrid account.

Parameters:

  • force (Boolean): Skip cache and fetch fresh data

Returns: Array of template objects with id, name, and versions

welcome_letter_for(locale:)​

Finds the welcome template for a given locale.

Parameters:

  • locale (String/Symbol): Locale code (e.g., 'en', 'es')

Returns: WelcomeTemplate object

Raises: TemplateNotFound if template doesn't exist for locale

send_welcome_letter_for(email:, locale:)​

Sends welcome email to a user.

Parameters:

  • email (String): Recipient email address
  • locale (String/Symbol): Locale code

Returns: HTTParty::Response on success, nil if template not found

send_transactional_email(template, personalization:)​

Low-level method to send transactional email.

Parameters:

  • template (WelcomeTemplate): Template object
  • personalization (Hash/Array): Personalization data with :to field

Returns: HTTParty::Response

Troubleshooting​

Welcome Email Not Sent​

Symptoms: User subscribed but didn't receive welcome email

Possible Causes:

  1. Template not found for locale
  2. User already subscribed to daily segment
  3. SendGrid API error
  4. Locale not specified in subscription request

Investigation:

  • Check logs for "Sending welcome letter" messages
  • Verify template exists: WELCOME-<LOCALE>
  • Check user's current subscription status
  • Verify SendGrid API credentials

Duplicate Welcome Emails​

Symptoms: User receives multiple welcome emails

Possible Causes:

  1. Multiple concurrent subscription requests
  2. Subscription state check failing
  3. Race condition in processing

Prevention:

  • System checks subscription status before sending
  • Idempotent subscription API (upserts)
  • Job processes sequentially per user

Template Not Found Error​

Symptoms: Warning in logs: "Welcome template not found for locale: xx"

Solution:

  1. Create template in SendGrid: WELCOME-<LOCALE>
  2. Ensure template has active version
  3. Verify template name matches exactly (case-sensitive)
  4. Force refresh template cache if recently added

Best Practices​

  1. Template Maintenance: Regularly review and update welcome email content
  2. Testing: Test templates in staging before production deployment
  3. Localization: Ensure all supported locales have corresponding templates
  4. Monitoring: Set up alerts for template not found errors
  5. Content: Keep welcome emails concise and action-oriented
  6. Performance: Template cache reduces API calls to SendGrid

Support​

For issues or questions about welcome emails:

  1. Check logs for error messages
  2. Verify template configuration in SendGrid
  3. Test in development/staging environment
  4. Review subscription API documentation