Cody Norman Personal Website

Create PDF attachments from email with Action Mailbox

2024-07-14T17:54:46-04:00

Today, I’m going to show you how to save a PDF attachment from an inbound email using Action Mailbox a Ruby on Rails application. I think this is a great example of a common feature that we can accomplish with email. This is going to allow your users to perform tasks without even having to open your app.

I’ll cover how to handle edge cases like checking for a valid user and handling missing or incorrect attachments.

This post will cover creating a new Rails app and adding Devise for a User model to check against the sender of the email. Since this will be a new app, I’ll also be installing Action Mailbox. Everything after that initial setup should apply to an existing app you’re trying to add this feature to.

If you’ll be adding this feature to an existing app, you can skip over most of that setup.

There’s also a video version of this post with some more detail.

Create your Rails app with Devise

Let’s start by creating a new Rails app and installing Devise for the User model.

$ rails new pdf_attachments_action_mailbox

Once the new app is created, move into the directory that was created and open the project in your code editor to add the Devise gem.

# Gemfile gem 'devise' 

Once Devise is added to the Gemfile you can bundle install and run the Devise install generators.

$ bundle install $ rails generate devise:install 

After running the Devise install generator, you’ll see some output that mentions some in your code editor changes to the views and routes. To keep things simple, I’ll be skipping the User views and routes to keep things focused on Action Mailbox.

Since we’ll be sending outbound emails to the sender to update them on the status on the import, there is one change we need to add from Devise.

Open the config/environments/development.rb file and add the following line to the configuration:

config.action_mailer.default_url_options = { host: 'localhost', port: 3000 } 

With Devise installed, we can now generate the User model.

$ bin/rails generate devise User $ bin/rails db:migrate

Since this app will be BYOV (Bring Your Own Views - I realize spelling it out doesn’t really save time but I think it’s neat), we can create a User in our Rails console to test with.

irb> user = User.create(email: 'user@actionmailbox.pro', password: 'youvegotmail') 

Next, we’ll create a simple model to store the PDF attachments using Active Storage.

$ bin/rails g model ImportDocument user:references name:string

This creates a new model ImportDocument that belongs to a User and has a name value. name will store the subject of the email to make it easier to reference the import.

Installing Action Mailbox

If you haven’t already done so, you’ll also need to install Action Mailbox.

$ bin/rails action_mailbox:install

One final change to make before running the migrations is to add the has_one_attached method to the ImportDocument model.

# app/models/import_document.rb class ImportDocument < ApplicationRecord belongs_to :user has_one_attached :pdf end 

Now, running the migrations will create the tables for the ImportDocument model and the tables needed for Action Mailbox, which includes Active Storage.

$ bin/rails db:migrate

This is all the setup we need to do to get started with the Action Mailbox side of things.

Sidenote: I’ve found that keeping your mailboxes small and focused on a single task helps keep things organized. This mailbox will be responsible for saving the PDF attachment from the email. If you decide to add different attachment types to the ImportDocument model, you could create a new mailbox for each type.

To get started, we can create a new Mailbox to handle the inbound emails and save the PDF.

$ bin/rails generate mailbox Pdf

Routing the email

Before processing the inbound email, we first need to route the email to the correct mailbox.

# app/mailboxes/application_mailbox.rb class ApplicationMailbox # routing /pdf/i => :pdf routing all: :pdf end 

I’ve included a commented-out line that gives a better idea of how you may want to route this email outside of your development environment. This example would route emails that contain pdf in the to address of the inbound email. In other words, sending an email to pdf@inbound.yousite.com or pdf-import@inbound,yoursite.com would route the email to the pdf mailbox.

When working on a new mailbox in development, I typically use the all: option to route any inbound email to the specified mailbox. This rules out any potential routing issues and lets you focus on the processing in the mailbox.

To confirm everything is working, we can send an email through the Rails Conductor and confirm it’s been delivered.

With your Rails server running, open the Rails Conductor by visiting

http://localhost:3000/rails/conductor/action_mailbox/inbound_emails

and click the ‘New inbound email by form’ option or head there directly by going to

http://localhost:3000/rails/conductor/action_mailbox/inbound_emails/new

Since we’re using the all: routing option, we don’t have to worry about the correct address to send the email to. Just fill in the ‘to’ and ‘from’ fields and submit the form.

After submitting the form, you’ll land on the detail page for the ActionMailbox::InboundEmail record that was created from the form. Refresh the page and you should see the status change from processing to delivered. This means the email was successfully processed by the PdfMailbox and everything is working as expected.

Re-routing and Debugging

If something went wrong and the status didn’t update to delivered, the Rails conductor provides an easy button to re-route and deliver the email again.

I’m also going to add a debugger statement using ruby debug to the process method of the PdfMailbox to show how you can inspect the inbound email and attachments or investigate any issues.

# app/mailboxes/pdf_mailbox.rb class PdfMailbox < ApplicationMailbox def process debugger end end 

After adding the debugger statement, restart your Rails server and click the ‘Route again’ button on the Inbound Email detail page.

Note: Since this app is only running with rails server and not using a Procfile, you’ll see the debugger open in the terminal where the server is running. If you’re using a Procfile and with something like Overmind, you can connect to the debugger with overmind connect web or overmind connect worker depending on your specific setup.

In the above example, I’m interacting with the Ruby Mail gem to parse information from the inbound email.

Since we’re fully embracing the BYOV philosophy, you can also use the Rails console to accomplish the same task.

Inside the Rails console, you can get the last ActionMailbox::InboundEmail record, update the status to pending, and then route the email to the PdfMailbox.

# In the Rails Console inbound_email = ActionMailbox::InboundEmail.last inbound_email.pending! inbound_email.route 

If your debugger statement is still in the process method of the PdfMailbox, you’ll see the debugger open in the terminal where the Rails console is running.

The Happy Path

To get things working initially, I’ll be assuming the mailbox will receive an inbound email with all the requirements. For now, it’s just going to be attached to the first User and focus on creating the Active Storage attachment.

In the later steps, we’ll add some error handling to handle edge cases and reply with emails alerting the sender of the import status.

Before getting started, if you’ve not already done so, be sure to remove the debugger statement from earlier.

Inside the process method of the PdfMailbox, we start by initializing a new ImportDocument record and setting the user_id to the id of the first User record.

For this to work, you’ll need to have a User record in your database (snippet for that above). After setting the user, we’ll set the name to the subject of the email.

# app/mailboxes/pdf_mailbox.rb def process import_document = ImportDocument.new( user_id: User.first.id, name: mail.subject ) 

After initializing the ImportDocument, we’ll attach the PDF file from the inbound email to the pdf Active Storage attachment.

# app/mailboxes/pdf_mailbox.rb def process import_document = ImportDocument.new( user_id: User.first.id, name: mail.subject ) import_document.pdf.attach( io: StringIO.new(mail.attachments.first.body.decoded), filename: mail.attachments.first.filename ) end 

This code is also assuming your inbound email has a PDF attachment. We’ll worry about the file type in a later step.

The final step in the happy path is to save the ImportDocument record.

# app/mailboxes/pdf_mailbox.rb def process import_document = ImportDocument.new( user_id: User.first.id, name: mail.subject ) import_document.pdf.attach( io: StringIO.new(mail.attachments.first.body.decoded), filename: mail.attachments.first.filename ) end import_document.save! 

If you submit an email through the Rails Conductor with all the required fields, including the PDF attachment, that should create a new ImportDocument record with the PDF attachment from the inbound email.

To confirm the ImportDocument was created with the correct attachment, you can check for the attachment in the Rails console.

import_document = ImportDocument.last import_document.pdf.attached? 

If the email is showing as delivered and import_document.pdf.attached? returns true, everything should have been saved correctly.

Checking for an existing User

Anything connected to the internet is only going to last a few days before it starts receiving inbound spam. It’s probably a safe assumption that you may not want to try to create a new Import Document from some spammers email signature.

To prevent this, we can check if a User record exists for the sender of the email. If the User is found, we move on to processing the email. If the User is not found, we’ll mark the email as bounced and send a reply to the sender.

Action Mailbox provides a simple way to handle this. We’ll use the before_processing callback to check for the User and the bounce_with method to mark the email as bounced. The bounce_with method takes a mailer as an argument and uses that as the email to alert the sender of the bounce.

# app/mailboxes/pdf_mailbox.rb class PdfMailbox < ApplicationMailbox before_processing :ensure_user def process import_document = ImportDocument.new( user_id: User.first.id, name: mail.subject ) import_document.pdf.attach( io: StringIO.new(mail.attachments.first.body.decoded), filename: mail.attachments.first.filename ) import_document.save! end private def ensure_user user = User.find_by(email: mail.from.first) unless user # bounce_with  end end end 

Inside the ensure_user method, we’ll check if a User record exists for the email address of the sender. If a User is not found, we’ll use the bounce_with method to mark the email as bounced and send a reply.

Since the bounce_with method requires a mailer, you’ll need to generate a new mailer to respond with. There will be more mailers used in the later steps so we can create them all at once.

Generate Mailers

$ bin/rails generate mailer Pdf user_not_found missing_attachment bad_attachment_format import_complete 

This will generate a new mailer with the methods user_not_found, missing_attachment, bad_attachment_format, and import_complete.

I won’t be updating any of the mailer views, but there are some changes to make to each one of the methods in the PdfMailer.

# app/mailers/pdf_mailer.rb def user_not_found @greeting = "User Not Found" @to = params[:to] mail to: @to end 

Updating @greeting is optional, but you will need to update the value passed to mail to: to use the to value from the params hash. This is how we’re going to pass the email address of the sender to the mailer.

Bonus Step: Install letter_opener_web to view the outbound emails easily in your browser. There’s more detailed information on how to set that up in the included video.

With our mailers updated, we can now finishing implementing the bounce_with method.

# app/mailboxes/pdf_mailbox.rb def ensure_user user = User.find_by(email: mail.from.first) unless user bounce_with PdfMailer.with(to: mail.from.first).user_not_found end end 

In this example, PdfMailer is the mailer we generated earlier. The with method is used to pass params to the mailer.

We’re using mail.from.first to get the first email address (the same one we used to find the User record) and passing that as the to value to the mailer.

The last part, user_not_found, is the mailer method we’re going to be sending.

If you re-start your Rails server and send an email from an email address that does not match a User in your local database, you should see the email marked as bounced and a reply sent to the sender.

Now, your Action Mailbox app is a bit more secure from the scary internet and won’t be trying to process documents and attachments all willy-nilly.

Another one of the assumptions from the previous step is that the inbound email has at least one attachment.

In the next step, I show how you can add a check for an attachment and reply to the sender if one is missing.

Checking for an attachment

To check for an attachment before attempting to process the email, we’ll be using another before_processing callback. This time, we’ll be checking if the email has at least one attachment.

This portion won’t be checking that it’s a PDF file, just that there is an attachment. Letting the sender know they may have forgotten to attach the file provides a better experience than getting a more generic error.

# app/mailboxes/pdf_mailbox.rb before_processing :ensure_attachment def ensure_attachment if mail.attachments.empty? # repy to sender end end 

Now, we need to send a reply to the sender and make sure we don’t attempt to process the email. The main difference between this and the bounce_with method is that the bounce_with updates the status of the ActionMailbox::InboundEmail record to bounced instead of something like failed or delivered.

In this scenario, the sender was a valid User sending to the correct email address so I don’t think bounced is a good representation of the inbound email’s status.

If you’ve followed the steps above for generating the mailers, you should have a missing_attachment method in the PdfMailer that we can use to reply to the sender.

 def ensure_attachment if mail.attachments.empty? PdfMailer.with(to: mail.from.first).missing_attachment.deliver_later end end 

This mailer is setup and called the same way as the one passed to bounce_with except for adding deliver_later to send the email asynchronously.

Our final step is to call :abort to stop the email from being processed.

 def ensure_attachment if mail.attachments.empty? PdfMailer.with(to: mail.from.first).missing_attachment.deliver_later :abort end end 

This ensures that we exit and don’t attempt to process the email if there are no attachments.

To test this out, you can send a test email through the Rails Conductor and confirm the reply email was sent and the status was updated to failed.

Checking the attachment type

Now we’ve confirmed the inbound email has at least one attachment, another additional check we can add is to confirm the attachment is a PDF file.

# app/mailboxes/pdf_mailbox.rb before_processing :ensure_attachment_format def ensure_attachment_format unless mail.attachments.first.content_type.start_with?("application/pdf") # send email and exit end end 

For this approach, we’ll be using another before_processing callback to check the content type of the attachment.

Note: Outside of the scope of a tutorial, you may want to combine or refactor some of the callbacks to suit your needs. I wanted to keep them separate to show easy ways we can add incremental improvements and refinements to the mailbox.

Inside the ensure_attachment_format method, we’ll check if the content type of the first attachment starts with application/pdf. If it doesn’t, we’ll send a reply and exit before processing.

Since you’re an old pro at these types of checks and callbacks by now, we can re-use the same approach used in the ensure_attachment callback to send a reply to the sender and exit.

 def ensure_attachment_format unless mail.attachments.first.content_type.start_with?("application/pdf") PdfMailer.with(to: mail.from.first).bad_attachment_format.deliver_later :abort end end 

Reply on success

We have a couple of different emails alerting the sender of issues, but what about when things go right?

It’d be nice to let the sender know when the import has been completed.

# app/mailboxes/pdf_mailbox.rb def process import_document = ImportDocument.new( user_id: User.first.id, name: mail.subject ) import_document.pdf.attach( io: StringIO.new(mail.attachments.first.body.decoded), filename: mail.attachments.first.filename ) if import_document.save! PdfMailer.with(to: mail.from.first).import_complete.deliver_later end end 

Now, if the ImportDocument is saved successfully, we’ll send an email to the sender with the import_complete mailer method.

Like the previous step, you can confirm this is working by sending some test emails in the Rails Conductor and confirm the new record was created and the correct email was sent.

Wrapping up

Inside our PdfMailbox, we’ve moved the task of uploading and processing files to email. We’ve also added some error handling and UX improvements to let the sender know if something went wrong or when their import is complete.

As an additional perk, creating and processing the attachments via email with Action Mailbox will run in the background whenever the ActionMailbox::InboundEmail is processed. This is a great way to handle large files without tying up your web server.

The included video is a free preview from my upcoming course on Action Mailbox covering more of these advanced topics and edge cases. If you’d like to learn how to create more features like this one, the course is available for pre-sale - Action Mailbox Pro.

Create a QR Code with a Logo

2024-06-09T17:54:46-04:00

QR codes are a great way to share links or information easily with your users, unless you’re a restaurant, in which case you should really consider a paper menu please.

In all seriousness, it’s a great way to easily let people scan and access specific information.

To say QR codes are a dime a dozen would be an understatement. Creating a composite QR code with a logo is a great way to help your code stand out and add some additional branding and feel to your app.

Being able to generate a custom QR code overlaid with a logo, while still being scannable is pretty easy with Rails.

This post will walk through setting up a simple standalone QR with logo app.

We’ll be using MiniMagick and RQRCode to create a PNG of the qr code, then create a composite image with the logo.

If you’d like to see everything in action, I have a video that goes through things in a little more detail

Getting started

The app is going to have a single model QRCode.

It will have a string field for the URL and 3 attached active storage images.

3 might be a bit overkill but this will store the logo uploaded by a user, the QR code without the logo and finally the combined QR code image with the logo.

Create a new Rails app with Tailwind by running the following command in your terminal.

rails new qr_code_generator --css=tailwind

We’ll keep things simple by scaffolding the QrCode resources

bin/rails generate scaffold QrCode url:string

Since this is a simple app, we’ll set the root route to the QrCode index page.

 # config/routes.rb root "qr_codes#index" 

Active Storage and Image Processing

With a simple model for the QR code, the next step is to add the image processing gem and install active storage for the images that will be attached.

If you look in the Gemfile, you should already see the image_processing gem in your Gemfile

# Use Active Storage variants [https://guides.rubyonrails.org/active_storage_overview.html#transforming-images] # gem "image_processing", "~> 1.2" 

You can uncomment the gem and run bundle install

With the image processing gem installed and ready to go, the next step is to install Active Storage and run the corresponding migrations.

bin/rails active_storage:install bin/rails db:migrate

With Active Storage installed, we can add our attachments we’ll be using.

app/models/qr_code.rb

class QrCode < ApplicationRecord has_one_attached :logo has_one_attached :original_image has_one_attached :combined_image end 

We’ll be generating the combined_image and the original_image based on inputs from the user, including a logo file.

Updating the form and adding the file attributes to the params in the controller will allow us to start storing the uploaded logo and URL attached to the QR code.

Add the file input for the logo to the form.

I’m also limiting the file type to PNG for simplicity. Or QR codes are going to be PNGs, so it makes sense to limit the logo to the same format. Accepting PNGs with transparent backgrounds also makes it easier to overlay the logo on the QR code after some processing.

This is by no means a foolproof way to ensure the file is a PNG, but it’s a good start. If you find yourself needing more, you can look into validating the file type in the model before saving.

app/views/qr_codes/_form.html.erb

 <div class="my-5"> <%= form.label :logo %> <%= form.file_field :logo, accept: "image/png" %> </div> 

Add logo to the strong params in the controller.

app/controllers/qr_codes_controller.rb

 def qr_code_params params.require(:qr_code).permit(:url, :logo) end 

Adding the logo to the show page will give us an easy way to reference the image we uploaded.

app/views/qr_codes/_qr_code.html.erb

<div id="<%= dom_id qr_code %>"> <p class="my-5"> <strong class="block font-medium mb-1">Url:</strong> <%= qr_code.url %> <%= image_tag qr_code.combined_image %> </p> </div> 

If you haven’t started the server yet, now would be a good time to start everything up and make sure it’s working.

If things are good to go, you should land directly on the QrCode index page.

Clicking the New QR Code button, filling out the URL, and uploading a logo should create a new QR code record with the URL and logo attached.

QR codes.

We’ll be using the rqrcode gem to generate QR codes as a PNG and saving as an Active Storage attachment.

Add it to the Gemfile with::

gem "rqrcode", "~> 2.0" 

and install the gem with bundle install

To keep a lot of the image processing logic out of the controller, we’ll create a method on the model to generate the QR code and save it as an attachment.

app/models/qr_code.rb

 def generate_qr_code! qr = RQRCode::QRCode.new(url) original_qr = qr.as_png(size: 400, bit_depth: 1, border_modules: 4, color_mode: ChunkyPNG::COLOR_GRAYSCALE, color: "black", file: nil, fill: "white") original_image.attach(io: StringIO.new(original_qr.to_s), filename: "original_qr.png", content_type: "image/png") save! end 

This method will generate a QR code based on the URL and save it as an attachment.

Another advantage of having the QR code generation on the model is that we can test and diagnose issues in our Rails console without needing to go through the controller.

Running qr_code.generate_qr_code! in the console (or anywhere) should generate a QR code from the URL and save it as an attachment.

Calling this method after we’ve successfully saved the QrCode record will create the QR code and save it as an attachment.

app/controllers/qr_codes_controller.rb

 def create @qr_code = QrCode.new(qr_code_params) respond_to do |format| if @qr_code.save @qr_code.generate_qr_code! format.html { redirect_to qr_code_url(@qr_code), notice: "Qr code was successfully created." } format.json { render :show, status: :created, location: @qr_code } else format.html { render :new, status: :unprocessable_entity } format.json { render json: @qr_code.errors, status: :unprocessable_entity } end end end 

So we can make sure the image was created an attached, we can display it on the details page.

<%= image_tag qr_code.original_image %>

app/views/qr_codes/_qr_code.html.erb

<div id="<%= dom_id qr_code %>"> <p class="my-5"> <strong class="block font-medium mb-1">Url:</strong> <%= qr_code.url %> <%= image_tag qr_code.logo %> <%= image_tag qr_code.original_image %> </p> </div> 

If everything is working as expected, you should see the QR code image on the show page for the QR code record. To check to make sure everything is working as expected, you can call generate_qr_code! on an existing record in the Rails console or create a new record through the form. (Screenshot of the QR code on the show page - Use real URLs)

Going Further

Adding a bit of flair to things, we’re ready to start combining the uploaded logo, this will be the combined_image attachment.

At this point, there are 2 attached image to the QR code model, original_image and logo.

We’re now going to use MiniMagick to do a bit of formatting and create a composite image.

The combined logo will be using the same approach as the original QR code, meaning this code will be added to a method in the QrCode model.

To start, we create a MiniMagick::Image for the logo and original_image qr code.

Before attempting to combine the images, we’ll need to do some processing on the logo image. This will include resizing the image and adding a white background to make the logo stand out from the QR code.

Since we’re going to be doing some image processing, we’ll need to require the mini_magick gem in the QrCode model.

First, we create a MiniMagick::Image object for the logo image.

logo_image = MiniMagick::Image.open(logo) 

Then we do the same for the QR code image.

qr_code_image = MiniMagick::Image.open(original_image) 

Next, we’ll resize the logo image and add a white background to help the logo stand out.

updated_logo_image = ImageProcessing::MiniMagick.source(logo_image) .resize_and_pad(100, 100, background: "white").call 

After creating the updated logo image, we can create a composite image with the QR code and logo.

composite_qr_code = qr_code_image.composite(updated_logo_image) do |c| c.compose "Over" c.gravity "center" c.colorspace "sRGB" end 

The composite method is used to overlay the updated logo image on top of the QR code image. The compose option is set to “Over” to overlay the logo on top of the QR code. The gravity option is set to “center” to center the logo on the QR code. The colorspace option is set to “sRGB” to ensure the colors are displayed correctly.

Finally, we’ll attach the composite image to the combined_image attachment.

qr_code.combined_image.attach(filename: "combined_qr_code.png", io: File.open(composite_qr_code), content_type: "image/png") 

Then create the composite image and stores it as an Active Storage attachment.

Here’s what the final method looks like in the QrCode model.

 def generate_combined_image! logo_image = MiniMagick::Image.open(logo) qr_code_image = MiniMagick::Image.open(original_image) updated_logo_image = ImageProcessing::MiniMagick.source(logo_image).resize_and_pad(100, 100, background: "white").call composite_qr_code = qr_code_image.composite(updated_logo_image) do |c| c.compose "Over" c.gravity "center" c.colorspace "sRGB" end combined_image.attach(filename: "combined_qr_code.png", io: File.open(composite_qr_code.path), content_type: "image/png") save! end 

If you’d like to break this down into smaller steps, you can call each method individually in the Rails console. Here’s an example of how you could call each method individually in the Rails console to create the composite image and save it as an attachment.

# in the Rails console require "mini_magick" qr_code = QrCode.last logo_image = MiniMagick::Image.open(qr_code.logo) qr_code_image = MiniMagick::Image.open(qr_code.original_image) updated_logo_image = ImageProcessing::MiniMagick.source(logo_image) .resize_and_pad(100, 100, background: "white").call composite_qr_code = qr_code_image.composite(updated_logo_image) do |c| c.compose "Over" c.gravity "center" c.colorspace "sRGB" end qr_code.combined_image.attach(filename: "combined_qr_code.png", io: File.open(composite_qr_code.path), content_type: "image/png") qr_code.save! 

In the same way we called generate_qr_code! after saving the record, we can call generate_combined_image! to create the composite image with the logo from the Rails console on an existing record that has a logo and QR code attached.

The last step is to call the generate_combined_image! method after the QR code has been generated and saved.

app/controllers/qr_codes_controller.rb

 def create @qr_code = QrCode.new(qr_code_params) respond_to do |format| if @qr_code.save @qr_code.generate_qr_code! @qr_code.generate_combined_image! format.html { redirect_to qr_code_url(@qr_code), notice: "Qr code was successfully created." } format.json { render :show, status: :created, location: @qr_code } else format.html { render :new, status: :unprocessable_entity } format.json { render json: @qr_code.errors, status: :unprocessable_entity } end end end 

We’ll also include this in the update action so that the combined image is updated whenever the QR code is updated.

 def update respond_to do |format| if @qr_code.update(qr_code_params) @qr_code.generate_qr_code! @qr_code.generate_combined_image! format.html { redirect_to qr_code_url(@qr_code), notice: "Qr code was successfully updated." } format.json { render :show, status: :ok, location: @qr_code } else format.html { render :edit, status: :unprocessable_entity } format.json { render json: @qr_code.errors, status: :unprocessable_entity } end end end 

Display the combined image on the show page for the QR code record to see the final result.

<%= image_tag qr_code.combined_image %>

app/views/qr_codes/_qr_code.html.erb

<div id="<%= dom_id qr_code %>"> <p class="my-5"> <strong class="block font-medium mb-1">Url:</strong> <%= qr_code.url %> <%= image_tag qr_code.logo %> <%= image_tag qr_code.original_image %> <%= image_tag qr_code.combined_image %> </p> </div> 

If all goes as planned, you should be re-directed to the show page for the newly created QR Code record and see if all the logos are correct.

And with that, you’ve created a simple tool too add some style and flair to your QR codes.

This is a pretty simple example and there are a lot of ways to improve and expand on this feature. You could add more options for the QR code generation, add more image processing options, or even add a background color to the QR code for some additional flair.

You can view the full code for this example on GitHub.

The Road To Rails Conf 2024

2024-06-01T17:54:46-04:00

The Road To Rails Conf

Last month, I had a chance to give my first conference talk at what turned out to be the penultimate Rails Conf.

Sometime early last year, I decided I was going to start working on doing more public speaking and had the goal of being accepted to speak at a conference.

I put a lot of work into my first proposal but wasn’t selected. Honestly, that may have been for the best.

I don’t consider myself a sore loser. If I didn’t get picked or make the cut for something, it’s because I didn’t do a good enough job, plain and simple. That doesn’t mean I’m happy about it. I guess a good way to put this is I’m fine with losing, but I absolutely hate the feeling, especially when it’s something I’ve set my mind to.

Getting that first stinging rejection let me know I had to step my game up. I started reading any article I could find on preparing a good conference proposal. Here are some of the resources that were a big help for me.

Conference Proposal Resources

Rails Conf 2013 How to Talk to Developers by Ben Orenstein

Kevin Murphy - Building Conference Talk Content

Sarah Mei - What Your Conference Proposal Is Missing

Noel Rappin - Conference Prompts: Or How To Submit Proposals and Influence People

Another great resource I found was Speakerline.io from Nadia Odunayo

What does a good proposal even look like?

During Rafael Franca’s keynote at Rails Conf 2023 he mentioned one way he started getting more comfortable with contributing to Rails was that he started reading over every single new commit.

I loved this and decided to try something similar with conference proposals. I read over every single Ruby proposal at least once, some of them multiple times. I started to get a much better idea of what a good (and accepted) proposal looks like.

To round out my newfound knowledge of the proposal process, I also attended my first proposal coaching session courtesy of the fine folks at Ruby Central. It was a great chance to get feedback my ideas and proposals while also seeing what others were working on.

So…after reading dozens of proposals, getting some coaching on my specific proposals and submitting them to the next conference…

More rejections.

Down but not out

After a long year, I began wondering if I should put my talk ambitions on the back-burner and focus on other areas. I had some time to rest up and lick my wounds over the holidays and after a bit of recharging, decided I wasn’t done yet and was going to come out swinging in 2024.

Sometime around January or February of this year, I started compiling a list of all the ruby conferences I could potentially submit to along with the Call For Proposal dates.

I started writing some blog posts around some of my potential proposal topics. This was a big win because the blog content made it much easier to pull info an ideas from to include in the proposal. It also allowed me to get feedback on what parts people thought were the most valuable.

I decided to go all in on what I thought was my strongest proposal and reached out to Boulder Ruby to speak on that topic.

My thinking was…If I don’t get accepted, having a chance to get some more feedback would improve my chances in the future.

If I did get accepted, I’d already be committed to having an early version done about 6 weeks before Rails Conf.

Hearing the theme of this year’s Rails Conf was ‘building with Rails’ I had some ideas for a talk on Action Mailbox that I thought would be a great fit. I thought this was my strongest proposal and represented my best chance of being accepted.

Thursday 2/29 @ 2:03 PM (I saved the email) I finally got my breakthrough.

“Wait, What?!….”

I had to squint and re-read the email a couple times but there it was. The acceptance email I’ve been on the hunt for so long.

Knocking the dust off

I took the rest of the week to take a bit of a victory lap and enjoy hitting such a big personal milestone.

A funny line I added to my planning notes that Saturday (March 2)

“What’s the Rocky IV equivalent for preparing for a talk?”

For those unaware, Rocky IV has the best training montage in existence. I will not be taking further questions.

I didn’t think I’d be able to realistically pull that off, but thinking about what that would look like, gave me some good ideas to think about for prep.

When Monday rolled around, it was time to get to work.

I immediately picked up a couple of Audio Books on speaking and how to craft an engaging and entertaining presentation. I also thought that audiobooks might have the advantage of allowing me to hear the examples instead of just reading which I thought would be a big help.

Even though I had never given a conference talk, I thought that depending on books and recordings alone would be like reading a book on skydiving and thinking that’ll be enough to help me jump out of a plane.

In other words…practicing was where the majority of my focus should be. There’s absolutely no substitute for feeling more comfortable speaking in public than…you guessed it, speaking in public.

Philly.rb

March 12 - I was originally slated to speak at Philly.rb in April. I just so happened that their March meetup happened to be the day before I was already scheduled to speak at Boulder Ruby. After a bit of a scheduling mix up, I received a message asking me if I was still ready to present that night. Since I was almost done with the first version of my talk, I decided to just go for it. This would give me 2 chances to practice and get feedback with plenty of time for revisions and updates before the conference.

This was extra special for me since Philly.rb was the first meetup I ever spoke at and was the last meetup I spoke at in person back in 2016 before relocating to Colorado.

(Philly.rb 2016)

I felt like it went really well and was also lucky enough to get some great feedback and speaker coaching from Kevin Murphy who was on the program committee this year. After going over some of the things he’d tweak or change, we started riffing on a couple of ‘Big Swing’ ideas. That really set me off on the path to think about how I could do some fun things to make this talk very ‘me’.

Boulder Ruby

March 13 - That whole week I’d been tracking a potentially record-breaking blizzard that was due to hit us in Colorado right around the time I was supposed to speak at the Boulder Ruby meetup in person. My small mountain town is a little over an hour from Boulder under normal conditions and the last stretch requires me heading through a mountain road that’s pretty well known for people getting stranded on.

I don’t think I’ve ever prepped for heading to a meetup by throwing a sleeping bag and shovel into my car ahead of time but I suppose there’s a first time for everything. All indications were pointing to a rough drive home at a minimum with a reasonable possibility of being stranded and having to sleep in my car (this happens a lot in Colorado). I knew it would be risky but it also represented my only chance to speak in person to get some practice and feedback before Rails Conf.

I knew it would be a huge gamble, but if it paid off, I would have done 2 versions of my talk with tons of ideas for improvements and 6 weeks to go to Rails Conf.

With no exaggeration do I tell you I barely made it home. We ended up with about 30 inches total with one area I drove through on my way home getting 36 inches in a 24-hour period.

I can’t thank the organizers for both meetups enough and incredibly grateful for having me.

Here's a quick clip from one of the worst sections last night. Luckily I was only a couple cars back from the plow, probably passed a dozen cars stuck by this point. pic.twitter.com/pe8vHXa8uq
— Cody Norman (@cnorm35) March 14, 2024

Here are the slides from the Boulder and Philly Ruby meetups to give a better idea of what my first version looked like. You can compare them to the Rails Conf version to see how they evolved.

Attraction Mailbox Slides - Meetup Version

Big Swings

One of my big takeaways from the meetups was that people really enjoyed the examples. Seeing examples of some different tasks you can accomplish with Action Mailbox got people’s wheels turning about ways they could use it in their applications.

With a couple of rounds of feedback, I start working on some ‘practical’ examples you could easily add with Action Mailbox. Since I had a practical example section, I thought it would be fun to close out with an ‘impractical’ example section. This would be a handful of the weirdest, interesting but probably not useful things built with Action Mailbox. This seemed like a great way to inject some personality into my talk while throwing out a wide range of things you can do with an inbound email. I was hoping the broad range of ideas would help people walk away with their own ideas for features they could add to their app (and some they shouldn’t)

I probably have a whole post’s worth of material covering all the stuff that didn’t work or at least became too much to get working on time.

Seriously, the past month, my office has been littered with Hotwheels tracks, springs, button-pushers, mouse traps, skateboard wheels and more. I’m determined to get at least one of those working to include in any future talks.

There was just something about the idea of sending an inbound email that triggered stuff to happen in the real world that cracked me up.

One idea was to see if the after-market remote start device I had installed on my truck had an API available. The device uses LTE to stay connected and has a mobile app that allows you to monitor the status and perform different actions like lock/unlock and start the vehicle. My top idea soon became something along the lines of

“I wonder if I could send an inbound email to start my truck?”

Unfortunately, there wasn’t a public API I could find. However, I was fortunate enough to find someone who created an unofficial API wrapper with JS.

After skimming through the repo a bit, it seemed like it was possible and after getting a token, would be a pretty simple API request I could trigger in the mailbox.

Drone Mobile Node API

I had casually floated out this idea a couple of times over the past couple of months and got some chuckles but it was clear that it would be tough to convey just how goofy this is through slides. I knew I had to record some kind of video demoing this for people to really get it.

After a long string of failures earlier in the week, I was able to get things working and recorded the process on Friday afternoon, just a couple of days before traveling for Rails Conf.

On Saturday, I finished editing the video and added it to my slides. I could not stop laughing when I watched it and was so tempted to share it publicly but thought that if I was able to keep this under wraps and come out of nowhere with a video demo of starting a 2006 Tacoma with an inbound email and a lil’ bit of Rails code.

My talk was right before lunch and wanted to do something that people would feel like they just had to ask someone if they saw it or tell them what they just saw.

Go Time

This being the first time I spoke at a conference, I wasn’t sure what to expect. My talk was on the last day so I had a couple of days before I was up. One tip I kept hearing was

“Don’t let it weigh on you where you don’t enjoy the conference”

I tried to take that to heart and knew that I’d done everything I could do to prepare myself and there was nothing left but to do it.

The other thing I kept hearing was

“Are you nervous?”

I tried to answer every time with something like “I’m not nervous, I’m excited” which was very intentional. That wasn’t over-confidence, that was me trying to not even begin to internalize the idea of being nervous. I’d been endlessly visualizing giving a successful talk.

On the first day, I even popped up on the stage in the room I was going to be speaking in and took a picture of what it looked like from the podium. I would keep referring back to that picture over the next couple of days thinking about what it’s going to be like on stage.

By the time I got on stage, I was ready to go. If anything, I was anxious to get to the end to see how the truck email went.

Almost by some miracle, I kept the ending under wraps and was able to see people react to it for the first time in person. That’s absolutely something I’ll never forget and couldn’t think of a better closer.

After the talk was done and getting to see a room full of people react to it I decided to post a quick tweet with the video on my way back to the conference venue after stashing my bag at the hotel.

It was viewed over 10,000 times in less than two days.

That was wayyyyyyyy more than anything I expected and was glad to see people appreciated the whimsy and fun of it all.

If you’re interested in the slides from my Rails Conf talk, you can find them Attraction Mailbox Slides - Rails Conf Version

Next steps?

After getting some great feedback from the content in my talk, I’ve started work on a video course on Action Mailbox. Pre-sale is available now and the course is expected to be completed in August.

Action Mailbox Pro

If you’re interested in me speaking at your conference or meetup, please reach out!

Announcing Action Mailbox Pro

2024-04-01T17:54:46-04:00

I’m very excited to finally share some more information on a project I’ve been working on for the past couple of months.

Recently, I’ve published some articles on Action Mailbox and some of my experiences with it. I’ve also been fortunate enough to have the opportunity to speak about Action Mailbox at Rails Conf this year. I’ve also been able to speak in person on this topic at some meetups and got great feedback on what people are interested in.

Starting today, I’m opening a waitlist for an in-depth and hands-on course with Action Mailbox.

The perfect starting point for developers looking to incorporate email processing capabilities into their Rails applications. This practical, hands-on course will guide you through the fundamentals of Action Mailbox, a powerful framework for handling incoming email within a Ruby on Rails application.

ActionMailbox Pro

The hands-on sections will cover some real-world and practical use cases (maybe impractical too…)

Each section will include focused and short text and video lessons. The advanced sections and hands-on sections will be separate so you can skip or revisit the details as you need it.

I’m hoping to have the course completed sometime this summer. I should have a better idea of the dates after some sample videos and chapters are made available for feedback.

The idea is to record an intro lesson people can preview to make sure things like lighting, sound, screen resolution, etc are all in order before moving forward. I don’t want to record the whole course only to find out the sound is off or something else is wrong.

Join the waitlist now to get more information on early access and limited discount offers for pre-sales.

Entering my Purple Cow Era

2024-03-27T17:54:46-04:00

Have you ever seen a Purple Cow?

First things first, I should probably fill those of you who may be unaware of the Purple Cow concept. Seth Godin has an entire book that does a great job of going into more detail on this concept.

The short version…

Be Remarkable.

Remarkable isn’t necessarily describing quality or that something is good. It’s more about whether it’s interesting, unique, delightful, or weird. So much so, you just have to tell people about it.

What do I do?

Almost one year into my most recent foray into the land of self-employment, I’ve been thinking more about my long term goals and overall vision.

The past few months, I’ve had a chance to work on a few different types of projects and ventures.

I’ve also had some trouble articulating what it is I do…

via GIPHY

The easiest title and the one I use most frequently is Independent Rails Consultant. This accounts for the lion’s share of my time and income so that’s what I usually lead with.

But it’s not the only thing I do. One of the main reasons for going self-employed was having more time to work on other projects and ventures.

Some of those have been:

Writing
Mentoring Early Career Developers
Offering Developer Coaching Services
Spot Squid (SaaS)
Speaking at meetups and conferences
Potentially organizing a Ruby retreat?

The variety and breadth of these projects have been a huge jolt to my creativity. These projects have been stretching me to the edge of my comfort zone consistently. That’s always been a good metric that I’m heading in the right direction.

But still, I wouldn’t use writer, speaker, SaaS founder, conference organizer, or developer coach to describe what I do.

Dawn of the Purple Cow Era

Focus and consistency are two areas I’ve always had trouble with. I’ve made some great strides in the past couple of years but still feel a twinge of self-inflicted guilt for not focusing on the ‘one thing’.

Not long ago, I had the thought of just considering myself a Purple Cow. A Purple Cow’s only mandate is to be unique, interesting and to turn some heads. I think at my core, I love making things. Those things could be code, blog posts, experiences, BBQ, skate ramps, or anything else that piques my interest.

The point is, thinking in Purple Cow terms has me feeling more creative and less boxed in.

My Purple Cow Era is about chasing down the ideas that I’m interested in and that excite me. These are the types of projects where ideas seem to pour out of me. That’s a good sign I should keep going.

Working on these different projects and ideas is the easiest way for me to put my unique stamp and style into what I’m working on.

Let It Rip

There’s a saying you may have heard…

I'm here for a good time, not a long time.

If you’ve heard this, it was probably right before someone did something really stupid.

Instead of viewing this in the light of reckless abandonment, I think about it more as a reminder we should all relish and make the best use of what time we have.

Changing my internal mandate to something along the lines of

Do and make interesting, unique, and remarkable things that are good expressions of yourself.

feels like it’s removed a huge bottleneck and opened me up to allowing more of these ideas in.

Time to get Moo-ving on that Purple Cow idea of yours.

Announcing Rawhide Ruby?

2024-03-07T16:54:46-05:00

You may have noticed the question mark in the title. That’s because this is something that’s still in the very early stages of planning and seeing if there’s enough interest out there to make this happen.

Introducing the y’all-way track…

Rawhide Ruby

Come join us in the mountains of Colorado for a unique and special event.

What

A 2-3 day single track conference hosted at a private ranch. Accommodations would be available on-site and range from private cabins, glamping domes, RV sites and tent camping sites. Talks during the day with activities in the evening on the ranch.

Where

Location is still tentative but will most likely be in the gorgeous Arkansas River Valley area of Colorado. With amazing views of the collegiate peaks, the area also offers a number of other things to do in the area

Hot Springs & Spas
ATV/Jeep Trails
White Water Rafting
Ghost Towns
Hiking & Back country Backpacking
Fishing

When

Tentative date is Summer 2025

What’s Next?

If you’d be interested in attending or sponsoring, join the list for additional information and updates.

In-Depth look at Action Mailbox

2024-02-07T16:54:46-05:00

I wouldn’t say I love email, more like I’m in love with the idea of email.

Even though it feels like I’m barely treading water in a sea of emails, I almost always open and check transactional emails. It seems like I’m not alone. Some estimates show most transactional emails have an open rate of 80-85% source.

With email being a great channel to reach your users, why not make it a two way street? It’s a familiar and low friction way for users to interact with your app and a powerful way to extend the capabilities of your Rails application.

Luckily, Rails has an unsung hero in Action Mailbox. Action Mailbox gives you a familiar Rails-y way to accept and process inbound emails for your app.

This post will walk through getting started with Action Mailbox, how to process your inbound emails and things to watch out for along the way.

Action Mailbox Background

The Rails guides for the Action Mailbox Basics do a pretty good job of explaining what Action Mailbox is. Here’s how they describe what Action Mailbox is:

Action Mailbox routes incoming emails to controller-like mailboxes for processing in Rails. It ships with ingresses for Mailgun, Mandrill, Postmark, and SendGrid. You can also handle inbound mails directly via the built-in Exim, Postfix, and Qmail ingresses.

The inbound emails are turned into `InboundEmail` records using Active Record and feature life cycle tracking, storage of the original email on cloud storage via Active Storage, and responsible data handling with on-by-default incineration.

These inbound emails are routed asynchronously using Active Job to one or several dedicated mailboxes, which are capable of interacting directly with the rest of your domain model.

Two really important items to note are:

storage of the original email on cloud storage via Active Storage... and These inbound emails are routed asynchronously using Active Job...

It’s easy to gloss over those requirements and can cause some issues when deploying to production. That will be covered in more detail and include my experiences deploying to production.

Here’s a rough breakdown of how Action Mailbox processes your inbound emails.

Getting Started

Getting started with Action Mailbox is a pretty familiar process

To install Action Mailbox run the following commands

$ bin/rails action_mailbox:install $ bin/rails db:migrate

The install task creates an ApplicationMailbox and a new migration for the InboundEmails.

 bin/rails action_mailbox:install Copying application_mailbox.rb to app/mailboxes create app/mailboxes/application_mailbox.rb rails railties:install:migrations FROM=active_storage,action_mailbox Copied migration 20240123213529_create_action_mailbox_tables.action_mailbox.rb from action_mailbox 

The migration for the InboundEmail should look something like this

# This migration comes from action_mailbox (originally 20180917164000) class CreateActionMailboxTables < ActiveRecord::Migration[6.0] def change create_table :action_mailbox_inbound_emails do |t| t.integer :status, default: 0, null: false t.string :message_id, null: false t.string :message_checksum, null: false t.timestamps t.index [ :message_id, :message_checksum ], name: "index_action_mailbox_inbound_emails_uniqueness", unique: true end end end 

If you’ve not already added Active Storage to your app, you’ll see the required migrations for Active Storage as well.

The other file that was created is our ApplicationMailbox. You can think of the ApplicationMailbox as the Post Office for your inbound emails. Mail is delivered, sorted then delivered to the correct mailbox. This file is going to route the InboundEmail to a mailbox that inherits from ApplicationMailbox.

# app/mailboxes/application_mailbox.rb class ApplicationMailbox < ActionMailbox::Base # routing /something/i => :somewhere end 

Generating a new mailbox

Like any good Rails tool, there’s a task to generate a new mailbox.

bin/rails generate mailbox support

The above command will create a new mailbox that looks something like this.

class SupportMailbox < ApplicationMailbox def process end end 

As mentioned earlier, our SupportMailbox inherits from ApplicationMailbox and a single method - process.

The process method is where the magic happens but first, we need to direct our InboundEmail to the SupportMailbox.

When your inbound email is routed to the SupportMailbox the process method will be called. This is where you’ll put your processing logic.

For that to happen, we need to tell our ApplicationMailbox how to route emails to this mailbox.

The ApplicationMailbox has a commented out example to help get us started. In this commented out example, anything inbound email with a to address that matches on something will get routed to the SomewhereMailbox.

The routing uses the ruby regex matcher to route emails to a mailbox.

When getting started with Action Mailbox, instead of spending time thinking about how you’re going to route your emails, I’ve found it helpful to use the :all option to direct any inbound email to a specific mailbox.

routing all: :support

# app/mailboxes/application_mailbox.rb class ApplicationMailbox < ActionMailbox::Base routing all: :support # routing(/support\./i => :support) end 

The above example will route all inbound emails to the SupportMailbox. This lets you start focusing on the processing logic of the mailbox right away and update the routing as your needs evolve.

The commented out example shows how you would route any inbound email with a to address containing support to the SupportMailbox.

With everything setup to forward any inbound email to the SupportMailbox you may be wondering…

How do I send an email to my local Rails App?

I would like to introduce you to the aptly named Rails Conductor.

Sending Emails with Rails Conductor

With your app running, you can access the Rails Conductor at the following URL

http://localhost:3000/rails/conductor/action_mailbox/inbound_emails

This is one of my favorite hidden gems (yeah I said it) of Rails. It offers a no-frills UI for sending email directly to your app. You also have the option of creating and sending and email via the built in form or by pasting the source code of an email.

Using the form option should provide you with everything you need. The by source option is a bit more involved and takes to source code from an .eml file. This is a great option for debugging and re-creating issues from production but is typically more than you need when getting started.

New Inbound Email Form

The new inbound email form has some options you’re probably familiar with along with the option to include an attachment to your inbound email.

There’s also some additional fields for setting email headers that may be useful in your processing of the inbound emails.

X-Original-To - The email address listed here is the original recipient of the email that was received.

In-Reply-To - are header values taken from the Message-ID header of the original

If you set up an :all route in your ApplicationMailbox to a specific inbox like the SupportMailbox example, submitting this form should deliver an email to that mailbox. After submitting your email, it will show as pending until Active Job sends the original inbound email to your Mailbox and processes it. If that’s successful, the InboundEmail status will be updated to delivered and at some point will be incinerated.

Now we’re sending email, let’s recap what’s happening:

An email is sent to a specific email address.
Your Email provider accepts and forwards the inbound email to your Rails app.
Your Rails App creates an ActtionMailbox::InboundEmail record and uploads the email file to Active Storage until it can be processed.
Active Job gets the email object and sends to the Mailbox.
The InboundEmail object takes the uploaded email file from Active Storage, converts it to a string and creates a new Mail object.
The process method inside the mailbox is called on the mailbox where the email is delivered too.
The InboundEmail is marked for incineration (record and raw_email attachment deleted).

There’s a surprising amount of things happening in the background at first glace. I think this is a great example of how Rails can handle so much for you allowing you to focus on the important things without setting up a ton of boilerplate on your own.

Process inbound email in the Mailbox

We know that the process method is going to be called withing the mailbox the inbound email is routed.

The ActionMailbox::InboundEmail is that object that’s delivered to the process method. If you look at the generated migration above, there’s not a lot to this class on the surface. It has a status, some references and an Active Storage attachment for the original email file sent raw_email.

 class InboundEmail < Record self.table_name = "action_mailbox_inbound_emails" include Incineratable, MessageId, Routable has_one_attached :raw_email, service: ActionMailbox.storage_service enum status: %i[ pending processing delivered failed bounced ] def mail @mail ||= Mail.from_source(source) end def source @source ||= raw_email.download end def processed? delivered? || failed? || bounced? end end end 

The different statues are:

pending - Email has been received and uploaded to Active Storage.
processing - Original email is being downloaded from Active Storage and sent to the appropriate mailbox.
delivered - Email was successfully delivered to the mailbox with no exceptions or bounces.
failed - An exception was raised while the inbound email was being processed.
bounced - Mark the email as bounced using boune_with

Most of the information you’ll need to process the inbound email is provided by the Mail object which is available with the mail method within the mailbox.

The InboundEmail class defines a mail method that downloads the original email file from Active Storage and creates a new Mail object.

Ruby Mail is an invaluable resource for working with email in Ruby.

mail = Mail.new do from 'mikel@test.lindsaar.net' to 'you@test.lindsaar.net' subject 'This is a test email' body File.read('body.txt') end mail.to_s #=> "From: mikel@test.lindsaar.net\r\nTo: you@... 

Ruby Mail also allows us to dig deeper into things like headers, attachments, html and text parts.

What does ‘processing’ the email actually look like?

Obviously, each case will be different but let’s take a look at an example for parsing the body of the email and creating a new support ticket.

class SupportMailbox < ApplicationMailbox def process support_ticket = SupportTicket.create(from_email: mail.from, subject: mail.subject, body: mail.body) SupportMailer.new_ticket(support_ticket).deliver_now end end 

In the example above, we’re creating a new SupportTicket record from the information contained in the inbound email.

We’re pulling the mail.from, mail.subject, and mail.body data provided by the Mail gem and using that to create our new record.

Parsing inbound email allows you to collect the same information as if you directed your user to a form to submit a new support request. You have all the information to create a new SupportTicket and your user had a more streamlined and familiar process.

The outbound mailer that gets sent as a reply can also contain some type of unique identifier we can easily use to look up the original SupportTicket and link new responses to the conversation.

Let’s say our SupportMailbox has a UUID field on the model, we can include that value in the email address, parse from the reply and link new responses to the original SupportTicket and not create a new support ticket each time there’s a reply.

class ApplicationMailbox < ActionMailbox::Base routing all: :support # routing(/support\./i => :support) routing(/support-(.+)@inbound.yoursite.com/i => :support_reply) --> end 

Testing out the commented out match statement shows we get a match for our test string and we have a result in our capture group

The (.+) is going to return a match group which will be that UUID included in the email address.

That should give you all you need to target the original SupportTicket you created and respond, escalate, close, etc.

That’s the ruby way to link emails together but there are also some options available in the Mail headers.

In-Reply-to contains a hash value of the original message if the subject email message is a reply to another message. This is how your mail clients thread together your emails.

There are a few other considerations to keep in mind when running this in production (bounce_with, before_processing, raising errors, catch all mailboxes, etc.) but this is the basic flow of things.

Advanced Usage

As you continue down the path of inbound email enlightenment, there are some additional tools and methods that could make your journey easier.

Callbacks

Action Mailbox provides some callbacks that will be ran before, after or around the process method.

Action Mailbox Callbacks Source Code

# frozen_string_literal: true require "active_support/callbacks" module ActionMailbox # = Action Mailbox \Callbacks # # Defines the callbacks related to processing. module Callbacks extend ActiveSupport::Concern include ActiveSupport::Callbacks TERMINATOR = ->(mailbox, chain) do chain.call mailbox.finished_processing? end included do define_callbacks :process, terminator: TERMINATOR, skip_after_callbacks_if_terminated: true end class_methods do def before_processing(*methods, &block) set_callback(:process, :before, *methods, &block) end def after_processing(*methods, &block) set_callback(:process, :after, *methods, &block) end def around_processing(*methods, &block) set_callback(:process, :around, *methods, &block) end end end end 

Like mentioned above, these callbacks relate to the process method. If you would like to perform some actions or ensure certain values are present the before_processing, like confirming your can find a User record that matches the email for the inbound message. In our SupportTicket example above, sending the confirmation email after a new ticket is created is a good example of something that would fit in the after_processing method.

 class SupportMailbox < ApplicationMailbox before_processing :ensure_user def process ### code for creating SupportTicket end private def from_email mail.from.first # mail.from returns Array end def ensure_user @user = User.find_by(email: from_email) unless @user bounce_with Mailer.post_not_found(mail) end end end 

Here’s a basic example of using a before_processing callback to make sure we can find the User before doing any additional processing on the email.

Keeping your email delivery rates high and bounce rate low is an important part of getting your emails to actually land in people’s inbox. Taking some additional steps to ensure you at least probably have a valid email address before doing more work than you need to.

You may have noticed another new method in the code above. bounce_with

bounce_with accepts a Mail message to send to the sender letting them know the email bounced. It also marks the ActionMailbox::InboundEmail status as bounced.

source code

There’s another similar method bounced!. This one silently prevents any additional processing without sending out an email alerting the sender of the bounce.

This stops the email from being processed and delivers an email (of your choosing) to notify the sender of the bounce.

The method accepts an ActionMailer::Base::Mailer object along with any additional parameters the email might require.

This might look something like this:

bounce_with PostRequiredMailer.missing(inbound_email) 

Parsing Attachments

It’s very likely people are exponentially more familiar with their chosen email client than they are the UI of your application. Attaching a file to an email is something they’ve probably done dozens if not hundreds of times. Leverage this familiarness by allowing attachments and documents to be sent and uploaded through email.

Let’s set I need some ‘attachments’ or files. For example, PDF documents from a User. I could give them the steps to walk through uploading everything on their own in some sort of self-service portal, have them upload the required documents in a forma…or I could lean on what they already know how to do.

In this example, We’ll look at what the process would be for grabbing an attached PDF from an email, creating an Active Storage object and alerting an admin that a new document is ready.

class LegacyDocumentMailbox < ApplicationMailbox def process create_legacy_document end def create_legacy_document legacy_document = LegacyDocument.new( name: mail.subject, email: mail.from.first, ) # imported_document is the attachment name on LegacyDocument legacy_document.imported_document.attach( io: StringIO.new(mail.attachments.first.body.decoded), filename: mail.attachments.first.filename ) legacy_document.save! end end 

All of our business logic is within the create_legacy_document method, so let’s break down what’s happening.

legacy_document = LegacyDocument.new( name: mail.subject, email: mail.from.first, ) 

We have a LegacyDocument active record object that has name and email attributes. Next, we’re creating a new object and setting the name to the value of the email subject and email to the first returned sender.

Don’t forget the mail gem returns an array of string values when calling from so we grab the first one.

Assuming our LegacyDocument has the Active Storage attachment set up correctly. Remember, Active Storage is a requirement of Action Mailbox so we should already have everything setup and only need to add the has_one_attached :imported_document to the model.

# app/models/LegacyDocument has_one_attached :imported_document 

This is how we can create a new Active Storage attachment of the PDF attachment from the InboundEmail.

 legacy_document.imported_document.attach( io: StringIO.new(mail.attachments.first.body.decoded), filename: mail.attachments.first.filename ) 

With our object created, this code is manually creating and attaching an ActiveStorage::Attachment called imported_document on the LegacyWaiver model.

attachments is a method from Ruby mail that returns a list of the attachments.

Extracting Attachments

Aside from the mail methods for accessing data on the mail object, this code is mostly Active Storage. mail.attachments.first.body.decoded will return a string representation of the attachment which we wrap in StringIO and send to Active Storage.

Digging into Active Storage is out of scope for this post but the general idea is you ‘manually’ attach the file (imported_document) to the parent object (LegacyWaiver)

Accepting attachments all willy-nilly like this does open yourself up to more potential issues. Some things you may want to consider are: file size, file type, dealing with multiple attachments with things like signatures, etc.

Ingress Options and Production Considerations

Default ingress options Action Mailbox provides are:

Exim
Mailgun
Mandrill
Postfix
Postmark
Qmail
SendGrid.

More information for each option can be found in the configuration section of the Rails Guides.

Postmark is my preferred email service provider from the default options Action Mailbox provides. I have another articles with the detail for deploying to Postmark.

Active Storage Service

One thing I’ve found helpful with deploying Action Mailbox to production is to bite the bullet up front and configure an external service like Amazon S3 for Active Storage. Using the disk option can work but if you’re app is not running in a single process, it can potentially cause some headaches.

Here’s why.

When your inbound mail service (like Postmark) receives the inbound email, it forwards it to your Rails application.

After the inbound email is received by your app, it uploads the original email file to Active Storage

ActionMailbox::InboundEmail has an Active Storage attachmentraw_email that is used for storing the original inbound email file (.eml). If we look back at the source method, we see that that file is downloaded from the Active Storage storage service with raw_email.download.

# rails/actionmailbox/app/models/action_mailbox/inbound_email.rb ... def source @source ||= raw_email.download end 

This process is also handled asynchronously with Active Job or other job service you have configured.

Let’s say you have your Rails app deployed to somewhere like Heroku or Render.

On Heroku, you probably have 2 dynos. One running your app, one running your background processes. If you have your Active Storage service set to Disk, that will store the inbound email on your app dyno.

When the worker dyno attempts to process the inbound email by downloading the original attachment, it will look on the dyno it’s being executed on.

However, the actual inbound email is stored on a different dyno.

This means the InboundEmail will never be able to be processed because the dyno running that code can’t find the original attachment (it’s on the other server)

This means that the InboundEmail record will raise an exception when trying to process the email since it can’t find the original attachment (it’s stored in the dyno running the app)

Setting up S3 from the get-go can eliminate a lot of these headaches. It also has the advantage of making it easier to grab the original email file for debugging. This is a great example of where the ‘create email from source’ in the Rails Conductor comes in handy.

Rob Zolkos has a great write up on how you can do that here.

Thanks Rob!

Using a subdomain for inbound mail

Another thing that I’ve found helpful when setting up Action Mailbox for production is running all your inbound emails through a subdomain.

inbound.yourapp.com

This also helps keeping your MX records separate on DNS. If you have internal email addresses for you app with something like name@yourapp.com and try to accept inbound emails for your app at reply-123@yourapp.com it’s pretty easy to accidentally overwrite your current DNS settings for existing email stuff.

I’ve learnt this lesson first hand…

Sometimes, mining for gems takes some diggin’.

Action Mailbox is a wonderful example of clean and concise code handling a complex problem and have learned a lot reviewing the source code.

I think Action Mailbox is a vastly underrated features of rails and can add powerful functionality in a way that feels very familiar to the standard Rails Controllers.

Allowing your users to perform actions from inbound emails is a great way to add convenience and flexibility to your Rails app. I hope this article has demystified the process and given you some ideas on how you can use inbound email in you Rails app.

Let me know if you have any questions, or spot any issues that should be updated. Keep your eye out for some more Action Mailbox content coming soon!

Coming Soon - Action Mailbox Pro

Deploy Action Mailbox to Postmark

2024-02-07T16:54:46-05:00

In my recent Action Mailbox Post, I reviewed a ton of information on how Action Mailbox works and how you can use it. One very important topic I didn’t go over was how to deploy your Action Mailbox code to one of the default providers from Rails.

With that post covering a lot of detail, I wanted to separate out the instructions for deploying.

Rails provides a few different options for providers to handle your inbound emails. You’ll see these referred to as Ingresses or Ingress when referring to one.

The default options from Rails are

Exim
Mailgun
Mandrill
Postfix
Postmark
Qmail
SendGrid

I’ve used Postmark quite a bit over the years for transactional email and have always had a good experience. It’s my default provider and the one we’re going to walk through in this post.

Before we get started, there are a couple of things you’ll need that will help your setup go smoother.

A Postmark Account
A domain to use for the mailer or a secure tunnel to your localhost like ngrok.

This post will assume your app is already deployed somewhere and won’t be covering deploying your Rails app. We’re only focusing on connecting Postmark for your inbound emails.

If you’re looking for some help deploying your app, I’ve been a long time customer of Hatchbox and can’t recommend them enough.

With your Action Mailbox app ready to go, let’s start adding the configuration needed for Postmark.

Rails Guide - Postmark

There isn’t a lot of code required for the Postmark setup so we can add some of the required code before configuring our mail servers in Postmark.

The first thing we need to is set our ingress for Action Mailbox in config/environments/production.rb

Setting the Ingress

# config/environments/production.rb config.action_mailbox.ingress = :postmark 

Generating and setting the ingress password

We also need to generate a password and set that value in our encrypted credentials or as an environment variable.

In your Rails console, we can use SecureRandom to generate a password for us.

SecureRandom.alphanumeric => "12312ddfgdfg" 

Encrypted Credentials Side Note

Running bin/rails credentials:edit will open the main encrypted credentials file. All the credentials in this file will apply to all environments unless we have a specific environment file.

note: For VSCode you may need to run EDITOR="code --wait" bin/rails credentials:edit. If your using another editor besides VSCode and are seeing issues getting your encrypted credentials to open, swap EDITOR=code with whatever editor your using EDITOR=sublime

In other words, these credentials are going to apply to our development and production environment unless I created a credentials/development.yml (or whatever that is) file. Eventually you’ll probably want to separate that out with different settings for different environments. However, making the password available in our development environment is going to make it easier connecting this to our local environment with ngrok.

Add generated password to encrypted credentials

Now we’re done detouring into Rails encrypted credentials, we can the password we generated earlier to our credentials.

You’ll need to copy the output of that command and add it to our encrypted credentials.

I’m a huge fan of using Rails encrypted credentials but if you’d like to stick with using environment variables, you can use the RAILS_INBOUND_EMAIL_PASSWORD environment variable for your password.

Once your encrypted credentials are open add the following code with your generated password.

action_mailbox: ingress_password: 12312ddfgdfg 

That’s pretty much it for the code changes we need to make. The rest of the setup and configuration is going to be on Postmark.

Creating A Postmark Server

If you haven’t already, create a new Postmark account and create a new ‘Server’

In Postmark, a server is a way to organize or group incoming or outgoing email. You can read more about Postmark Servers

After creating the server, you’ll see 3 different ‘Streams’ listed on the dashboard.

To try to keep things consistent. I’ll be using the same terminology as Postmark does. A server is contains different types of ‘Streams’ which are used to send different types of email. Here’s how Postmark defines Streams:

Message Streams is how we separate different types of mail to ensure the highest deliverability for each. Pick the one that’s right for your email:

Transactional streams are for sending time-sensitive messages triggered for one recipient at a time. Broadcasts are for messages sent to many recipients at once, like marketing campaigns or newsletters. Inbound stream is a way for your application to receive email.

Your new Postmark server should have 3 different streams.

Default Broadcast Stream (marketing emails)
Default Inbound Stream (inbound email)
Default Transactional Stream (transactional email from your app like password reset emails)

Configuring the Default Inbound Stream

For configuring our inbound emails, we’ll be using the Default Inbound Stream option.

After first clicking on the Default Inbound Stream link, you should land on the ‘Setup Instructions’ page. Right at the top, you’ll see the option to get your servers inbound email address.

Setting up production email is fraught with peril. Well…maybe that’s being a tad dramatic but it can still be a bumpy ride.

Debugging and diagnosing production issues with email can feel like trying to look inside a black box that has another black box inside. In other words, there’s lot of small points of failure.

For this reason, in order to preserve my time and sanity as best as possible, I try to do a series of small checks along the way to make sure things are working as expected.

When I’m trying to resolve production issues, I’ll often start with focusing on things to rule-out to begin with. Performing some small checks along the way can give you a better idea of what things are working as intended and rule them out as possible causes.

Sending a Test Email

Just to make sure out Inbound Stream has been set up correctly and ready for use, we can fire off a quick email to the server’s inbound email address at the top-section. It should look something like this

123456e8b05e594a3a18129f293281469@inbound.postmarkapp.com

After sending your inbound email to the server, clicking on the ‘Activity’ tab for your inbound server should show the inbound email you just sent.

This lets us know that things should be configured correctly on the Postmark side and can move on to the next step.

Speaking of checking things along the way, now would be a good time to make sure these changes are deployed and checked to make sure the values are set.

Checking your credentials

Speaking of checking things along the way, now would be a good time to check if your changes adding the ingress_password have been deployed to your server. Missing or incorrect keys is very close to the top of my list for most common issues when setting up a new service.

A quick visit to our old friend the Rails console is all we need to confirm our password has been set.

Rails.application.credentials.action_mailbox => {ingress_password: 12312ddfgdfg} 

Or if you set the value with an environment variable.

ENV["RAILS_INBOUND_EMAIL_PASSWORD"] => 12312ddfgdfg 

Add Webhook URL to Postmark

With the password on the server, we need to setup an inbound webhook for Postmark. This inbound webhook is going to receive the incoming email and send the data to our postmark inbound email controller Action Mailbox provides for us.

If you’ve never seen this syntax for authentication in a URL like this I’m sure this looks weird but here’s how you structure your URL for the webhook to add to Postmark:

https://actionmailbox:PASSWORD@example.com/rails/action_mailbox/postmark/inbound_emails

This is using HTTP basic authentication with our username actionmailbox and password PASSWORD (the one we generated and added to the credentials) in the URL. This is how Rails confirms this is a valid request instead of being an open endpoint for requests.

The @example.com is the URL for our server, as in the URL for where your app is deployed (not postmark).

The final portion is the route that goes to the Action Mailbox controller for Postmark.

rails/action_mailbox/postmark/inbound_emails

We now have all the info we need to create our inbound webhook URL.

Click on the ‘Default Inbound Stream’ for your server and look for the section ‘Set your server’s inbound webhook URL’

You could set up the inbound webhook URL on the ‘Setup Instructions’ page for the Inbound Stream, but there’s 1 small change we need to make that’s not visible on that page.

There’s a helpful little note in the Rails guides about including raw email content in the payload.

When configuring your Postmark inbound webhook, be sure to check the box labeled "Include raw email content in JSON payload". Action Mailbox needs the raw email content to work.

If you navigate to the ‘Settings’ section for your Inbound Stream, you’ll see a checkbox in the Webhook section that says ‘Include raw email content in JSON payload’

That’s what the Rails guides were referring to so make sure that option is checked.

With that option checked, add your webhook URL (https://actionmailbox:PASSWORD@example.com/rails/action_mailbox/postmark/inbound_emails) to the field.

Now we’re added new configs, it would be a good time to confirm they’re working.

Testing The Webhook URL

After saving your Inbound webhook URL, you should see a button to check the URL confirming Postmark can correctly send requests to your sever. Clicking on the button should show a loading state and if everything goes well, you’ll see:

Remote server returned an HTTP status code of 204

If you’re not seeing that, you know that there’s an issue connecting your Rails app and Postmark so gives you a good idea of where to look too (check your rails logs to see if the request is hitting your server and if so, if there’s anything obvious happening)

Seeing a successful request doesn’t necessarily mean everything is ready to go, just that Postmark is connecting with your app at the correct URL. This request should be visible in your server logs as well.

If your request fails, you’ll see an error message.

If you’re not getting a successful request to your webhook URL, checking your logs to see if the request hit your app and any errors that may have been raised afterwards is the first place to look.

Connecting a Domain

If you’d like to connect a domain you have to handle all your inbound mailers (hot tip: subdomains save a ton of headache) you can read more about that here

The short version is you need to create a MX record for your inbound email domain and set the value to inbound.postmarkapp.com

If I wanted to set up something like inbound.example.com as my inbound email URL, I would create a new DNS record, set the type to MX, add inbound in the Name section, set the priority 10 (from their docs) and the value to inbound.postmark.com

The screenshot illustrates adding the DNS record for example.yourdomain.com

After adding your DNS record, head back to the Inbound Stream settings page and add your inbound domain to the ‘Inbound domain forwarding’ section and click ‘Save Changes’

And Voila, now you have a production setup for your inbound email.

Testing and debugging locally

It’s pretty likely that at some point, you’ll have some issues you’d like to try to diagnose or re-create in your local environment.

Using ngrok or cloudflare’s secure tunnel service exposes your local development environment (localhost:3000) to a public URL. This is great for sending webhooks from a 3rd party service to your local environment.

I’ll be covering how to use a secure tunnel to debug mailer issues with ngrok.

Start ngrok with ngrok http 3000. In this case our local Rails app is running on localhost:3000.

Your screen should look something like this. Note the URL ngrok is making your app available on. There’s one change we’ll need to make to access our running app on this public URL.

There are a couple of different variations of the ngrok URL (.io, .app, etc.) so make note of which one is being used.

We need to whitelist this host in our config/environments/development.rb file to tell Rails it’s ok to accept connections from this URL.

You can add your specific ngrok domain with: config.hosts << "f515c7854739.ngrok.app"

or if you would like to allow any domain to access localhost you set hosts to nil with config.hosts = nil. This can be handy when testing multi-tenant apps.

Without a premium ngrok account, your URL will be different each time. If you don’t want to update that URL each time you start ngrok, you can use a regex to whitelist _any ngrok domain.

 # config/environments/development.rb # whitelist ngrok domains. config.hosts << /[a-z0-9-]+\.ngrok\.app/ 

The other change for allowing Postmark to send email to your local environment is setting the ingress value in config/environments/development.rb.

# config/environments/development.rb # use ngrok and update postmark settings to test locally config.action_mailbox.ingress = :postmark 

Re-start your server, paste your ngrok URL into your browser and make sure your app loads.

Update Postmark Settings for development

Swap your domain name for the ngrok domain in the webhook settings, it should look something like this:

https://actionmailbox:PASSWORD@f515c7854739.ngrok.app/rails/action_mailbox/postmark/inbound_emails

where f515c7854739.ngrok.app is the URL sending traffic to my local environment.

If we hit the ‘Check’ button, even without saving, that should check the URL to make sure it’s working. You should see a request from Postmark hit your local environment a couple seconds after clicking the button. If all goes well, you’ll see the green text saying Postmark received a 204 status code.

If it failed, hopefully it made it to your app and you’ll have more information in your local logs. If you don’t see anything in your Rails server logs, it’s most likely an issue with the webhook URL.

If your webhook URL returned an successful response, sending an email to the inbound email address for the Default Inbound Stream (123456e8b05e594a3a18129f293281469@inbound.postmarkapp.com) should forward that email to your local Rails app.

To confirm the email made it to Postmark, click on the ‘Activity’ section for the Default Inbound Stream and look for the email you just sent. The email should have a status like queued, retry or processed.

If everything is configured correctly, you should see some activity in your local server logs from Postmark at the corresponding controller:

Processing by ActionMailbox::Ingresses::Postmark::InboundEmailsController#create as JSON

Now we have these real emails being forwarded from Postmark to our local dev environment. This is a huge boost to your feedback loop and a great way to debug tough to re-create issues with inbound email.

Since this works more or less in the same manner as sending an email from the Rails Conductor, we can also do things like adding debugger to our process method inside a mailbox to access an interactive debugger with the data from the real inbound email.

Josh Smith has a great article walking through connecting a debugger to a Rails application if you’re not familiar with that process.

Thanks Josh!

Using Raw Source in development

If you’re unable or unwilling to get everything working with forwarding your emails to your local environment, you still have some options.

If you click on one of the inbound emails listed in your ‘Activity’ section of the Default Inbound Stream, you’ll see some additional information about the inbound email.

Clicking on the tab that says ‘Raw Source’ will display the source code of the email. If you remember from earlier, the Rails Conductor has the option to send an inbound email using the email source code. That’s the information contained in this ‘Raw Source’ section.

Copying that Raw Source and pasting that info into the input for the email by source option in the Rails Conductor should give you a pretty similar result.

Hopefully this gives you some additional tools and methods for debugging and inspecting your inbound emails.

Other Providers

If your intersted in seeing how this same process can be accomplished with Postfix or SendGrid Prabin Poudel has some great articles detailing that process.

Setup Action Mailbox with SendGrid

Setup Action Mailbox with Postfix

Final Thoughts

While these steps have been specific for Postmark, a lot of the same principles, including using a local tunnel like ngrok to send email to your local environment should be pretty similar.

Please let me know if you feel like I left anything out or when Postmark changes their UI making all of these screenshots and steps outdated.

Coming Soon - Action Mailbox Pro

Using Concerns with Ruby on Rails

2023-07-23T17:54:46-04:00

For the past few months, I’ve been holding standups and office hours with a top-notch group of early career developers. After everyone gives their update, we take some time and try to go into more detail about one of the issues they’re having. Topics have ranged from database migrations and when to use the up and down methods over change, helper methods, how and what to test and plenty more.

On one of these in-depth conversations, we found ourselves tracing down a method definition that led us to a module using ActiveSupport::Concern, as I’ll refer to it from here on out, a Concern.

I’ve used Concerns a ton over the years but it’s a topic I’ve never had to look into more than just a quick skim of the docs to check the syntax or make a few changes to an existing Concern.

I realized that while I knew how to use Concerns, I didn’t know enough to be able to explain all of the details without re-visiting the documentation.

This is something that comes up a lot in these mentorship sessions. I have a decent idea how something works. When I don’t, I can usually make an educated guess based on how other things work and are set up in Rails.

When working with these early career devs, I always try to highlight when I don’t know something, which is well…a lot. One of the things I try to stress is you don’t have to know or memorize everything about Rails (or any other framework for that matter).

If you know enough to find what you’re looking for and can read over some documentation or source code and get what you need, there’s no point in memorizing a ton of methods and other documentation. You’ll start to learn and memorize the right things the more you work and figure out the things you’re having to look up consistently.

I thought this was a great opportunity to refresh myself on some of the details around Concerns in Rails, why they’re useful and how to implement them.

What is a Concern?

A Concern is a Module with added methods that makes it easier to define instance and class methods that will be evaluated in the context of the Class they’re included into.

From the Rails Docs we can look at an example of a Concern, and what an equivalent module would look like without the extras provided by ActiveSupport::Concern

# example using ActiveSupport::Concern require "active_support/concern" module M extend ActiveSupport::Concern included do scope :disabled, -> { where(disabled: true) } end class_methods do ... end end 

# plain ruby module version module M def self.included(base) base.extend ClassMethods base.class_eval do scope :disabled, -> { where(disabled: true) } end end module ClassMethods ... end end 

Not only does ActiveSupport::Concern give us a cleaner interface to dynamically define methods into the classes they’re included in, it can also resolve module dependencies.

module Foo def self.included(base) base.class_eval do def self.method_injected_by_foo ... end end end end module Bar def self.included(base) base.method_injected_by_foo end end class Host include Foo # We need to include this dependency for Bar include Bar # Bar is the module that Host really needs end 

module Bar include Foo def self.included(base) base.method_injected_by_foo end end class Host include Bar end 

Why Concerns?

Concerns make it easy to share code across different Classes and Modules. Concerns allow us to define either class methods or instance methods on the objects they will be included to.

Looking at the first example above, we see the Concern is defining a new scope called disabled

# MyConcern included do scope :disabled, -> { where(disabled: true) } end 

The code within the included block will be added to any Class it’s included in.

Say we have a User model with a disabled: boolean column

class User < ApplicationRecord include MyConcern end 

Pending that all the data is set up correctly, we would now be able to use the scope defined in the Concern

disabled_users = User.disabled # returns collection of Users

Let’s say we would like to have that same disabled scope available in an Account class. Instead of defining the scope in this class, we can just include the Concern.

class Account < ApplicationRecord include MyConcern end 

disabled_accounts = Account.disabled # returns collection of Accounts 

This gives us a clean and powerful way to define logic that we’d like to share across different objects.

We’re also not limited to class methods, we can also define instance methods. Assuming both the User and Account models from above have a name field that’s a string.

Let’s say we want to format the name field a specific way to create a filename.

module FileNames include ActiveSupport::Concern def to_filename ActiveSupport::Inflector.parameterize(name, separator: '_') end end 

class User < ApplicationRecord include FileNames end class Account < ApplicationRecord include FileNames end 

user.to_filename "cody_norman" account.to_filename "my_business_account" 

If you find yourself including the same concern many times, you may be able to include it in a parent class like ApplicationController or ApplicationRecord to make that functionality available across any child class.

Where to put your concerns?

If you look inside your app/controllers and app/models directories, both have a concerns directory.

If I’m not mistaken, there isn’t any Rails magic that requires them to be in a specific spot, those directories are there for organization and clarity.

Without overthinking it too much, if your Concern will be added into a controller, it should be in the app/controllers/concerns directory and the same applies for models.

If you’re Concern is only interacting with a single model, it’s best to namespace your concern with the same name as the model you’re interacting with.

# app/models/post.rb class Post include Foo end # app/models/post/foo.rb module Post::Foo extend ActiveSupprt::Concern end 

Thanks to Kasper Timm Hansen for this suggestion on namespacing!

When you’re working with something that interacts with both Models and Controllers and don’t want to break into smaller chunks, consider placing somewhere like lib.

Custom Errors

One thing I like to add to Concerns is a custom error class I raise if there are any errors. Raising the specific error allows error handling to be more specific and explicit. Seeing something like NameIsNilError is a lot more intuitive than something like a method_missing error you have to dig through the stack trace for.

module FileNames include ActiveSupport::Concern class NameIsNilError < StandardError; end def to_filename raise NameIsNilError, "unable to generate filename, name is nil" unless name ActiveSupport::Inflector.parameterize(name, separator: '_') end end 

Testing

There are a few different ways to test Concerns. Some people prefer doing something like a shared context for the functionality the Concern adds, others prefer testing the methods directly in the objects they’re included in.

There’s also the option of creating a dummy class to include your Concern into and testing that class. This is the method I go for most of the time. In the same way concerns help keep duplication to a minimum, I like this option since I’m not continuously adding testing to new objects

I think this is especially a good option for concerns included at a higher level like the ApplicationController

If we have a Users::TimeZone concern included to our ApplicationController to check the user’s timezone, this is an example of including into a dummy class and testing the dummy class

#controller_spec.rb # create a dummy class to include the concern we're testing class MockController < ApplicationController include Users::TimeZone end RSpec.describe MockController, type: :controller do let(:browser_time_zone) { "America/Los_Angeles" } # setup for cookies before do allow(controller).to receive(:cookies).and_return(browser_time_zone: browser_time_zone) end describe "#browser_time_zone" do expect(controller.browser_time_zone).to eq("America/Los_Angeles") end end 

I simplified that example a bit to make it more readable to focus on creating a class within the spec, including our subject Concern to that class and testing the Concern’s functionality.

Closing

Concerns are a great way to keep your code DRY. When you find yourself re-writing or repeating similar methods across different classes, think about moving that logic to a concern. Hopefully, this post has prepared you to better handle the next time to have to update existing concerns or find an opportunity to add a new one.

Upgrading your Jumpstart Pro App

2023-07-19T17:54:46-04:00

If you’re reading this, there’s a good chance this will sound familiar…

You’ve decided to build your latest idea for a SaaS app with Jumpstart Pro.

Things are going great and you’re shipping code left and right. Then…as it tends to do, life gets in the way.

Sometime later, you find some time and renewed vigor to get back at it. But before getting back into development, you’d like to take advantage of any bug fixes or new features merged to Jumpstart since you initially started the app.

Blowing the dust off your old side project and getting things updated again can be a pretty daunting task. There’s a point most of us hit where we start wondering if the ol’ kill it with fire approach is the best path forward and start thinking about scrapping what you have and starting over.

I’ve been there…a lot. I’ve also been on projects that go so long without being updated or maintained, it hits a point where it seems impossible or at least improbable to get approval from the higher-ups.

That was something I wanted to avoid when I first started building SpotSquid. I wanted to take a long-term view and make sure things never get to the point of no return.

I have a few processes I’ve started using to keep my running SaaS app updated as a solo developer. I’ll be going through how I keep my Jumpstart Pro app updated while still shipping features and other changes.

Dependabot

Dependabot updates have been a huge help boost to keeping my app up to date. If you don’t make the time to try to stay on top of them though, they can quickly pile up and become a distraction.

Jumpstart Pro ships with configuration for Dependabot so you’ll start seeing these pull requests start coming in shortly after pushing to GitHub.

The current Jumpstart Pro default for how often Dependabot checks for updates is "weekly". If this is a little optimistic for your taste, you can change the interval value to "monthly".

If you want to go in the opposite direction, you can also configure Dependabot to check for updates "daily".

Dependabot Interval Options

Dependabot Configuration Options

The three package-ecosystems we’re telling Dependabot to watch for changes are "github-actions", for the actions you’ve added and configured as part of your Build/CI process on GitHub, as well as "npm" and "bundler".

This will check NPM for updates to the JS packages and Bundler for ruby gem updates and open a pull request to our app bumping the versions.

Merging changes

This is an example of what you’ll see when you view the Dependabot pull requests in GitHub.

You’ll notice some nice labels are showing if each one of these is a dependency update and if it’s for JS or Ruby. You may also notice the failing builds, I haven’t had time or desire to fix that but I think this process can be pretty close to automatic where it merges after tests pass if you choose to do so.

One option is to merge each of these pull requests individually. This is how I was doing things at first, but it was a little time-consuming. Also, if any issues popped up, it was hard to pinpoint exactly where the problems were introduced.

What I’ve found works best for me is to create a new branch to merge the gem updates into and one to merge the JS updates into.

I used to only do a single upgrade branch but after running into a couple of issues with JS package updates, I keep those separate from everything else to be able to point a finger in the right direction if something goes wrong.

This way, if and when something does go wrong, you don’t have to worry about reverting it right away. You can just delete or ignore the upgrade branch or come back to it when you have more time.

Especially when this is a side-project, you may have hard stops on your time, this keeps your app from getting to a broken state so the next time you have some free time to work on it, you’ll spend it just getting things running again.

I start with the Ruby gems since that’s where I have the most experience with upgrades.

To start, I create a new branch from main using something like:

upgrades/ruby/07-19-23

This branch can be named anything but it’s not uncommon to have to change gears or run out of time in the middle of things so this is something that helps give me more context when I come back to things.

Then I push this branch up to GitHub, update the target branch for each gem upgrade PR to my upgrade branch upgrades/ruby/07-19-23 and merge the changes.

After merging the updates to the upgrade branch, I pull down that branch and do some quick checks to make sure everything is working. I also rely on my test suite to let me know when things go south, but running things locally before merging makes sure when you come back to things, everything starts and works. Things like conflicts with local dependencies or gems that haven’t released a patch for known issues are all little snags you can hit that slow you down and steal precious time from your side project.

If everything looks good locally and all my tests pass on CI, I merge the changes and move on.

If things do go south, at least I know it’s an issue with some of the recent gems and can either

A) revert the changes and try to merge each gem individually to try to find where the problems are being introduced

B) Declare upgrade bankruptcy on this one and get try again the next round of updates. If you’re on the monthly interval, that might be a little more time than you’d like to put things off. The important thing is to find what works best for you.

Another big perk of merging things in groups like this is those issues are contained within the upgrade branch instead of merged into your main branch where you feel like you have to try to frantically fix a broken deployment.

Then I repeat the same process for the JS packages. I’m not pointing fingers but the JS packages seem more likely to introduce breaking changes in minor versions so I really try to keep these separate and make sure everything is working as a whole before merging.

Having a set of steps and processes for merging these updates lowers some of the friction to upgrading and makes it a little more enticing and manageable. Especially if you’re working solo, you have to get the most out of the limited time you have.

I would say currently, if most of the version bumps are pretty small, it takes me about 15-20 mins per week to keep everything updated.

Scheduled reminders and recurring tasks

Depending on your notifications, you probably see something when Dependabot opens a new pull request. However, this will not let you know when there are updates to the upstream repo (the repo you generated your Jumpstart Pro app from). It’s easy to forget about this and let your versions drift further and further from upstream. The longer it goes, the more involved the upgrade process can be.

As a way of gently nudging and reminding myself to upgrade, I have a monthly Slack reminder to ‘Check on upgrades’. That’s kind of a placeholder for Dependabot updates if they’re not already covered and to check on the upstream changes from Jumpstart Pro.

I also have a recurring Trello card that gets created once per month to at least check on the upgrades.

I don’t always have the time to upgrade my application as much as I like, but at least this way, I can stay updated with the changes and plan accordingly. An example of this was seeing there were updates to the Pay gem sending subscription reminders which was something I was planning on working on but was able to focus on other areas and pull the updates once they were merged.

It also helped to re-frame how I thought about these updates. Instead of thinking of pulling upstream changes as a chore, I started thinking about it more along the lines of leveraging what’s available to me.

Pulling these updates and staying on top of the changes allows you to take full advantage of the work being done to Jumpstart. Thinking of it that way as a time-strapped solo founder, why wouldn’t I want the GoRails team and other contributors porting changes that update and enhance my app?

Thinking of it as a perk instead of a chore made it sit a little better with me.

Upstream Changes

I’ve done quite a few upgrades to Jumpstart at this point and this is the process I’ve ended up with. Feel free to tweak as needed but I think having a process or some rules for how you approach these things saves your mental bandwidth for the interesting challenges your app is tackling. Finding a flow and set of steps that works well for you is important to making this something that’s repeatable and not so draining.

These steps are assuming you’ve set up your local repo according to the Jumpstart Pro Docs in particular git remote rename origin jumpstart

First, I pull the latest changes from upstream (the main Jumpstart Pro repo).

$ git fetch jumpstart

Then, I create a branch in the same way I do for the gem updates

$ git checkout -b upgrades/july-19

I don’t usually have any other open upgrade branches while updating Jumpstarst so I don’t include anything noting this is for upstream changes but that might help.

After creating my upgrade branch, I merge the jumpstart/main branch into my upgrade branch and push to GitHub.

$ git merge jumpstart/main

If you’ve been updating regularly, this is usually pretty smooth. You may have to resolve some conflicts before completing the merge. If it’s only a handful of conflicts and/or you feel comfortable resolving conflicts once everything is resolved and you’ve merged your branch you can push that branch up to GitHub to start comparing the changes.

If it’s been more than a couple of months since you’ve pulled updates from the upstream version of Jumpstart Pro, you’ll probably have a lot of conflicts to resolve. If you don’t want to tackle all of those conflicts at once, this is my process for making that a little easier.

When I need more time and more clarity to work through all the changes, I will create a branch with the code from Jumpstart upstream main branch. Then push that to GitHub and open a pull request to an upgrade branch or my main branch (depending on how brave I’m feeling).

Fetch the latest version on the Jumpstart remote and checkout the main branch

$ git fetch jumpstart $ git checkout jumpstart/main

You’ll see a notice about ‘detached HEAD’ which is read-only. We need to switch branches so we’ll be able to make commits.

$ git switch -c jumpstart-updates-july

This gives us a local branch with the code we were trying to merge with git merge jumpstart/main

Push the new branch to GitHub

$ git push origin jumpstart-updates-july

After pushing, I open a pull request on GitHub from the upgrade branch to the main branch. This gives me a nice visual diff of all the changes in a single spot. I’ve found this is much easier for me to digest than trying to do everything locally in Git.

It’s also helpful to mark the changes you’re comfortable with as ‘Viewed’ to help remind you of the files you’ve already reviewed if (and when) you have to come back to this and finish up.

(Screenshots of Diffs and collapsed changes)

This gives you a nice visual to see all the changes. After reviewing some of the changes you may want to do something like “just accept all the changes in lib” and “ignore the changes in app/views”. That’s really up to you and how you prefer to do things.

For me, I’m not actively working or making changes to lib so feel ok marking those as reviewed and generally ignore all the changes to my views and cherry-pick or copy-paste any changes I’d like to include.

Resolving conflicts is beyond the scope of this post but the --ours and --theirs flags for git can be a big help. You can read some more info on those here

As mentioned before, keeping this potentially hairy upgrade within its own branch giving you plenty of time to review and test before merging allows you to skip it entirely or pick back up where you left off whenever you run out of time. Merging the upgrade branch into your main branch this way also gives you the option to revert those changes with a single click.

The worst thing as a solo developer is being stuck trying to get my app running whenever I have time to work on it. Quarantining your upgrades lets you keep rolling as needed.

After running the upgrade branch locally and making sure everything seems to be in order, after feeling pretty comfortable about the changes I’ll merge and deploy to my staging server.

If everything looks good, or at least nothing looks bad, I deploy those changes to production.

Wrapping up

I wouldn’t say I love all of the upgrading I’ve been doing but I will say it’s been a huge help in keeping my apps up to date and finding ways to help myself and others keep theirs updated as well.

Cody Norman Personal Website

Create PDF attachments from email with Action Mailbox

Create your Rails app with Devise

Installing Action Mailbox

Routing the email

Re-routing and Debugging

The Happy Path

Checking for an existing User

Generate Mailers

Checking for an attachment

Checking the attachment type

Reply on success

Wrapping up

Create a QR Code with a Logo

Getting started

Active Storage and Image Processing

QR codes.

Going Further

The Road To Rails Conf 2024

The Road To Rails Conf

What does a good proposal even look like?

Down but not out

Knocking the dust off

Philly.rb

Boulder Ruby

Big Swings

Go Time

Next steps?

Announcing Action Mailbox Pro

Entering my Purple Cow Era

Have you ever seen a Purple Cow?

What do I do?

Dawn of the Purple Cow Era

Let It Rip

Announcing Rawhide Ruby?

What

Where

When

What’s Next?

In-Depth look at Action Mailbox

Action Mailbox Background

Getting Started

Sending Emails with Rails Conductor

Process inbound email in the Mailbox

Advanced Usage

Parsing Attachments

Ingress Options and Production Considerations

Using a subdomain for inbound mail

Coming Soon - Action Mailbox Pro

Deploy Action Mailbox to Postmark

Setting the Ingress

Generating and setting the ingress password

Add generated password to encrypted credentials

Creating A Postmark Server

Configuring the Default Inbound Stream

Sending a Test Email

Checking your credentials

Add Webhook URL to Postmark

Connecting a Domain

Testing and debugging locally

Update Postmark Settings for development

Using Raw Source in development

Final Thoughts

Coming Soon - Action Mailbox Pro

Using Concerns with Ruby on Rails

What is a Concern?

Why Concerns?

Where to put your concerns?

Custom Errors

Testing

Closing

Upgrading your Jumpstart Pro App

Dependabot

Merging changes

Scheduled reminders and recurring tasks

Upstream Changes

Wrapping up

Video