feat: Support SMTP as an alternative email provider to Sparkpost (#172)

Author: sman591

README.md

@@ -31,7 +31,7 @@ HackathonManager makes use of a few different third-party services & Ruby gems:
 
 - [Devise](https://github.com/plataformatec/devise) + [MyMLH](https://my.mlh.io/) (authentication & attendee identity)
 - [Sidekiq](https://github.com/mperham/sidekiq) (background jobs)
-- [Sparkpost](https://www.sparkpost.com/) (email)
+- [SparkPost](https://www.sparkpost.com/) (email)
 - [Amazon S3](https://aws.amazon.com/s3/) (resume storage)
 - [Chartkick](http://chartkick.com/) (management UI charts)
 - [Blazer](https://github.com/ankane/blazer) (custom SQL queries, analytics, and charts)

app.json

@@ -59,11 +59,11 @@
       "required": false
     },
     "SPARKPOST_API_KEY": {
-      "description": "Sparkpost API key for sending email",
+      "description": "SparkPost API key for sending email",
       "required": false
     },
     "SPARKPOST_CAMPAIGN_ID": {
-      "description": "Sparkpost campaign ID for sending email (e.g. the name of your hackathon)",
+      "description": "SparkPost campaign ID for sending email (e.g. the name of your hackathon)",
       "required": false
     },
     "HM_DOMAIN_NAME": {

app/mailers/user_mailer.rb

@@ -23,7 +23,7 @@ def incomplete_reminder_email(user_id)
 
   rescue_from SparkPostRails::DeliveryException do |e|
     error_codes_to_not_retry = [
-      "1902", # Generation rejection
+      "1902", # Generation rejection, specific to the Sparkpost API
     ]
     raise e unless e.blank? || error_codes_to_not_retry.include?(e.service_code)
   end

app/views/manage/configs/index.html.haml

@@ -63,10 +63,30 @@
         = render 'config_row', name: 'Domain Name', key: 'HM_DOMAIN_NAME'
         = render 'config_row', name: 'Domain Protocol', key: 'HM_DOMAIN_PROTOCOL', default: 'https'
         %hr
-        = render 'config_row', name: 'Sparkpost API Key', key: 'SPARKPOST_API_KEY', secret: true
-        = render 'config_row', name: 'Sparkpost Campaign ID', key: 'SPARKPOST_CAMPAIGN_ID'
-        %hr
         = render 'config_row', name: 'My MLH Application ID', key: 'MLH_KEY'
         = render 'config_row', name: 'My MLH Secret', key: 'MLH_SECRET', secret: true
         %hr
         = render 'config_row', name: 'Rollbar Access Token', key: 'ROLLBAR_ACCESS_TOKEN', secret: true, required: false
+        %hr
+        %p.mb-0
+          %b Email Provider
+        - if Rails.application.config.action_mailer.delivery_method == :smtp
+          %p
+            %span.badge.badge-secondary SparkPost
+            %span.badge.badge-success SMTP
+            %br
+            %small
+              %i To switch to SparkPost, unset the <code>SMTP_ADDRESS</code> environment variable
+          = render 'config_row', name: 'SMTP Address', key: 'SMTP_ADDRESS'
+          = render 'config_row', name: 'SMTP Port', key: 'SMTP_PORT', default: 587
+          = render 'config_row', name: 'SMTP Username', key: 'SMTP_USER_NAME'
+          = render 'config_row', name: 'SMTP Password', key: 'SMTP_PASSWORD'
+        - else
+          %p
+            %span.badge.badge-success SparkPost
+            %span.badge.badge-secondary SMTP
+            %br
+            %small
+              %i To switch to SMTP, set the <code>SMTP_ADDRESS</code> environment variable
+          = render 'config_row', name: 'SparkPost Campaign ID', key: 'SPARKPOST_CAMPAIGN_ID'
+          = render 'config_row', name: 'SparkPost API Key', key: 'SPARKPOST_API_KEY', secret: true

app/views/manage/questionnaires/_history.html.haml

@@ -9,5 +9,10 @@
     .card.mb-3
       .card-header Recent Email Events
       .card-body
-        .email-events{ data: { url: message_events_manage_questionnaire_path(@questionnaire) } }
-          %em Email events not available at this time.
+        - email_provider = Rails.application.config.action_mailer.delivery_method
+        - if email_provider == :sparkpost
+          .email-events{ data: { url: message_events_manage_questionnaire_path(@questionnaire) } }
+            %em Email events not available at this time.
+        - else
+          %p.alert.alert-info
+            Not supported with current email provider (#{email_provider})

config/environments/production.rb

@@ -94,8 +94,21 @@
 
   ### Custom config below this line ###
 
-  # Send email through Sparkpost API
-  config.action_mailer.delivery_method = :sparkpost
+  if ENV["SMTP_ADDRESS"].present?
+    # Send email through SMTP
+    config.action_mailer.delivery_method = :smtp
+    config.action_mailer.smtp_settings = {
+      address: ENV["SMTP_ADDRESS"].presence,
+      port: ENV["SMTP_PORT"].presence&.to_i || 587,
+      username: ENV["SMTP_USER_NAME"].presence,
+      password: ENV["SMTP_PASSWORD"].presence,
+      authentication: ENV["SMTP_AUTHENTICATION"].presence || "plain",
+      enable_starttls_auto: ENV["SMTP_STARTTLS_AUTO"] != "false", # defaults to true
+    }
+  else
+    # Send email through SparkPost API
+    config.action_mailer.delivery_method = :sparkpost
+  end
 
   # Required for email messages
   mailer_url_host = ENV["HM_DOMAIN_NAME"]

docs/deployment-environment-variables.md

@@ -60,15 +60,36 @@ S3_FORCE_PATH_STYLE=true
 
 ### E-mail
 
-Currently, emails are queued via Sidekiq and then sent by Sparkpost's servers.
+Emails can be sent using [SparkPost](https://www.sparkpost.com) or traditional SMTP.
 
-Create a Sparkpost API key with **Transmissions: Read/Write** and **Message Events: Read-only** permissions, limited to the production server's IP address. SMTP is _not_ required, as email is sent over the Sparkpost API rather than SMTP.
+#### SparkPost
+
+[SparkPost](https://www.sparkpost.com) is the recommended email provider, and provides a free plan suitable for most hackathons.
+
+Create a SparkPost API key with **Transmissions: Read/Write** and **Message Events: Read-only** permissions. The SMTP permission is _not_ required, as email is sent over the SparkPost API instead of SMTP.
+
+For added security, whitelist the API key to your server's IP address.
 
 ```bash
 SPARKPOST_API_KEY=""
 SPARKPOST_CAMPAIGN_ID=""
 ```
 
+#### SMTP
+
+>Sending email with SMTP over a personal or school email address (such as Gmail) is **NOT** recommended. Your hackathon may easily send several hundred to a few thousand emails during months leading up to the event, which regular email accounts block and may get reported for spam.
+>
+>Be sure your SMTP provider is configured appropriately for mass email, and check periodically that emails are being delivered successfully.
+
+```bash
+SMTP_ADDRESS="mail.example.com"
+SMTP_USER_NAME=""
+SMTP_PASSWORD=""
+SMTP_PORT=""           # optional, 587 by default
+SMTP_AUTHENTICATION="" # optional, "plain" by default
+SMTP_STARTTLS_AUTO=""  # optional, "true" by default
+```
+
 ### Rollbar
 
 Rollbar captures and notifies of errors in production, and requires a server-side access token.