Merge pull request #101 from cs169/feature/mailbluster

Feature/mailbluster

Author: kienthuynh

.env.example

@@ -20,6 +20,7 @@ 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]
 SENTRY_DSN=
 SNAP_CLIENT_SECRET='ignore'
 SNAP_CLIENT_URL='https://forum.snap.berkeley.edu/session/sso_provider'

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(", ")
@@ -33,6 +35,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="badge badge-pill badge-primary h6">primary</span>' if email.primary?
+    labels << '<span class="badge badge-pill badge-danger h6">bounced</span>' if email.bounced?
+    return nil if labels.empty?
+    "&nbsp; #{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/models/email_address.rb

@@ -4,12 +4,15 @@
 #
 # 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
+#  primary          :boolean          default(FALSE), not null
+#  created_at       :datetime         not null
+#  updated_at       :datetime         not null
+#  teacher_id       :bigint           not null
 #
 # Indexes
 #
@@ -31,6 +34,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/teacher.rb

@@ -4,31 +4,35 @@
 #
 # Table name: teachers
 #
-#  id                 :integer          not null, primary key
-#  admin              :boolean          default(FALSE)
-#  application_status :string           default("not_reviewed")
-#  education_level    :integer          default(NULL)
-#  email              :string
-#  first_name         :string
-#  ip_history         :inet             default([]), is an Array
-#  languages          :string           default(["\"English\""]), is an Array
-#  last_name          :string
-#  last_session_at    :datetime
-#  more_info          :string
-#  personal_email     :string
-#  personal_website   :string
-#  session_count      :integer          default(0)
-#  snap               :string
-#  status             :integer
-#  created_at         :datetime
-#  updated_at         :datetime
-#  school_id          :integer
+#  id                    :integer          not null, primary key
+#  admin                 :boolean          default(FALSE)
+#  application_status    :string           default("not_reviewed")
+#  education_level       :integer          default(NULL)
+#  email                 :string
+#  first_name            :string
+#  ip_history            :inet             default([]), is an Array
+#  languages             :string           default(["\"English\""]), is an Array
+#  last_name             :string
+#  last_session_at       :datetime
+#  mailbluster_synced_at :datetime
+#  more_info             :string
+#  personal_email        :string
+#  personal_website      :string
+#  session_count         :integer          default(0)
+#  snap                  :string
+#  status                :integer
+#  verification_notes    :text
+#  created_at            :datetime
+#  updated_at            :datetime
+#  mailbluster_id        :integer
+#  school_id             :integer
 #
 # Indexes
 #
 #  index_teachers_on_email                     (email) UNIQUE
 #  index_teachers_on_email_and_first_name      (email,first_name)
 #  index_teachers_on_email_and_personal_email  (email,personal_email) UNIQUE
+#  index_teachers_on_mailbluster_id            (mailbluster_id) UNIQUE
 #  index_teachers_on_school_id                 (school_id)
 #  index_teachers_on_snap                      (snap) UNIQUE WHERE ((snap)::text <> ''::text)
 #  index_teachers_on_status                    (status)
@@ -311,17 +315,46 @@ def self.csv_export
       school_website
       school_grade_level
       school_type
+      mailbluster_id
+      primary_email_sent
+      primary_email_delivered
+      primary_email_bounced
     |
 
     CSV.generate(headers: true) do |csv|
       csv << attributes
 
-      Teacher.where(admin: false).find_each do |user|
+      Teacher.where(admin: false).includes(:email_addresses).find_each do |user|
         csv << attributes.map { |attr| user.send(attr) }
       end
     end
   end
 
+  def mailbluster_synced?
+    mailbluster_id.present?
+  end
+
+  def mailbluster_profile_url
+    return nil unless mailbluster_id.present?
+    "https://app.mailbluster.com/leads/#{mailbluster_id}"
+  end
+
+  def primary_email_address
+    email_addresses.find_by(primary: true)
+  end
+
+  def primary_email_sent
+    primary_email_address&.emails_sent || 0
+  end
+
+  def primary_email_delivered
+    primary_email_address&.emails_delivered || 0
+  end
+
+  def primary_email_bounced
+    primary_email_address&.bounced? ? "Yes" : "No"
+  end
+
   private
   def non_primary_emails
     email_addresses.where(primary: false)&.pluck(:email)