Tracking

Tracking

Every order has a status field which will tell you how far along the order is in the delivery pipeline. The status of an order can be one of the values listed below.

Status	Description
ready	The order was created successfully. This order will be printed on the date specified in its sendDate property. By default, sendDate is set to the next day however this can be overwritten and specified for a later date.
printing	The order has been given to a printer and will be processed within our SLA (2 business days).
processed_for_delivery	The order has been handed off to the local postal service.
completed	The order has most likely been delivered. With this status, it is not guaranteed that the order has been delivered as this is an approximation.
cancelled	The order has been cancelled and it will never be sent out.

Check out our guides for how to view the tracking status of an order on the dashboard and via the API.

❗️

ORDER CANCELLATION

Please note that orders can only be cancelled while they are in the "ready" stage. Once an order's status changes to "printing," PostGrid will no longer be able to cancel it.

Tracking Number

Soon after an order has been processed, a trackingNumber property is added to the order. You can use this tracking number to track your order via USPS tracking. If you do not see this tracking number on your order within several days of your order being processed, please reach out to our support team at [email protected].

Intelligent-Mail Tracking

Live orders destined for the US will have an imbStatus field added to them once they are processed at a USPS facility. There can sometimes be a delay in this data which can reach as high as 5 calendar days. See below for the possible imbStatus values.

_{IMB refers Intelligent Mail Barcode which is used to track mailings.}

Status	Description
entered_mail_stream	The order has entered a USPS facility.
out_for_delivery	The order has been processed at its final USPS facility and will be delivered within a day.
returned_to_sender	The order has been returned to the sender.

Check out our guides for how to view the IMB status of an order on the dashboard and via the API.

Note: This feature is only available for live orders destined for the US.

Certified and Registered Mail

For Letters and Cheques, you have the ability to send certified/registered mail including certified mail with return receipts. These options will be applied as an extra service on orders. If an order is certified or registered mail it will be shown in the extraService field on the order. See below for a list of possible extra service values.

Value	Description
certified	Send the order as certified mail
certified_return_receipt	Send the order as certified mail with a return receipt
registered	Send the order as registered mail

Note: This is currently only available for US mailings and additional charges will apply for these mailings.

Check out our guides for how to create and verify if an order is certified/registered mail on the dashboard and via the API.

Express Shipping

You can request express shipping for your orders by setting express to true in your POST requests. In the best case, this would mean your order will reach your customer within 2 days of making the API call. Note that an additional charge will apply for these orders.

Perforation

You can request that the first page of a letter is perforated by adding a parameter perforatedPage: 1 to your letters POST request body. The perforation will be done such that the bottom 3rd of the page (3.6 inches from the bottom) can be torn off the letter.

Return Envelopes

You can send your letters along with a return envelope by supplying a returnEnvelope ID to your POST /letters API call. Note that you must first order return envelopes using our Return Envelopes API.

API Reference: https://postgrid.readme.io/reference/return-envelopes

Using Webhooks to Handle Status Updates

Webhooks can be used to notify your application when events occur in PostGrid. These webhooks for example, can be used to send you a notification when an order has been processed for delivery. Listed below are the possible event types you can listen for on a webhook.

Name	Description
letter.created	Triggered when a letter is created
letter.updated	Triggered when a letter is updated
postcard.created	Triggered when a postcard is created
postcard.updated	Triggered when a postcard is updated
cheque.created	Triggered when a cheque is created
cheque.updated	Triggered when a cheque is updated
self_mailer.created	Triggered when a self mailer is created
self_mailer.updated	Triggered when a self mailer is updated
return_envelope_order.created	Triggered when a return envelope order is created
return_envelope_order.updated	Triggered when a return envelope order is updated

If you wanted to listen for when an order's status has updated, you could listen for the updated events on orders. For example, you could listen for the letter.updated, postcard.updated, and cheque.updated events to receive a notification when any of these collaterals have been updated. If you are only concerned about letters, you would only need listen for the letter.updated event. You can listen to as many or as little events as you need.

Check out our guides for how to set up webhooks to listen for order changes on the dashboard and via the API. For more information on how PostGrid handles webhooks, checkout our webhook guide.

API Reference: https://postgrid.readme.io/reference/webhooks

US NCOA Address Changes

In the event that one of the recipients you've mailed to has moved from the address you supplied, PostGrid may redirect the mail to their new address (depending on your subscription tier).

If mail is redirected, the address changes are applied directly to the affected contacts/orders within our API and dashboard. This also issues a webhook \\*.updated event where \\* is one of letter, postcard, cheque, or self_mailer depending on which type of order was updated.

You can examine the new address by looking at the addressLine1, addressLine2, etc. fields of the contacts. There is also a new addressChange object that gets added to contacts that have changed as a result of a move. See the following for the schema of this object.

Address Change Object

Name	Type	Description
processedOn	Date (string)	The date and time this address change was ingested into our system.
moveYearMonth	string	The MM/YYYY that this contact moved.
oldAddress	object	An object containing the addressLine1, city, etc of the address prior to the move update.