Ruby wrapper for the Lob.com API. This gem gives you an ActiveRecord-style syntax to use the Lob.com API.
Supports Ruby 1.9.3 and greater.
- Installation
- Usage
- Supported Image Types
- Initialization and Configuration
- API Reference
- Developing
- Testing
- Contributing
Add this line to your application's Gemfile:
gem 'lob'
And then execute:
$ bundle
Or manually install it yourself:
$ gem install lob
The library uses an ActiveRecord-style interface. You'll feel right at home. You'll need a Lob.com API key. It's free and you can get yours here.
For optional parameters and other details, refer the docs here - https://lob.com/docs
When using zip codes with zero-prefixes, always quote them. For example when specifying 02125, pass it as a string "02125", instead of an integer.
The Ruby interpreter assumes it's not of base-10 and tries to convert it to base-10 number. So that might result in an entirely different zip-code than intended.
The lob.com API supports the following image types:
- PNG
- JPEG
For more information on prepping the images please see the Lob documentation
If you need to generate your own PDF programmatically we recommend using prawn. There is an example provided in the examples folder here
# To initialize a Lob object
@lob = Lob.load(api_key: "your-api-key")
# Alternatively, to set the API key for all calls in the future
Lob.api_key = "your-api-key"
@lob = Lob.loadLob.configure do |config|
config.api_key = "your-api-key" # get your own at http://lob.com :)
config.api_version = "v1" # default version
config.protocol = "https" # default protocol
config.api_host = "api.lob.com" # ofcourse it's Lob
end- Simple Print Service
- Simple Postcard Service
- Simple Check Service
- Simple Area Mail
- Resources
# Below is an example with inline addresses and object creation
@lob.jobs.create(
name: "Inline Test Job",
from: {
name: "Test Address",
email: "[email protected]",
address_line1: "123 Test Street",
address_line2: "Unit 199",
city: "Mountain View",
state: "CA",
country: "US",
zip: 94085
},
to: {
name: "TestAddress",
email: "[email protected]",
address_line1: "123 Test Street",
address_line2: "Unit 199",
city: "Mountain View",
state: "CA",
country: "US",
zip: 94085
},
objects: {
name: "Local File Object",
file: File.new("/path/to/file.pdf"),
setting_id: 100
})
# name, to-address and object are the arguments
# to-address can be specified as an address-id
@lob.jobs.create(
name: "New Cool Posters",
from: "from-address-id",
to: "to-address-id",
objects: "object-id"
)
# mixing inline objects with ids
@lob.jobs.create(
name: "New Cool Posters",
from: {
name: "FromAddress",
address_line1: "120, 6th Ave",
city: "Boston",
state: "MA",
country: "US",
zip: 12345
},
to: "to-address-id",
objects: "object-id"
)
# You can also pass new object params for the object
# and other options like packaging_id an setting_id
@lob.jobs.create(
name: "New Cool Posters",
from: "from-address-id",
to: "to-address-id",
objects: "object-id",
{
name: "Your fantistic object",
file: "http://test.com/file.pdf",
setting_id: "some-setting-id"
}
)
# Multi Object Jobs (include more than 1 file)
@lob.jobs.create(
name: "New Cool Posters",
from: "from-address-id",
to: {
name: "ToAddress",
address_line1: "120, 6th Ave",
city: "Boston",
state: "MA",
country: "US",
zip: 12345
},
objects: ["object-id", "another-object-id"]
)
# returns an array of jobs
@lob.jobs.list
#you can also pass count and offset
@lob.jobs.list(count: 10, offset: 3)# returns the job with the corresponding ID
@lob.jobs.find("some-job-id")# name, address, city, state, country and zip are required parameters
@lob.addresses.create(
name: "John Doe",
email: "[email protected]", # optional
address_line1: "104, Printing Boulevard",
address_line2: "Sunset Town", # optional
city: "Boston",
state: "MA",
country: "US",
zip: 12345
)# returns an array of addresses
@lob.addresses.list
#you can also pass count and offset
@lob.addresses.list(count: 10, offset: 3)# returns the address with the corresponding ID
@lob.addresses.find("some-address-id")# deletes the address with the corresponding ID
@lob.addresses.destroy("some-address-id")# verifies and returns an address with more details
@lob.addresses.verify(
address_line1: "220 WILLIAM T MORRISSEY BLVD",
city: "Boston",
state: "MA",
zip: "02125"
)# You can create an onject by passing the name, file url and setting ID, quantity is defaulted to 1
@lob.objects.create(
name: "Your fantistic object",
file: "https://s3-us-west-2.amazonaws.com/lob-assets/test.pdf",
setting_id: "201"
)
# You can also pass the quantity as an option
# Or pass a file for upload instead of a url
@lob.objects.create(
name: "Your fantistic object",
file: File.new("/path/to/file.pdf"),
setting_id: "some-setting-id",
quantity: 12
)# returns an array of objects
@lob.objects.list
#you can also pass count and offset
@lob.objects.list(count: 10, offset: 3)# returns the object with the corresponding ID
@lob.objects.find("some-object-id")# deletes the object with the corresponding ID
@lob.objects.destroy("some-object-id")# returns an array of settings
@lob.settings.list# returns a setting object
@lob.settings.find("setting_id")# returns a list of packagings
@lob.packagings.list# returns a list of services
@lob.services.listYou'll have to specify either the message option or the back option.
# create postcard with complete customization
@lob.postcards.create(
name: "John Joe",
to: {
name: "ToAddress",
address_line1: "120, 6th Ave",
city: "Boston",
state: "MA",
country: "US",
zip: 12345
},
from: {
name: "FromAddress",
address_line1: "120, 6th Ave",
city: "Boston",
state: "MA",
country: "US",
zip: 12345
}
front: "https://s3-us-west-2.amazonaws.com/lob-assets/postcardback.pdf",
back: File.new("/path/to/file.pdf")
)
# create postcard with templated back
@lob.postcards.create(
name: "John Joe",
to: {
name: "ToAddress",
address_line1: "120, 6th Ave",
city: "Boston",
state: "MA",
country: "US",
zip: 12345
},
from: {
name: "FromAddress",
address_line1: "120, 6th Ave",
city: "Boston",
state: "MA",
country: "US",
zip: 12345
}
front: "https://s3-us-west-2.amazonaws.com/lob-assets/postcardback.pdf",
message: "Hey Buddy, Thanks for Visiting"
)
# sending a new postcard with stored address id
@lob.postcards.create(
name: "John Joe",
to: "to-address-id",
message: "Hey buddy. Waiting to hear your stories",
front: File.new("/path/to/file.pdf")
)@lob.postcards.list
#you can also pass count and offset
@lob.postcards.list(count: 10, offset: 3)@lob.postcards.find("post-card-id")# For the "to" address, you can pass params
# Transfer $5000 to a bank account.
@lob.checks.create(
bank_account: "bank-account-id",
to: {
name: "FromAddress",
address_line1: "120, 6th Ave",
city: "Boston",
state: "MA",
country: "US",
zip: 12345
},
amount: 5000
)
# or an address ID
@lob.checks.create(
bank_account: "bank-account-id",
to: "to-address-ID",
amount: 5000
)
# You can also specify an optional 4th argument, with other options.@lob.checks.list@lob.checks.find("check-id")bank_address =
account_address =
# Pass address params or address IDs
# The 5th argument is the options argument and is optional
@lob.bank_accounts.create(
routing_number: "routing_number",
account_number: "account_number",
bank_address: {
name: "ToAddress",
address_line1: "120 6th Ave",
city: "Boston",
country: "US",
zip: 12345
},
account_address: {
name: "ToAddress",
address_line1: "120 6th Ave",
city: "Boston",
country: "US",
zip: 12345
}
)# returns a list of accounts
@lob.bank_accounts.list@lob.bank_accounts.find("bank-account-id")You'll have to specify front, back, and either zip_codes or routes
# create an area request with routes
@lob.areas.create(
name: "My Area",
front: "https://s3-us-west-2.amazonaws.com/lob-assets/areafront.pdf",
back: "https://s3-us-west-2.amazonaws.com/lob-assets/areaback.pdf",
routes: ["94158-C001", "94107-C031"],
target_type: "all",
full_blled = "1"
)
# create an area request with zip_codes
@lob.areas.create(
name: "My Area",
front: "https://s3-us-west-2.amazonaws.com/lob-assets/areafront.pdf",
back: "https://s3-us-west-2.amazonaws.com/lob-assets/areaback.pdf",
zip_codes: ["95678", "94158"],
target_type: "all",
full_blled = "1"
)zip_codes and routes can be a string or an array of strings
@lob.areas.list
# you can also pass count and offset
@lob.areas.list(count: 10, offset: 3)@lob.areas.find("area_id")You'll have to specify zip_codes
@lob.routes.find(
zip_codes: ["95678, 94158"]
)zip_codes can be a string or an array of strings
# returns a list of countries
@lob.countries.list# returns a list of states
@lob.states.listMake sure you have Ruby 2.0 installed. Copy and paste the following commands in your projects directory.
git clone https://github.com/lob/lob-ruby.git
cd lob-ruby
bundle install
You are powered up and ready to roll ~!
To run the tests, download the required sample files by running the following command:
bundle exec rake dev:setup
Tests are written using MiniTest, a testing library that comes with Ruby stdlib. The remote responses are tested using vcr.
You'll need to pass in your Lob.com API as the environment variable LOB_API_KEY, to run the tests. Be sure to use your Test API key, and not the Live one.
Here's how you can run the tests:
LOB_API_KEY=your_test_api_key bundle exec rake test
When you make changes to failed tests, then clear out the vcr cassettes to re-record the http requests. You can clear out all the cassettes by running rm -rf spec/vcr_cassettes.
You can also configure, TravisCI for your fork of the repository and it'll run the tests for you, when you push.
- Fork it
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Add some feature') - Push to the branch (
git push origin my-new-feature) - Make sure the tests pass
- Open up coverage/index.html in your browser and add tests if required
- Create new Pull Request
Copyright © 2013 Lob.com
Released under the MIT License, which can be found in the repository in LICENSE.txt.