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.

Requirements

• 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.
• You will also need a Lob API Key. If you haven't already, sign up for an account: https://dashboard.lob.com/#/register. Once registered go to https://dashboard.lob.com/#/settings to find your API Key.

The Postcard

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.

The Routes

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

The Views

We will be creating 3 template files for this example that will live in the following locations:

/app/views/postcards/index.html.erb
/app/views/postcards/create.html.erb
/app/views/postcards/postcard_front.html.erb

index.html.erb

This file will display our form, which will collect 3 things from the user: A FROM mailing address, a TO mailing address, and a custom message to be printed on the back of the postcard.

<%= form_for="" :postcards="" do="" |f|="" %=""></%=>
<div class="from"></div>
<label>From Name:</label><%= f.text_field="" :from_name,="" :value=""> "Lob" %></%=>
<label>From Address</label><%= f.text_field="" :from_address_line1,="" :value=""> "185 Berry Street" %></%=>
<label>From City</label><%= f.text_field="" :from_city,="" :value=""> "San Francisco" %></%=>
<label>From State</label><%= f.text_field="" :from_state,="" :value=""> "CA" %></%=>
<label>From Zip </label><%= f.text_field="" :from_zip,="" :value=""> "94117" %></%=>

<div class="to"></div>
<label>To Name:</label><%= f.text_field="" :to_name,="" :value=""> "User 1" %></%=>
<label>To Address</label><%= f.text_field="" :to_address_line1,="" :value=""> "185 Berry Street" %></%=>
<label>To City</label><%= f.text_field="" :to_city,="" :value=""> "San Francisco" %></%=>
<label>To State</label><%= f.text_field="" :to_state,="" :value=""> "CA" %></%=>
<label>To Zip </label><%= f.text_field="" :to_zip,="" :value=""> "94117" %></%=>

<div class="message"></div>
<label>Message:</label><%= f.text_area="" :message="" %=""></%=>

<%= f.submit="" %=""></%=>
<% end="" %=""></%>

create.html.erb

This view file will be used once the user successfully submits the form and will display a link to preview the postcard.

<% if="" @results="" %=""></%>
<h1>Congrats on sending your customized Postcard</h1>

<p>You can view the postcard from the dashboard:</p>

<a href="https://dashboard.lob.com/#/postcards/<%= @results['id'] %>" target="_blank">https://dashboard.lob.com/#/postcards/<%= @results['id']="" %=""></%=></a>
<% end="" %=""></%>

postcard_front.html

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.

<html></html>
<head></head>
<title>Lob.com Sample 4x6 Postcard Front&lt;/title></title>
<style></style>
@font-face {
font-family: 'Arimo';
font-style: normal;
font-weight: 400;
src: url('https://s3-us-west-2.amazonaws.com/lob-assets/Arimo-Regular.ttf') format('truetype');
}
body {
width: 6.25in;
height: 4.25in;
margin: 0;
padding: 0;
background-image: url(https://s3-us-west-2.amazonaws.com/lob-assets/jungle.jpg);
background-size: 6.25in 4.25in;
background-repeat: no-repeat;
font-family: Arimo;
}
#content {
text-align: center;
position: relative;
top: 1.2in;
}
#product-highlight {
background: rgba(0,0,0,.7);
border: 5px solid #000;
display: inline-block;
padding: .2in;
width: 3.5in;
font-size: .14in;
line-height: 1.5;
letter-spacing: 4px;
color: #fff;
}


<body></body>
<div id="content"></div>
<h1 id="product-highlight">Hello <%= params[:postcards][:to_name]="" %=""></%=></h1>

Pulling it all Together with the Controller

Create a file called /app/controllers/postcards_controller.rb with the following code:

class PostcardsController < ApplicationController
# Replace with your API key
LOB_API_KEY = "test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc"

def index
end

def create
lob_client = Lob::Client.new(api_key: LOB_API_KEY)

template_file = ERB.new(File.open(File.join(Rails.root, 'app', 'views', 'postcards', 'postcard_front.html.erb')).read)
custom_html = template_file.result(binding)

@results = lob_client.postcards.create(
description: "Demo Postcard",
to: {
name: params[:postcards][:to_name],
address_line1: params[:postcards][:to_address_line1],
address_city: params[:postcards][:to_city],
address_state: params[:postcards][:to_state],
address_zip: params[:postcards][:to_zip],
address_country: "US",
},
from: {
name: params[:postcards][:from_name],
address_line1: params[:postcards][:from_address_line1],
address_city: params[:postcards][:from_city],
address_state: params[:postcards][:from_state],
address_zip: params[:postcards][:from_zip],
address_country: "US",
},
front: custom_html,
message: params[:postcards][:message]
)
end

end

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.

lob_client = Lob::Client.new(api_key: LOB_API_KEY)

Next, we need to read in our postcard template file. Then we need to render so that it knows to replace our Rails template variables with values from our form.

template_file = ERB.new(File.open(File.join(Rails.root, 'app', 'views', 'postcards', 'postcard_front.html.erb')).read)
custom_html = template_file.result(binding)

At the very top of the API request you can see that we are giving our postcard a name. This is simply for identification purposes and won't be printed on the postcard itself.

name: "Demo Postcard",

Next you can see that we are pulling in the various mailing address parameters from the form and assigning to the corresponding API fields:

name: params[:postcards][:from_name]

To use our custom template for the front of the postcard, just assign our rendered HTML to the front: attribute of the API call.

front: custom_html

Testing

Now that we have everything in place we should be run rails server and visit https://localhost:3000/postcards and see our postcard creation form.

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.

Final Thoughts

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.

‍