royal mail tracking
4.2.0
Please raise an issue in the GitHub repository if you are able, if not please feel free to contact me.
Pull requests for bug fixes or potential changes are welcome!
Towards the bottom of this readme is a list of some of the event codes and their rough definition.
PHP 8.1 or above is required.
To install the package via Composer:
composer require elliotjreed/royal-mail-trackingThree means of fetching tracking data are available:
Events: for detailed information and full history of a single tracking number;Signature: the signature data (including image data - either base64-encoded PNG, or an SVG);Summary: for the most recent event for multiple tracking numbers.Details for each are outlined below, with examples included.
Information about error handling is provided below the Events, Signature, and Summary information
(and is worth reading as Summary errors are handled differently to Events and Summary errors).
$tracking = (new ElliotJReedRoyalMailTrackingEvents(
new GuzzleHttpClient(),
'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
'12345678901234567890123456789012345678901234567890',
true, // Optional, when true (default: true) exceptions will be thrown for tracking errors
true, // Optional, when true (default: true) exceptions will be thrown for technical (eg. 500 HTTP response) errors
'https://api.royalmail.net/mailpieces/v2' // Optional, when set the default API endpoint can be overridden (default: 'https://api.royalmail.net/mailpieces/v2')
));$signature = (new ElliotJReedRoyalMailTrackingSignature(
new GuzzleHttpClient(),
'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
'12345678901234567890123456789012345678901234567890',
true, // Optional, when true (default: true) exceptions will be thrown for tracking errors
true, // Optional, when true (default: true) exceptions will be thrown for technical (eg. 500 HTTP response) errors
'https://api.royalmail.net/mailpieces/v2' // Optional, when set the default API endpoint can be overridden (default: 'https://api.royalmail.net/mailpieces/v2')
));$summary = (new ElliotJReedRoyalMailTrackingSummary(
new GuzzleHttpClient(),
'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
'12345678901234567890123456789012345678901234567890',
true, // Optional, when true (default: true) exceptions will be thrown for tracking errors
true, // Optional, when true (default: true) exceptions will be thrown for technical (eg. 500 HTTP response) errors
'https://api.royalmail.net/mailpieces/v2' // Optional, when set the default API endpoint can be overridden (default: 'https://api.royalmail.net/mailpieces/v2')
));The behaviour of the events operation is to provide a history of tracks for a single mail item.
Returns the summary, signature metadata, estimated delivery window and events for a supplied tracking number.
$tracking = (new ElliotJReedRoyalMailTrackingEvents(
new GuzzleHttpClient(),
'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
'12345678901234567890123456789012345678901234567890'
));
$mailPieces = $tracking->setTrackingNumber('AB1234567890GB')->getResponse()->getMailPieces();
$mailPieces->getMailPieceId(); // 090367574000000FE1E1B
$mailPieces->getCarrierShortName(); // RM
$mailPieces->getCarrierFullName(); // Royal Mail Group Ltd
$summary = $mailPieces->getSummary();
$summary->getUniqueItemId(); // 090367574000000FE1E1B
$summary->getOneDBarcode(); // FQ087430672GB
$summary->getProductId(); // SD2
$summary->getProductName(); // Special Delivery Guaranteed
$summary->getProductDescription(); // Our guaranteed next day service with tracking and a signature on delivery
$summary->getProductCategory(); // NON-INTERNATIONAL
$summary->getDestinationCountryCode(); // GBR
$summary->getDestinationCountryName(); // United Kingdom of Great Britain and Northern Ireland
$summary->getOriginCountryCode(); // GBR
$summary->getOriginCountryName(); // United Kingdom of Great Britain and Northern Ireland
$summary->getLastEventCode(); // EVNMI
$summary->getLastEventName(); // Forwarded - Mis-sort
$summary->getLastEventDateTime(); // new DateTimeImmutable('2016-10-20T10:04:00+01:00')
$summary->getLastEventLocationName(); // Stafford DO
$summary->getStatusDescription(); // It is being redirected
$summary->getStatusCategory(); // IN TRANSIT
$summary->getStatusHelpText(); // The item is in transit
$summary->getSummaryLine(); // Item FQ087430672GB was forwarded to the Delivery Office on 2016-10-20.
$internationalPostalProvider = $summary->getInternationalPostalProvider();
$internationalPostalProvider->getUrl(); // https://www.royalmail.com/track-your-item
$internationalPostalProvider->getTitle(); // Royal Mail Group Ltd
$internationalPostalProvider->getDescription(); // Royal Mail Group Ltd
$signature = $mailPieces->getSignature();
$signature->getRecipientName(); // Elliot
$signature->getSignatureDateTime(); // new DateTimeImmutable('2016-10-20T10:04:00+01:00')
$signature->getImageId(); // 001234
$estimatedDelivery = $mailPieces->getEstimatedDelivery();
$estimatedDelivery->getDate(); // new DateTimeImmutable('2017-02-20T00:00:00+00:00')
$estimatedDelivery->getStartOfEstimatedWindow(); // new DateTimeImmutable('2017-02-20T08:00:00+01:00')
$estimatedDelivery->getEndOfEstimatedWindow(); // new DateTimeImmutable('2017-02-20T11:00:00+01:00')
$events = $mailPieces->getEvents();
$event = $events[0];
$event->getEventCode(); // EVNMI
$event->getEventName(); // Forwarded - Mis-sort
$event->getEventDateTime(); // new DateTimeImmutable('2016-10-20T10:04:00+01:00')
$event->getLocationName(); // Stafford DO
$linkSummary = $mailPieces->getLinks()->getSummary();
$linkSummary->getHref(); // /mailpieces/v2/summary?mailPieceId=090367574000000FE1E1B
$linkSummary->getTitle(); // Summary
$linkSummary->getDescription(); // Get summary
$linkSignature = $mailPieces->getLinks()->getSignature();
$linkSignature->getHref(); // /mailpieces/v2/090367574000000FE1E1B/signature
$linkSignature->getTitle(); // Signature
$linkSignature->getDescription(); // Get signature
$linkRedelivery = $mailPieces->getLinks()->getRedelivery();
$linkRedelivery->getHref(); // /personal/receiving-mail/redelivery
$linkRedelivery->getTitle(); // Redelivery
$linkRedelivery->getDescription(); // Book a redelivery$tracking = (new ElliotJReedRoyalMailTrackingEvents(
new GuzzleHttpClient(),
'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
'12345678901234567890123456789012345678901234567890'
));
echo $tracking->setTrackingNumber('AB1234567890GB')->asJson();Would output the Royal Mail response as JSON:
{
"errors": [],
"httpCode": null,
"httpMessage": null,
"mailPieces": {
"carrierFullName": "Royal Mail Group Ltd",
"carrierShortName": "RM",
"estimatedDelivery": {
"date": "2017-02-20T00:00:00+00:00",
"endOfEstimatedWindow": "2017-02-20T11:00:00+01:00",
"startOfEstimatedWindow": "2017-02-20T08:00:00+01:00"
},
"events": [
{
"eventCode": "EVNMI",
"eventDateTime": "2016-10-20T10:04:00+01:00",
"eventName": "Forwarded - Mis-sort",
"locationName": "Stafford DO"
}
],
"links": {
"redelivery": {
"description": "Book a redelivery",
"href": "/personal/receiving-mail/redelivery",
"title": "Redelivery"
},
"signature": {
"description": "Get signature",
"href": "/mailpieces/v2/090367574000000FE1E1B/signature",
"title": "Signature"
},
"summary": {
"description": "Get summary",
"href": "/mailpieces/v2/summary?mailPieceId=090367574000000FE1E1B",
"title": "Summary"
}
},
"mailPieceId": "090367574000000FE1E1B",
"signature": {
"imageId": "001234",
"recipientName": "Elliot",
"signatureDateTime": "2016-10-20T10:04:00+01:00"
},
"summary": {
"destinationCountryCode": "GBR",
"destinationCountryName": "United Kingdom of Great Britain and Northern Ireland",
"internationalPostalProvider": {
"description": "Royal Mail Group Ltd",
"title": "Royal Mail Group Ltd",
"url": "https://www.royalmail.com/track-your-item"
},
"lastEventCode": "EVNMI",
"lastEventDateTime": "2016-10-20T10:04:00+01:00",
"lastEventLocationName": "Stafford DO",
"lastEventName": "Forwarded - Mis-sort",
"oneDBarcode": "FQ087430672GB",
"originCountryCode": "GBR",
"originCountryName": "United Kingdom of Great Britain and Northern Ireland",
"productCategory": "NON-INTERNATIONAL",
"productDescription": "Our guaranteed next day service with tracking and a signature on delivery",
"productId": "SD2",
"productName": "Special Delivery Guaranteed",
"statusCategory": "IN TRANSIT",
"statusDescription": "It is being redirected",
"statusHelpText": "The item is in transit",
"summaryLine": "Item FQ087430672GB was forwarded to the Delivery Office on 2016-10-20.",
"uniqueItemId": "090367574000000FE1E1B"
}
},
"moreInformation": null
}$tracking = (new ElliotJReedRoyalMailTrackingSignature(
new GuzzleHttpClient(),
'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
'12345678901234567890123456789012345678901234567890'
));
$mailPieces = $tracking->setTrackingNumber('AB1234567890GB')->getResponse()->getMailPieces();
$mailPieces->getMailPieceId(); // 090367574000000FE1E1B
$mailPieces->getCarrierShortName(); // RM
$mailPieces->getCarrierFullName(); // Royal Mail Group Ltd
$signature = $mailPieces->getSignature();
$signature->getRecipientName(); // Elliot
$signature->getSignatureDateTime(); // new DateTimeImmutable('2017-03-30T16:15:00+01:00')
$signature->getImageId(); // 001234
$signature->getOneDBarcode(); // FQ087430672GB
$signature->getHeight(); // 530
$signature->getWidth(); // 660
$signature->getUniqueItemId(); // 090367574000000FE1E1B
$signature->getImageFormat(); // image/svg+xml
$signature->getImage(); // <svg></svg>
$events = $mailPieces->getLinks()->getEvents();
$events->getHref(); // /mailpieces/v2/FQ087430672GB/events
$events->getTitle(); // Events
$events->getDescription(); // Get events
$linkSummary = $mailPieces->getLinks()->getSummary();
$linkSummary->getHref(); // /mailpieces/v2/summary?mailPieceId=090367574000000FE1E1B
$linkSummary->getTitle(); // Summary
$linkSummary->getDescription(); // Get summary$tracking = (new ElliotJReedRoyalMailTrackingSignature(
new GuzzleHttpClient(),
'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
'12345678901234567890123456789012345678901234567890'
));
echo $tracking->setTrackingNumber('AB1234567890GB')->asJson();Would output the Royal Mail tracking response as JSON:
{
"errors": [],
"httpCode": null,
"httpMessage": null,
"mailPieces": {
"carrierFullName": "Royal Mail Group Ltd",
"carrierShortName": "RM",
"links": {
"events": {
"description": "Get events",
"href": "/mailpieces/v2/FQ087430672GB/events",
"title": "Events"
},
"summary": {
"description": "Get summary",
"href": "/mailpieces/v2/summary?mailPieceId=090367574000000FE1E1B",
"title": "Summary"
}
},
"mailPieceId": "090367574000000FE1E1B",
"signature": {
"height": 530,
"image": "<svg></svg>",
"imageFormat": "image/svg+xml",
"imageId": "001234",
"oneDBarcode": "FQ087430672GB",
"recipientName": "Elliot",
"signatureDateTime": "2017-03-30T16:15:00+01:00",
"uniqueItemId": "090367574000000FE1E1B",
"width": 660
}
},
"moreInformation": null
}The behaviour of the summary operation is to allow customers to obtain the latest tracking data for a mail item.
This operation returns the summary of one or more tracking numbers provided in the request.
This operation only allows a maximum of 30 tracking numbers to be provided in the ->setTrackingNumbers() method
(eg. ->setTrackingNumbers(['AB0123456789GB', 'CD0123456789GB'])).
$summary = (new ElliotJReedRoyalMailTrackingSummary(
new GuzzleHttpClient(),
'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
'12345678901234567890123456789012345678901234567890'
));
$mailPieces = $summary->setTrackingNumbers('AB1234567890GB', 'CD1234567890GB')->getResponse()->getMailPieces();
$firstMailPieces = $mailPieces[0];
$firstMailPieces->getMailPieceId(); // 090367574000000FE1E1B
$firstMailPieces->getCarrierShortName(); // RM
$firstMailPieces->getCarrierFullName(); // Royal Mail Group Ltd
$summary = $firstMailPieces->getSummary();
$summary->getUniqueItemId(); // 090367574000000FE1E1B
$summary->getOneDBarcode(); // FQ087430672GB
$summary->getProductId(); // SD2
$summary->getProductName(); // Special Delivery Guaranteed
$summary->getProductDescription(); // Our guaranteed next day service with tracking and a signature on delivery
$summary->getProductCategory(); // NON-INTERNATIONAL
$summary->getDestinationCountryCode(); // GBR
$summary->getDestinationCountryName(); // United Kingdom of Great Britain and Northern Ireland
$summary->getOriginCountryCode(); // GBR
$summary->getOriginCountryName(); // United Kingdom of Great Britain and Northern Ireland
$summary->getLastEventCode(); // EVNMI
$summary->getLastEventName(); // Forwarded - Mis-sort
$summary->getLastEventDateTime(); // new DateTimeImmutable('2016-10-20T10:04:00+01:00')
$summary->getLastEventLocationName(); // Stafford DO
$summary->getStatusDescription(); // It is being redirected
$summary->getStatusCategory(); // IN TRANSIT
$summary->getStatusHelpText(); // The item is in transit
$summary->getSummaryLine(); // Item FQ087430672GB was forwarded to the Delivery Office on 2016-10-20.
$internationalPostalProvider = $summary->getInternationalPostalProvider();
$internationalPostalProvider->getUrl(); // https://www.royalmail.com/track-your-item
$internationalPostalProvider->getTitle(); // Royal Mail Group Ltd
$internationalPostalProvider->getDescription(); // Royal Mail Group Ltd
$events = $firstMailPieces->getLinks()->getEvents();
$events->getHref(); // /mailpieces/v2/FQ087430672GB/events
$events->getTitle(); // Events
$events->getDescription(); // Get events
$error = $firstMailPieces->getError();
$error->getErrorCode(); // E1142
$error->getErrorDescription(); // Barcode reference $mailPieceId isn't recognised
$error->getErrorCause(); // A mail item with that barcode cannot be located
$error->getErrorResolution(); // Check barcode and resubmit$summary = (new ElliotJReedRoyalMailTrackingSummary(
new GuzzleHttpClient(),
'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
'12345678901234567890123456789012345678901234567890'
));
echo $summary->asJson();Would output the Royal Mail response as JSON:
{
"errors": [],
"httpCode": null,
"httpMessage": null,
"mailPieces": [
{
"carrierFullName": "Royal Mail Group Ltd",
"carrierShortName": "RM",
"error": {
"errorCause": "A mail item with that barcode cannot be located",
"errorCode": "E1142",
"errorDescription": "Barcode reference mailPieceId is not recognised",
"errorResolution": "Check barcode and resubmit"
},
"links": {
"events": {
"description": "Get events",
"href": "/mailpieces/v2/FQ087430672GB/events",
"title": "Events"
}
},
"mailPieceId": "090367574000000FE1E1B",
"summary": {
"destinationCountryCode": "GBR",
"destinationCountryName": "United Kingdom of Great Britain and Northern Ireland",
"internationalPostalProvider": {
"description": "Royal Mail Group Ltd",
"title": 
