Confirmation Emails & Testing with MailCatcher

Topics Covered in This Ruby on Rails Tutorial:

Installing & Configuring MailCatcher, Creating a Mailer, Sending the Email

Exercise Overview

In this exercise, we'll implement a customer confirmation email system that triggers after checkout completion. Email testing has traditionally presented significant challenges for developers. Setting up production mail servers or configuring reliable SMTP relays requires extensive infrastructure knowledge and careful security considerations. Even with proper setup, development teams often find themselves limited to personal test addresses, battling spam filters, and risking IP blacklisting from misconfigured servers.

The MailCatcher gem elegantly solves these development pain points by creating a local email testing environment. It operates as a lightweight SMTP server on your development machine, intercepting all outgoing emails from configured applications and presenting them through an intuitive web interface. This approach eliminates external dependencies while providing complete visibility into email content, formatting, and delivery metadata. Since MailCatcher runs as a standalone service, it maintains clean separation from your Rails application without cluttering your Gemfile with development-only dependencies.

1. If you completed the previous exercises, you can skip the following sidebar. We recommend you finish the previous exercises (8A–12A) before starting this one. If you haven't finished them, do the following sidebar.

   MailCatcher Solution

   MailCatcher runs a dummy mail server on your computer, catching all outgoing email from configured applications and serving them through a web interface for easy testing.

Installing & Configuring MailCatcher

Now that we understand the benefits of local email testing, let's set up MailCatcher and configure Rails to route emails through our development environment.

1. For this exercise, we'll continue working with the nutty folder located in Desktop > Class Files > yourname-Rails Class > nutty.

   If you haven't already done so, we suggest opening the nutty folder in your code editor if it allows you to (like Sublime Text does).

2. You should still have a window with two tabs open in Terminal from the last exercise, the first of which is running the server. If you don't, complete the following sidebar.

   Independent Installation

   MailCatcher runs separately from your Rails app, so you don't need to add it to your Gemfile. This keeps your application dependencies clean.

Creating a Mailer

With MailCatcher configured, we'll now build a Rails mailer to handle order confirmation emails. Rails mailers follow the same architectural patterns as controllers: they prepare data, set instance variables, and render views to generate email content.

1. Generate a new mailer using Rails' built-in generator:

   rails g mailer order_mailer

   This command creates the necessary mailer class file along with a corresponding views directory structure for email templates.

2. Examine the generated application-level mailer configuration by opening: nutty > app > mailers > application_mailer.rb

   This file establishes default settings inherited by all mailers in your application, similar to how ApplicationController provides shared functionality for all controllers.

3. Customize the default sender address to reflect our business domain:

   default from: "orders@thatnuttyguy.com"

   Using a dedicated email address like orders@ creates a professional appearance and helps recipients identify the email's purpose immediately.

4. Save the file and open the specific order mailer: nutty > app > mailers > order_mailer.rb

5. Implement the confirmation email method by adding the following code around line 2:

   class OrderMailer < ApplicationMailer
      def confirmation_email(order)
         @order = order
         mail(to: @order.email, subject: "Your Order #{@order.id} at ThatNuttyGuy.com")
      end
   end

   NOTE: This mailer method mirrors controller architecture. We define a method name (confirmation_email) that accepts an order parameter, convert it to an instance variable for view access, and call the mail method to configure recipients and subject line. Rails automatically looks for corresponding view templates to generate the email body content.

6. Save the file. We'll now add the email template files to complete our mailer setup.

7. Open Finder and navigate to: Desktop > Class Files > yourname-Rails Level 2 Class > snippets

8. Select both email template files by clicking confirmation_email.html.erb then Shift–clicking on confirmation_email.text.erb

9. Copy the selected files with Cmd–C

10. Navigate to the mailer views directory: Desktop > Class Files > yourname-Rails Level 2 Class > nutty > app > views > order_mailer

11. Paste the template files with Cmd–V

12. Open the HTML email template: nutty > app > views > order_mailer > confirmation_email.html.erb

13. Review the template structure. This file functions like any other Rails view, with access to instance variables from the mailer method and standard ERB templating features. The HTML version provides rich formatting capabilities for modern email clients.

14. Close the HTML template and open the plain text version: nutty > app > views > order_mailer > confirmation_email.text.erb

    Providing both HTML and plain text versions follows email best practices and ensures compatibility across all email clients. Recipients with text-only preferences or accessibility requirements can still receive properly formatted order confirmations, while modern clients can choose the optimal rendering format.

15. Close the text template file. Our mailer is now ready for integration with the checkout process.

Sending the Email

The final step involves integrating our order mailer into the checkout workflow to automatically send confirmation emails when customers complete their purchases.

1. Open the cart controller: nutty > app > controllers > cart_controller.rb

   We'll trigger the confirmation email immediately after successful order completion and before redirecting the customer to the success page.

2. Add the email delivery call to the complete method as shown:

   def complete
      @order = Order.new(customer: current_customer)
      @order.line_items = @cart.line_items
      @order.save
      @cart.destroy
   
      OrderMailer.confirmation_email(@order).deliver
   
      redirect_to '/cart/complete' and return

   This implementation ensures the email sends only after successful order processing but before cart cleanup, providing the mailer with all necessary order data while maintaining proper error handling flow.

3. Save the file and prepare to test the email functionality.

4. Restart the Rails server to ensure all mailer configurations load properly. In Terminal, stop the current server with Ctrl–C, then restart with rails s.

5. Test the email system by completing a purchase. Open a new browser tab and navigate to: localhost:3000

6. Add a product to your cart by selecting any item and clicking the add button.

7. Proceed to checkout by clicking the Checkout button in your cart.

8. Switch to your MailCatcher browser tab to view the intercepted email.

9. Click on the newly received confirmation email to examine its content.

   Excellent! The order confirmation email displays properly with all dynamic content populated from the order data.

10. Click the Plain Text tab within the email viewer to confirm that both HTML and plain text versions were generated and delivered successfully.

    This multi-format approach ensures optimal compatibility across diverse email clients and user preferences.

11. Now that you've verified the email functionality works correctly in the development environment, you can shut down the Rails server. Switch to Terminal and press Ctrl–C to stop the server.