Bulk Mail Product Selector API - Documentation

This API allows you to select the best Bulk Mail NZ Post product for your needs.

Test out the API here


Send an HTTP GET to http://api.nzpost.co.nz/ratefinder/bulk_mail with all of the parameters listed below.

Parameter NameDescriptionRequiredExample
api_key Your license key for the application. Please contact developer@nzpost.co.nz for a license key yes 1234-5678-90ab-cdfe
num_items How many items do you want to send (per lodgement)? Yes 1000
height Item height (mm) Yes 80
length Item length (mm) Yes 120
thickness Item thickness (mm) Yes 5
weight Item weight (g) Yes 250
has_soa Does the lodgement have a Statement of Accurary? 1 for yes or 0 for no Yes 1
permit What type of permit does the lodgement have? Can be one of [approved, customised, neither] Yes customised
els Does each item meet the Envelope Layout Standards for machinable or manually-sorted mail? Can be one of [machinable, manual, neither] Yes manual
print_post Is each item a magazine, periodical or catalogue? 1 for yes or 0 for no Yes 0
postcode_sorted Is the lodgement sorted in ascending postcode order? 1 for yes or 0 for no Yes 1
delivery_sorted Is the lodgement sorted in delivery sequence order? 1 for yes or 0 for no No 1
time_of_day What time of the day do you wish to lodge? 'S' for 'By 5pm Monday to Friday', 'E' for 'Evening and weekends' Yes S
format The format of the response (it can also be set by the content-type header). Can be 'json', 'html' or 'xml' Yes json


If the format parameter is set to JSON, the response object is a json hash.

Success is determined by the 'success' key-value pair (either true or false). The product code and description is in the product hash.

Example Request

http://api.nzpost.co.nz/ratefinder/bulk_mail.json? api_key=123&els=machinable&has_soa=1&height=120&length=200&num_items=1000&permit=approved&postcode_sorted=1&print_post=1&thickness=4&time_of_day=S&weight=25

Example Response

           "description":"VolumePost 1 Medium Standard",
     "success": true