Iteration 5.2 - SES SnsMessageVerifier + aws-sdk-sns gem

.env.example

@@ -20,6 +20,8 @@ S3_BUCKET_NAME=[NEW ONE]
 S3_REGION=us-west-2
 S3_SECRET_ACCESS_KEY=[NEW ONE]
 SECRET_KEY_BASE=[NEW ONE]
+MAILBLUSTER_API_KEY=[NEW ONE]
+SNS_ALLOWED_TOPIC_ARNS=arn:aws:sns:us-west-2:123456789012:ses-events
 SENTRY_DSN=
 SNAP_CLIENT_SECRET='ignore'
 SNAP_CLIENT_URL='https://forum.snap.berkeley.edu/session/sso_provider'

Gemfile

@@ -40,6 +40,9 @@ gem "liquid"
 # Store uploaded files
 gem "aws-sdk-s3", require: false
 
+# Verify signatures on SNS webhook deliveries
+gem "aws-sdk-sns", "~> 1", require: false
+
 # Render images for file uploads in pages
 gem "image_processing", ">= 1.2"
 

Gemfile.lock

@@ -106,6 +106,9 @@ GEM
       aws-sdk-core (~> 3, >= 3.127.0)
       aws-sdk-kms (~> 1)
       aws-sigv4 (~> 1.4)
+    aws-sdk-sns (1.55.0)
+      aws-sdk-core (~> 3, >= 3.127.0)
+      aws-sigv4 (~> 1.1)
     aws-sigv4 (1.4.0)
       aws-eventstream (~> 1, >= 1.0.2)
     axe-core-api (4.3.2)
@@ -569,6 +572,7 @@ DEPENDENCIES
   activerecord-import
   annotate
   aws-sdk-s3
+  aws-sdk-sns (~> 1)
   axe-core-cucumber
   axe-core-rspec
   bootsnap (>= 1.4.4)

README.md

@@ -159,6 +159,44 @@ If bundler install runs successfully, continue with the following commands to co
 - `heroku config:set ...` for each of the environment variables.
 - `heroku open`
 
+## MailBluster Integration
+
+The app integrates with [MailBluster](https://mailbluster.com/) for email marketing and newsletter management.
+
+### Configuration
+
+Set the `MAILBLUSTER_API_KEY` environment variable:
+
+```bash
+# Local development
+export MAILBLUSTER_API_KEY=your_api_key_here
+
+# Heroku
+heroku config:set MAILBLUSTER_API_KEY=your_api_key_here
+```
+
+### Features
+
+- **Auto-sync on approval**: When a teacher is validated, their info is synced to MailBluster as a lead
+- **Auto-sync on status change**: Updating a teacher's application status triggers a MailBluster sync
+- **Auto-sync on email add**: Adding a new email address to a validated teacher triggers sync
+- **Manual sync**: Admins can sync individual teachers or all validated teachers from the UI
+- **Lead cleanup**: Deleting a teacher removes their lead from MailBluster
+- **Delivery tracking**: Email addresses track `emails_sent`, `emails_delivered`, and `bounced` status
+
+### Rake Tasks
+
+```bash
+# Sync all validated teachers to MailBluster
+bundle exec rake mailbluster:sync_all
+
+# Sync a single teacher by ID
+bundle exec rake mailbluster:sync_teacher[123]
+
+# Check sync status
+bundle exec rake mailbluster:status
+```
+
 
 
 ### CodeClimate Local Test

app/controllers/email_addresses_controller.rb

@@ -13,6 +13,8 @@ def create
     end
 
     @teacher.email_addresses.create!(email:, primary: false)
+    # Sync teacher to MailBluster when a new email is added
+    MailblusterService.create_or_update_lead(@teacher) if MailblusterService.configured? && @teacher.validated?
     redirect_to teacher_path(@teacher), notice: "Personal email addresses added successfully."
   rescue ActiveRecord::RecordInvalid => e
     error_message = e.record&.errors&.full_messages&.join(", ")
@@ -28,6 +30,8 @@ def destroy
     end
 
     email.destroy!
+    # Re-sync to MailBluster since email list changed
+    MailblusterService.create_or_update_lead(@teacher) if MailblusterService.configured? && @teacher.validated?
     redirect_to teacher_path(@teacher), notice: "Email address deleted successfully."
   rescue ActiveRecord::RecordNotFound
     redirect_to teacher_path(@teacher), alert: "Email address not found."

app/controllers/teachers_controller.rb

@@ -10,10 +10,10 @@ class TeachersController < ApplicationController
   include CsvProcess
 
   before_action :load_pages, only: [:new, :create, :edit, :update]
-  before_action :load_teacher, except: [:new, :index, :create, :import, :search]
+  before_action :load_teacher, except: [:new, :index, :create, :import, :search, :sync_all_mailbluster]
   before_action :sanitize_params, only: [:new, :create, :edit, :update]
   before_action :require_login, except: [:new, :create]
-  before_action :require_admin, only: [:validate, :deny, :destroy, :index, :show, :search]
+  before_action :require_admin, only: [:validate, :deny, :destroy, :index, :show, :search, :sync_mailbluster, :sync_all_mailbluster]
   before_action :require_edit_permission, only: [:edit, :update, :resend_welcome_email]
 
   rescue_from ActiveRecord::RecordNotUnique, with: :deny_access
@@ -131,6 +131,7 @@ def update
 
     attach_new_files_if_any
     send_email_if_application_status_changed_and_email_resend_enabled
+    sync_to_mailbluster_if_status_changed
 
     if fail_to_update
       return
@@ -162,6 +163,19 @@ def send_email_if_application_status_changed_and_email_resend_enabled
     end
   end
 
+  def sync_to_mailbluster_if_status_changed
+    return unless MailblusterService.configured?
+    return unless @teacher.application_status_changed?
+
+    if @teacher.validated?
+      MailblusterService.create_or_update_lead(@teacher)
+    elsif @teacher.application_status_was == "validated"
+      # If teacher was validated but status changed away, update MailBluster
+      # to mark them as unsubscribed
+      MailblusterService.create_or_update_lead(@teacher)
+    end
+  end
+
   def request_info
     @teacher.info_needed!
     if !params[:skip_email].present?
@@ -173,6 +187,7 @@ def request_info
   def validate
     @teacher.validated!
     TeacherMailer.welcome_email(@teacher).deliver_now
+    MailblusterService.create_or_update_lead(@teacher) if MailblusterService.configured?
     redirect_to root_path
   end
 
@@ -185,6 +200,9 @@ def deny
   end
 
   def destroy
+    if MailblusterService.configured? && @teacher.primary_email.present?
+      MailblusterService.delete_lead(@teacher.primary_email)
+    end
     @teacher.destroy!
     flash[:info] = "Deleted #{@teacher.full_name} successfully."
     redirect_to teachers_path
@@ -208,6 +226,34 @@ def import
     redirect_to teachers_path
   end
 
+  def sync_mailbluster
+    unless MailblusterService.configured?
+      redirect_to teacher_path(@teacher), alert: "MailBluster API key is not configured."
+      return
+    end
+
+    result = MailblusterService.sync_teacher(@teacher)
+    if result[:success]
+      redirect_to teacher_path(@teacher), notice: "Successfully synced #{@teacher.full_name} to MailBluster."
+    else
+      redirect_to teacher_path(@teacher), alert: "Failed to sync #{@teacher.full_name} to MailBluster. #{result[:error]}"
+    end
+  end
+
+  def sync_all_mailbluster
+    unless MailblusterService.configured?
+      redirect_to teachers_path, alert: "MailBluster API key is not configured."
+      return
+    end
+
+    results = MailblusterService.sync_all_teachers
+    flash[:notice] = "MailBluster sync complete: #{results[:synced]} synced, #{results[:failed]} failed, #{results[:skipped]} skipped."
+    if results[:errors].any?
+      flash[:alert] = "Errors: #{results[:errors].first(5).join('; ')}"
+    end
+    redirect_to teachers_path
+  end
+
   private
   def load_teacher
     @teachers = Teacher.all

app/helpers/teacher_helper.rb

@@ -13,7 +13,23 @@ def ip_history_display(teacher)
   end
 
   def email_address_label(email)
-    return unless email.primary?
-    '&nbsp; <span class="badge badge-pill badge-primary h6">primary</span>'.html_safe
+    labels = []
+    labels << '<span class="primary-email-dot" data-toggle="tooltip" data-placement="top" title="Primary email"></span>' if email.primary?
+    labels << '<span class="bounced-email-dot" data-toggle="tooltip" data-placement="top" title="Bounced email"></span>' if email.bounced?
+    return nil if labels.empty?
+    labels.join("").html_safe
+  end
+
+  def mailbluster_sync_status(teacher)
+    if teacher.mailbluster_synced?
+      url = teacher.mailbluster_profile_url
+      if url
+        link_to('<span class="badge badge-success">Synced</span>'.html_safe, url, target: "_blank", title: "View in MailBluster")
+      else
+        '<span class="badge badge-success">Synced</span>'.html_safe
+      end
+    else
+      '<span class="badge badge-secondary">Not Synced</span>'.html_safe
+    end
   end
 end

app/javascript/styles/application.scss

@@ -162,6 +162,25 @@ footer a:active {
   }
 }
 
+.primary-email-dot,
+.bounced-email-dot {
+  display: inline-block;
+  width: 12px;
+  height: 12px;
+  border-radius: 50%;
+  vertical-align: middle;
+  margin-right: 4px;
+  cursor: default;
+}
+
+.primary-email-dot {
+  background-color: #007bff;
+}
+
+.bounced-email-dot {
+  background-color: #dc3545;
+}
+
 .trapezoid {
   position: absolute;
   bottom: -11px;

app/models/email_address.rb

@@ -4,12 +4,18 @@
 #
 # Table name: email_addresses
 #
-#  id         :bigint           not null, primary key
-#  email      :string           not null
-#  primary    :boolean          default(FALSE), not null
-#  created_at :datetime         not null
-#  updated_at :datetime         not null
-#  teacher_id :bigint           not null
+#  id                :bigint           not null, primary key
+#  bounced           :boolean          default(FALSE), not null
+#  email             :string           not null
+#  emails_delivered  :integer          default(0), not null
+#  emails_sent       :integer          default(0), not null
+#  hard_bounce_count :integer          default(0), not null
+#  last_ses_event_at :datetime
+#  primary           :boolean          default(FALSE), not null
+#  soft_bounce_count :integer          default(0), not null
+#  created_at        :datetime         not null
+#  updated_at        :datetime         not null
+#  teacher_id        :bigint           not null
 #
 # Indexes
 #
@@ -23,6 +29,7 @@
 #
 class EmailAddress < ApplicationRecord
   belongs_to :teacher
+  has_many :ses_delivery_events, dependent: :destroy
 
   # Rail's bulit-in validation for email format regex
   validates :email, presence: true, uniqueness: true, format: { with: URI::MailTo::EMAIL_REGEXP }
@@ -31,6 +38,19 @@ class EmailAddress < ApplicationRecord
   before_save :normalize_email
   before_save :flag_teacher_if_email_changed
 
+  scope :bounced, -> { where(bounced: true) }
+  scope :with_undelivered, -> { where("emails_sent > emails_delivered") }
+
+  # Number of emails that were sent but not delivered.
+  def undelivered_count
+    [emails_sent - emails_delivered, 0].max
+  end
+
+  # Whether this email has any undelivered emails.
+  def has_undelivered?
+    undelivered_count > 0
+  end
+
   private
   def only_one_primary_email_per_teacher
     if primary? && EmailAddress.where(teacher_id:, primary: true).where.not(id:).exists?

app/models/ses_delivery_event.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+class SesDeliveryEvent < ApplicationRecord
+  EVENT_TYPES = %w[Send Delivery Bounce Complaint].freeze
+
+  belongs_to :email_address, optional: true
+
+  validates :sns_message_id, presence: true
+  validates :event_type, presence: true
+  validates :recipient_email, presence: true
+  validates :event_occurred_at, presence: true
+
+  scope :hard_bounces, -> { where("event_type = 'Complaint' OR (event_type = 'Bounce' AND bounce_type <> 'Transient')") }
+  scope :soft_bounces, -> { where(event_type: "Bounce", bounce_type: "Transient") }
+end