API Quick Start

Postmen helps calculate rates, generate labels, generate invoices and manifests across multiple couriers. You can add your multiple courier accounts in the Postmen app and generate labels as per your negotiated rates with the courier.

This API Quick Start guide intends to walk you through 4 common scenarios, and hopefully, after this journey, you will know how to use the Postmen API to integrate Postmen with your website to calculate rates and generate labels.

The Postmen API is a flexible, modern API that aggregates shipping APIs into one. It allows you to programmatically build applications that interface with Postmen. The API can be used to calculate rates, generate labels and manifest with multiple carriers like UPS, USPS, FedEx and more. Thousands of developers are already using it to automate their shipping process.

Please refer to supported couriers to get a list of all the couriers supported by Postmen.

A shipping label contains the information a courier needs to get your package from its origin to the destination. It includes a scannable barcode with a tracking number that enables the courier to provide delivery updates.

Postmen verifies a user's request by adding an as-api-key in the header. So you shall get the as-api-key first.

Log in to your Postmen Admin account and go to settings. Click the API Keys option to generate your API key.

image.png

You can generate multiple API keys from the API Keys page. Same API key can be used in both sandbox and production environment. image.png

preparing...
preparing...

All endpoints are only accessible via HTTPS.

Use POST /shipper-accounts to create a shipper account. Kindly refer to the endpoint instructions for more details.

preparing...

Once you get the shipper account id in UUID v4 format (e.g. 123e4567-e89b-12d3-a456-426614174000), it can be used to generate labels by callin /v3/labels.

Use POST /labels to generate labels. Kindly refer to the endpoint instructions for more details.

preparing...

Once you get the label url in the response, please click the URL and preview the label layout in your browser.

https://sandbox-download.postmen.com/label/2021-07-22/66bb6e50-7c50-492f-9afd-27e1a5887beb-1626960740878242.pdf

While generating labels, we suggest you provide all the required fields in the request. Please check the full payload in the endpoint instructions for more details.

But when you are not sure what fields are required in /labels, Postmen will validate and return an error message like the one shown below. If you get this error, please update the specific fields and try it again.

preparing...

Use POST /rates to calculate rates before generating labels. ndly refer to the endpoint instructions for more details.

preparing...

You will get the shipping rates of your shipment in the response.

Use GET /labels for generating mutiple labels. Kindly refer to the endpoint instructions for more details.

preparing...

You will get all the label information you generated in the response. Feel free to download all the labels in the browser.

A webhook lets an application share real-time information with other apps. Since data transfer happens instantly, the popularity of webhooks is increasing rapidly these days. With Postmen webhook, you can receive the push update when the API is made asynchronously.

To set up your webhook, go to Postmen Settings and click the Webhooks option to fill in your webhook URL and save it. You can add multiple webhook URLs, and we will push notifications to all those URLs.

Webhook secret

Webhooks include a calculated digital signature for verification. Each webhook request includes an am-webhook-signature header. The signature is a base64-encoded HMAC generated using the sha256 algorithm with the webhook request body and the webhook secret of your account. The following Node.js example demonstrates the computation of a webhook signature.

Each webhook request could be verified by comparing the computed HMAC digest and the attached HMAC digest in the header.

webhook-secret

Sample encrypted signature(Node.js)

preparing...

Sample webhook body

preparing...