Skip to main content

Email Notifications

This document describes all email notifications sent by the donation platform to donors and staff.

Email Infrastructure​

Mailer Class​

All donation emails are sent via:

Email Service Provider​

  • SendGrid is used for email delivery
  • Configured via Action Mailer
  • Emails sent asynchronously via Sidekiq (deliver_later)

Localization​

All emails are localized based on donor's preferred language:

Languages are extracted from:

  1. Transaction/notification metadata (primary)
  2. Stripe customer metadata
  3. Browser locale (initial donation)
  4. Application default (fallback)

URL Configuration​

Email links point to the donations subdomain:

Donor Emails​

1. Thank You Email​

Sent when: Successful donation (single or recurring charge)

Trigger:

Mailer Method:

Email Content:

  • Subject: Localized "Thank you for your donation"
  • Donor's name (first_name + last_name)
  • Donation amount and currency
  • Payment date
  • Transaction ID (for reference)
  • Link to manage subscription (if recurring)
  • Tax deduction information (if applicable)

Template:

Localization Keys:

2. Charge Failed Email​

Sent when: Payment attempt fails (recurring subscription)

Trigger:

Mailer Method:

Email Content:

  • Subject: "Payment failed for your Aleteia donation"
  • Donor's name
  • Failed amount and currency
  • Failure reason (translated):
    • "Card declined"
    • "Insufficient funds"
    • "Card expired"
    • etc.
  • Link to update payment method
  • Information about retry schedule
  • Support contact information

Template:

Common Failure Reasons:

3. Subscription Canceled Email​

Sent when: Donor cancels recurring subscription

Trigger:

Mailer Method:

Email Content:

  • Subject: "Your Aleteia subscription has been canceled"
  • Donor's name
  • Subscription details (amount, frequency)
  • Cancellation date
  • Information about past donations
  • Invitation to donate again in the future
  • Thank you message

Template:

Staff Emails​

1. Charge Failed Staff Notification​

Sent when: Payment fails (for monitoring and support)

Trigger:

Mailer Method:

Email Content:

  • Subject: "Stripe error: card_declined" (or with "[ALERT]" prefix for fraud)
  • Event ID and type
  • Charge ID
  • Customer ID and email
  • Amount and currency
  • Failure code and message
  • Metadata (campaign, locale, etc.)
  • Link to Stripe Dashboard for charge
  • Recommended actions

Template:

Staff Email Recipients: Configured in settings:

2. Fraud Alert Notification​

Sent when: Suspected fraudulent activity detected

Trigger:

Detection Criteria:

  1. Stripe Fraud Detection:

  2. Multiple Failures:

Email Content: Same as regular staff notification, but with:

  • Subject prefixed with "[ALERT] Possible fraud attempt"
  • High priority flag
  • Additional context about why it's flagged as suspicious
  • Automated action taken (payment intent canceled)

Email Sending Strategy​

Asynchronous Delivery​

All emails sent via background jobs:

Benefits:

  • Non-blocking (doesn't delay webhook response)
  • Automatic retry on failure
  • Can be rescheduled if needed
  • Better performance

Delivery Queue​

Retry Logic​

If email delivery fails:

  • Sidekiq automatically retries with exponential backoff
  • Max retries: 25 (default)
  • Failures logged to error tracking (Rollbar)

Email Templates​

Layout​

All donation emails use the newsletter layout:

Layout Structure:

Inline CSS​

Email styles are inlined for better email client compatibility:

  • Use stylesheet_link_tag with email-specific stylesheet
  • Premailer gem (or similar) inlines CSS automatically
  • Mobile-responsive tables and media queries

Testing Templates​

Preview Emails (in development):

Access at: http://localhost:3000/rails/mailers/donations/donor_mailer

RSpec Tests​

Emails include authenticated links for donors to manage subscriptions:

Authentication Token:

  • Token is cryptographically signed
  • Identifies donor uniquely
  • Never expires (donor uses same link forever)
  • Cannot be forged or tampered with

Link Example:

https://donations.aleteia.org/authenticate?authToken=BAh7CEk...

Clicking link authenticates donor and shows subscription management page.

Email Deliverability​

Best Practices Implemented​

  1. SPF/DKIM/DMARC: Configured at DNS level via SendGrid
  2. Unsubscribe Links: Not included (transactional emails)
  3. From Address: Uses verified domain ([email protected])
  4. Reply-To: Can be configured for support email
  5. List-Unsubscribe Header: Not set (transactional, not marketing)

Bounce Handling​

SendGrid handles bounces and sends webhook events:

  • Hard bounces: Donor marked as invalid
  • Soft bounces: Retry automatically
  • Spam reports: Logged and monitored

Email Testing Services​

Use email testing in development:

  • MailCatcher: Local SMTP server with web interface
  • Mailtrap: Development email sandbox
  • Letter Opener: Opens emails in browser

Monitoring & Analytics​

Email Delivery Metrics​

Track via SendGrid:

  • Delivery rate
  • Open rate (if tracking enabled)
  • Click rate
  • Bounce rate
  • Spam complaints

Application Logs​

Error Tracking​

Email failures tracked in Rollbar:

  • Mailer exceptions
  • Template rendering errors
  • SendGrid API errors

Customization​

Email Templates​

Templates can be customized per locale:

app/views/donations/donor_mailer/
  thank_you.html.erb          # Default (English)
  thank_you.it.html.erb       # Italian
  thank_you.es.html.erb       # Spanish
  thank_you.fr.html.erb       # French

Subject Lines​

Localized in translation files:

From Name​

Configure sender name:

Next Steps​