Print and Mail a Customizable Postcard using HTML, CSS, and Ruby on Rails
NOTE: This example was created on an outdated version of the Lob API. Please see the latest Lob documentation for the most up-to-date information on integrating with Lob.
In this post I'm going to walk you through the process of printing and mailing a customizable postcard in a Ruby on Rails application. We will be exploring the functionality of Lob's Postcard API and diving into some of the more advanced HTML templating options. The complete example can be downloaded from our GitHub repository, but I'll be walking through the code step-by-step and explaining things along the way.
I'm assuming you already have a Ruby on Rails project up and running. If not, take a look at the repository and follow the instructions for setting up the project.
The featured image (above) is an example of what our postcard will look like when we are done. The front of the postcard will be designed using basic HTML/CSS. This will allow us to save the design as a template and pass it dynamic variables. For the mailing addresses and the custom message, we will create a Ruby on Rails form to collect that information from the user.
Install the Ruby Gem
Before we can get started sending postcards, we need to install the Ruby wrapper for the Postcard API. We've built a Ruby Gem for this which makes it really easy to start using the API. For this example we'll be using version 3.0.0 of the wrapper. To install it just navigate to your Gemfile and add the line:
gem 'lob', '~> 3.0.0'
This Gem uses an ActiveRecord-style interface for interacting with the Lob API so you will feel right at home in your Rails environment. For full documentation on the Gem, check out the GitHub repository.
Before creating the controller and view files we should first define our routes. We need to let Rails know that we will be setting up a resource called postcards and that it will use the methods index and create. Go ahead and drop this line in your /config/routes.rb file.
resources :postcards, only: [:index, :create]
Once we have this in the routes file we can run rake routes from the terminal and see the new URLs:
Verb URI Pattern Controller#Action GET /postcards(.:format) postcards#index POST /postcards(.:format) postcards#create
We will be creating 3 template files for this example that will live in the following locations:
This is the template file that contains the design for the front of our postcard. It is just simple HTML and CSS, so it's easily customizable. Instead of using static images for your postcards, you can customize and update the design dynamically using already familiar HTML and CSS. Notice that we are printing the name of the recipient in the template using regular Ruby syntax.
You will notice a blank controller action called index.
def index end
This will link up with our index view that displays our form. No logic needed here.
Creating Your Customizable Postcard
Next we have the create action which will handle the request once the form is submitted. Here is where we are creating the Postcard object and sending it to the Lob servers. At the top of the action you can see that we are initializing the Lob API with this line of code. Make sure to use your own Test API Key at the top of the controller instead of using the example one.
Submitting this form will take us to our create.html.erb page which will contain a link. Following this link will take us to the Lob dashboard where we can preview our postcard.
What I've outlined above is a quick and dirty example of how to use the Postcard API and the new HTML template features. In a real world application we would definitely want to do some validation on the mailing addresses. Take a look at our Address Verification API which will validate and standardize any mailing address. This API is also included in the ruby gem so usage will be very similar to the Postcard use case.
Also, you'll definitely want to take a look at the full Documentation for the API. There are a lot more settings and functionality to play around with. Let me if you have any questions in the comments below and I will try to help you out as much as possible.
This blog provides general information and discussion about direct mail marketing and related subjects. The content provided in this blog ("Content”), should not be construed as and is not intended to constitute financial, legal or tax advice. You should seek the advice of professionals prior to acting upon any information contained in the Content. All Content is provided strictly “as is” and we make no warranty or representation of any kind regarding the Content.
Stay up-to-date with Lob’s latest
We have a lot cooking in the Lobster tank! Sign up for our newsletter to never miss a beat.