Building a Notifications Inbox in Rails

I’m putting the finishing touches on a new app, to be announced very soon. This app has a few timely events that are important to notify our users about as they happen.

I wanted to create a simple inbox for these notifications on the web, but also send out the notifications on a few different channels that the user is interested in: email, SMS, web push notifications, and more down the road.

Here’s my approach for creating a simple version of a notifications inbox and multi-channel delivery system.

The Notification Model

My first step was to create a model to store the notifications. I had a few ideas in mind for how I wanted to structure the model:

• The notification belongs to a single user in the system.
• The notification keeps track of the channels the user was notified on, for example via email or SMS.
• The notification has a specific ‘action’ associated with it. I liked the idea of a string to identify each action (aka an event) that the user needs to be notified about.
• The notification should keep a reference to the original object that is being notified about. For example, if I’m sending a notifications about a particular calendar appointment, I keep a reference to the appointment model in my notification. This will allow me to link back to that appointment record from the notification.
• For the web inbox, I wanted to keep track of which notifications had been seen or “read” by the user.

Those were my core constraints and ideas around the notification. Here’s the model migration that I came up with:

class CreateNotifications < ActiveRecord::Migration[8.0]

  def change
    create_table :notifications do |t|
      # FK to the user that is receiving this notification
      t.references :user, null: false, foreign_key: true
      
      # the specific action we're notifying about
      t.string :action, null: false
      
      # current status of this notification, enum
      t.integer :status, default: 0
      
      # polymorphic association to an arbitray related record
      t.bigint :record_id
      t.string :record_type

      # which channels this notification has been delivered to:
      t.boolean :delivered_email, default: false
      t.boolean :delivered_sms, default: false
      t.boolean :delivered_web, default: false

      t.datetime :read_at
      
      # timestamp of when the notification was delivered to all channels
      t.datetime :delivered_at

      t.timestamps
    end

    # index for our web inbox
    add_index :notifications, [ :user_id, :delivered_web ], order: { created_at: :desc }

    # index to find notifications by related record
    add_index :notifications, [ :record_id, :record_type ]
  end

end

And here’s the basic corresponding model structure that goes with it:

# app/models/notification.rb
class Notification < ApplicationRecord

  include CustomerFacingIdentifiable

  normalizes :action, with: -> (action) { action.strip.downcase.presence }

  customer_facing_prefix :ntf

  validates :action, presence: true
  validates :user_user_id, presence: true

  belongs_to :user
  belongs_to :record, polymorphic: true, optional: true

  enum :status, {
    # this notification has not yet been sent
    pending: 0,
    
    # this notification has been delivered on all desired channels
    delivered: 1
  }

  # newest notifications at the top of the list
  default_scope { order(created_at: :desc) }

end

This model makes use of my previously-covered Customer Facing Identifiers too, so each notification will have a URL that looks something like this:

https://example.com/notifications/ntf_abc123

Delivering Notifications

The primary delivery channel for the notifications is through email. If someone books a calendar appointment, I want to send the user an email letting them know what happened, with a link back to the app to view details.

As you may or may not know, I love using Ruby modules (aka Rails concerns for our use case). So, naturally, to handle delivery of the notifications I’ve set up a concern that handles the delivery. Here’s the basic idea of the Notification::Delivery concern:

# app/models/notification/delivery.rb
module Notification::Delivery

  extend ActiveSupport::Concern

  included do
    # locking flag to determine if this notification is being delivered
    kredis_flag :delivery_in_progress

    # as soon as the record writes to the database, enqueue the delivery job
    after_create_commit :queue_notification_delivery
  end

  def deliver!
    # don't send the same notification twice
    return false if delivered?
    
    # prevent this method from running more than once at the same time
    return false if delivery_in_progress.marked?

    # set the locking flag
    delivery_in_progress.mark(expires_in: 15.minutes, force: false)

    begin
      # send out the notification on each desired channel
      send_web_notification!
      send_email_notification!
      send_sms_notification!

      # successful delivery!
      self.status = :delivered
      self.delivered_at = Time.current

      save!
    rescue StandardError => e
      logger.error("Error delivering notification #{ id }: #{ e.message }".red)

      retry_notification_delivery
    ensure
      # always ensure the record lock is removed after 
      # the process runs, successfully or not
      delivery_in_progress.remove
    end

    true
  end

  private

    # wait 30 seconds, and try again on failure
    def retry_notification_delivery
      NotificationDeliveryJob.set(wait: 30.seconds).perform_later(self)
    end

    # delivery job calls #deliver! in the background
    # 
    # this job is enqueued after the record is created
    def queue_notification_delivery
      if persisted?
        NotificationDeliveryJob.perform_later(self)
      end
    end

end

The concern has a method which we’ll use to enqueue a background job to send emails for this notification. Let’s fill that in with a new background job. First, I’ll generate the new job:

rails g job NotificationDelivery

Lately I’ve really gravitated towards simple jobs that rely on methods in a model to do the ‘real’ work. So let’s keep that job extremely simple and set it up to just send the notification’s deliveries:

class NotificationDeliveryJob < ApplicationJob

  queue_as :default
  
  def perform(notification)
    unless notification.delivered?
      notification.deliver!
    end
  end

end

The job just loads a Notification record, and if it’s not already delivered, sends out the deliveries.

I’m also using a primitive ‘locking’ flag here, using the handy Kredis gem. Kredis is a usability wrapper around Redis storage that has a cleaner syntax than interfacing with Redis directly for some use cases. In this case I’m using a kredis_flag to mark when we’re currently running a notification delivery, just so that two of the same notification won’t ever be sent at the same time, causing a duplicate notification email to go out to a user.

Before we move on, don’t forget to add the concern into the notification model:

class Notification < ApplicationRecord
  # ...
  
  include Delivery
  
  # ...
end

Delivering via Email

Now that the the core delivery mechanisms are set up and in the model, we’ll work on actually delivering the email message itself. Inside of our Delivery concern we have a few methods that we haven’t defined yet, including send_email_notification! which does just what it sounds like.

Let’s wire up our email delivery channel with another concern just for the email details:

# app/models/notification/email.rb

module Notification::Email

  extend ActiveSupport::Concern

  def email_subject
    I18n.t("notifications.#{ action }.subject", default: "New #{ action.to_s.titleize } Notification")
  end

  def email_to
    user.email
  end

  private

    def send_email_notification!
      # ensure this user wants to receive email notifications
      return false unless user.email_notifications?

      # already delivered, don't send it again
      return false if delivered_email?

      # no email address, don't send
      return false unless email_to.present?

      # not persisted record, can't send
      return false unless persisted?
      
      # actually send the email via a Rails Mailer
      NotificationMailer.delivery(self).deliver_now

      # once the mailing operation completes, mark the email notification as delivered 
      update_column(:delivered_email, true)

      true
    end

end

The send_email_notification! is a private method, because we only want this notification class to call it directly, not elsewhere in the app. There are a few failsafe methods in here to ensure emails are ready to send and have not already been sent to a user.

Then we use a basic Rails ActionMailer class called NotificationMailer to do the normal work of sending an email.

To send the email, we’ll generate a new Rails mailer and fill in the email details:

rails g mailer Notification delivery

# app/mailers/notification_mailer.rb
class NotificationMailer < ApplicationMailer

  def delivery(notification)
    @notification = notification

    mail(
      to: notification.email_to,
      subject: notification.email_subject
    )
  end

end

In this case, I’m also defining the subject line dynamically using Rails internationalization features and our action column above for the key to differentiate emails.

I’m skipping the part here where I fill in the body of the email message, because that is really app-specific and you’ll likely want to design what that looks like.

Delivering via SMS

As a second channel, I’m going to use SMS deliveries as well.

In reality, we probably wouldn’t want to send every notification from an app via SMS, so I'm using an sms_eligible_action? method to determine which notification actions are relevant for this use case.

Following our usual pattern, let’s create another concern for the SMS delivery:

# app/models/notification/web.rb
module Notification::SMS

  extend ActiveSupport::Concern

  def sms_content
    I18n.t("notifications.#{ action }.sms_content", default: nil)
  end
  
  def sms_eligible_action?
    %w( appointment_created appointment_canceled ).include?(action)
  end

  def sms_to
    user.sms_phone_number
  end

  private

    def send_sms_notification!
      # ensure this user wants to receive sms notifications
      return false unless user.sms_notifications?
      
      # if this isn't an action we want sending via SMS, don't bother
      return false unless sms_eligible_action?

      # already delivered, don't send it again
      return false if delivered_sms?

      # no sms phone number, don't send
      return false unless sms_to.present?
      
      # no content for this SMS message, don't send
      return false unless sms_content.present?

      # not persisted record, can't send
      return false unless persisted?

      # Send this notification via Twilio or your SMS provider of choice here
      TwilioClient.new(
        to: sms_to, 
        content: sms_content
      ).deliver_now

      # mark the SMS as delivered
      update_columns(delivered_sms: true)

      true
    end

end

Delivering to the Inbox

For our last delivery ‘channel’ we want to send the notification to the user’s inbox on the application’s website. This delivery mechanism is a bit different than the others since we’re not really ‘sending’ anything out directly.

The web delivery just flips the delivered_web boolean flag and streams the notification to the top of the user’s inbox via Turbo streams. I’m skipping some unimportant bits here, but this concern contains the basics:

# app/models/notification/web.rb
module Notification::Web

  extend ActiveSupport::Concern

  def web_description
    I18n.t("notifications.#{ action }.web_description", default: action.to_s.titleize)
  end

  def web_title
    email_title
  end

  private

    # "delivering" a notification to the web just pushes a new 
    # notification partial to the top of our inbox view 
    # using Turbo streams.
    # 
    # Once a notification is sent to the inbox, we mark
    # it as unread and flip the boolean column to display the record
    def send_web_notification!
      return false if delivered_web?
            
      # use turbo streams to prepend the partial to the top of a 
      # <div id="inbox"></div> element 
      Turbo::StreamsChannel.broadcast_prepend_to(
        user,
        target: "inbox",
        partial: "notifications/notification",
        locals: {
          notification: self
        }
      )
            
      # mark the web delivery as 'sent' and the notification as unread
      update_columns(
        delivered_web: true,
        read_at: nil
      )

      true
    end

end

And don’t forget to include all of our new delivery concerns in the Notification root model:

class Notification < ApplicationRecord
  # ...
  
  include Delivery
  include Email
  include Sms
  include Web
  
  # ...
end

User Notification Settings

Last but not least, we need to allow an application user the ability to opt in or out of notifications on each delivery channel. I’m using simple booleans for this use case, but this could certainly be more granular to support more complicated use cases. Here is my migration for adding notification settings to the user:

class AddNotificationSettingsToUsers < ActiveRecord::Migration[8.0]

  def change
    # does this user want to receive notifications via email
    add_column :users, :email_notifications, :boolean, default: true
    
    # does this user want to receive notifications via SMS
    add_column :users, :sms_notifications, :boolean, default: false
    
    # In reality I'm storing this with the country code and number, 
    # but simplifying it here
    add_column :users, :sms_phone_number, :string
  end

end

We’re almost there! For the last step, I’m adding another concern that will handle our notifications sending with a simple syntax to use throughout the application:

# app/models/user/notifications.rb
module User::Notifications

  extend ActiveSupport::Concern

  included do
    has_many :notifications, dependent: :destroy
  end

  def notify(action, related: nil, record: nil, **options, &block)
    notification = Notification.new(
      user: self,
      action:,
      record:
    )

    if block_given?
      yield notification
    end

    notification.save!
    notification
  end

end

Then include the new concern in our User model:

# app/models/user.rb
class User < ApplicationRecord
  # ...
  
  include Notifications
  
  # ...
end

Once that is all set up, we have a basic working notifications system. Here’s how I create a new notification:

Current.user.notify(:appointment_created, record: @appointment)

I find this syntax very readable and helpful to understand what’s happening. We don’t even have to discuss what this app does to understand that we’re notifying the currently signed-in user that a new appointment has been created. That appointment record is also saved in the notifications table with a polymorphic association back to the Appointment model itself.

That’s it! Multi-channel notifications, the capability for a web inbox, and the easy ability to add more channels down the road.

Note: I’ve skipped a bunch of unnecessary details here for the purposes of focusing on the core functionality. This isn’t designed to be a fully complete design, but a working prototype and thought process of how notifications could work.