Skip to content


Repository files navigation


Build Status Coverage Status Module Version Hex Docs Total Download License Last Updated

Elixir library for Lob API.


The package can be installed by adding :lob_elixir to your list of dependencies in mix.exs:

def deps do
    {:lob_elixir, "~> 1.5.0"}

Getting Started

This library implements the Lob API. Please read through the official API Documentation to get a complete sense of what to expect from each endpoint.


The library requires a valid Lob API key to work properly. To acquire an API key, first create an account at Once you have created an account, you can access your API Keys from the Settings Panel.

API Key Configuration

The library will by default refer to the :api_key config when making authenticated requests. If that is not present, it will look for the LOB_API_TEST_KEY environment variable.

# Configuring an API key with configs
config :lob_elixir,
  api_key: "your_api_key"

The {:system, "ENV_VAR"} syntax is also supported, allowing the API key to be fetched at runtime. For example, if the API key is stored in an environment variable named LOB_KEY, the library could be configured with:

# Configuring an API key with configs
config :lob_elixir,
  api_key: {:system, "LOB_KEY"}

Similarly, the library allows users to optionally configure the API version through the :api_version config. If that is not present, it will look for the LOB_API_VERSION environment variable.

# Configuring an API key and API version with configs
config :lob_elixir,
  api_key: "your_api_key",
  api_version: "2014-12-18"


Requests return a 2-tuple or 3-tuple, depending on the response.

# Successful response
{:ok, postcards, _headers} = Postcard.list()

# Unsuccessful response
{:error, %{message: ":nxdomain"}} = Postcard.list()

# Unsuccessful response with status code
{:error, %{message: "postcard not found", status_code: 404}} = Postcard.retrieve('nonexistent_resource')


To contribute, please see the file.


Tests are written using ExUnit, Elixir's built-in test framework.

Here's how you can run the tests:


To run tests with a coverage report:


Then view the report at cover/excoveralls.html.


Copyright © 2021

Released under the MIT License, which can be found in the repository in LICENSE.txt.