Reading Time: 7 minutes

In my role at MuleSoft, I advise federal agencies and commercial businesses in connecting their applications, data, and devices. Those conversations center around building modern Application Programming Interfaces (APIs) to create new capabilities. A modern API is one that enables systems to exchange information securely using broadly adopted standards like REST and JSON.  

These days there are APIs for nearly everything, like an API for your thermostat. I can change the temperature in my house from my phone or my smartwatch using an application that interacts with my thermostat’s API. One part of your house that is way overdue for an API is your mailbox.

Why Your Mailbox

latest report
Learn why we are the Leaders in API management and iPaaS

Retailers are challenged with optimizing their packaging and shipping; especially with smaller packages that may or may not be able to fit inside of the customer’s mailbox. In 2001, USPS revealed standard mailbox sizes and just the height ranges from 6 inches to 15 inches. That’s a wide size range!

Another challenge is there are many parcel sizes. With more and more people shopping online and getting goods delivered to their homes, being able to get the right size package into the mailbox is incredibly important and could have an impact on profit margins.

What would retailers do if they knew the dimensions of your mailbox? What if they could determine in a second if your items at checkout could fit in your mailbox?

Let’s see how retailers might be able to do that.

Creating the Perfect Mailbox API

One approach might be through a simple information exchange. Here, a retailer would ask the post office “what are the dimensions of my buyer’s mailbox?” The retailer would send the buyer’s address, and either USPS or someone with the postal service information would respond with the mailbox dimensions.

mailbox api

In reality, though, this approach is too simple to be useful.

A better application of the mailbox API can be seen with a mobile order entry application. Once a user adds several items to their shopping cart, then the retailer can request to see if their items will fit in their mailbox. Packages can be optimized to fit in the mailbox and ultimately steer packages to the postal network.

usps api

That’s good in theory, so how do we make this a reality?

I’ve created an API specification in RAML that is vendor-neutral and it contains all the details to implement a fully functional mailbox API. The RAML file contains resources, response codes, and schemas. This spec can be easily implemented in various programming languages.


If you’re interested, then you can visit my Github site to download or contribute changes. The mailbox API is under an MIT license to make it easy to distribute and modify. API users should provide feedback on how they consume the mailbox data.

The functionality we want is created by connecting multiple layers of APIs using a strategy called API-led connectivity. At the bottom layer, which I call the system API, the mailbox dimensions are provided. The next layer will add some process logic, like “will my package fit?” Yes or No? Or a process for optimizing the fit. Will these 3 items fit?

api-led connectivity

Last, there can be multiple APIs for each experience, like an API for a web site, a mobile phone, or even an Amazon Echo. You could use any of those communications channels to discover whether or not a package will fit inside your mailbox.

In summary, these APIs are not necessarily built by one organization, but they exist in an ecosystem. That ecosystem starts with unlocking the data; API consumers can then experiment with how best to use the data. The goal is to enable retailers to optimize their shipments to better fit in their buyer’s mailbox.

For more about how different layers of APIs can help you create different types of functionality that can have a real business impact, take a look at our resources on API-led connectivity and, more specifically, for retail.

And take a look at the mailbox API on my Github site and let me know what you think!