Royal Mail Guide

Royal Mail offers domestic and international shipping solutions for shipments originating in Great Britain. ShipEngine's integration with Royal Mail allows our UK-based ecommerce merchants with a Royal Mail Online Business Account - OBA to create domestic and international shipping labels for small parcels to be delivered anywhere within Royal Mail's extensive delivery network.

This guide provides developers an overview of shipping services that Royal Mail offers and the service codes that you will use to create Royal Mail shipments.

Connect Your Account

ShipEngine API allows you to connect your Royal Mail OBA accounts programmatically without logging in to the ShipEngine API dashboard. This is useful if you have wrapped a custom UI around the ShipEngine API toolset and want to add or disconnect existing carrier accounts without exposing your end users to the API dashboard.

These APIs can be used in parallel with the ShipEngine Partner APIs to programmatically create new ShipEngine users, and then connect existing Royal Mail accounts all via the API without logging into a dashboard. Together these APIs empower you to completely white-label the ShipEngine experience for your end users.

Continue below for instructions on how to programatically connect Royal Mail using the ShipEngine API.

For instructions on connecting Royal Mail via the ShipEngine dashboard, go to our Royal Mail help article.

Account the Connection Workflow

The Royal Mail connection process involves several manual steps. This connection request notifies both ShipEngine and Royal Mail. Your Royal Mail account will remain in an inactive pending state until Royal Mail sends ShipEngine your validated OBA Credentials.

Once ShipEngine has received your OBA Credentials from Royal Mail, your account will be configured. If you have services that use personalized tracking numbers, a request will be put in to Royal Mail to obtain tracking number ranges for your account. If you do not have personalized tracking ranges, you will be notified and your account will be activated. If a tracking range had to be requested, your account will be activated when Royal Mail sends back the valid ranges.

The credential verification process and the tracking range request process may take up to 5 business days each.

When your Royal Mail carrier connection is fully activated and verified you will receive an email notification, a notification in the ShipEngine dashboard, and if you are subscribed, the API_CARRIER_CONNECTED webhook.

Should any errors on the registration form cause Royal Mail to reject the registration request, ShipEngine will email you to let you know that corrections are needed. Potential errors could result from your shipping address, OBA email, or Royal Mail account number.

Royal Mail Account Information Model

Example POST Call to Connect a Royal Mail Account

POST /v1/connections/carriers/royal_mail

Copy

HTTPcURLJavaScriptNodeJSPHPPythonRubyC#JavaGoSwiftObjective-CPowerShell

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
POST /v1/connections/carriers/royal_mail HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json

{
"nickname": "My Royal Mail account",
"account_number": "123456789",
"oba_email" : "[email protected]",
"company_name": "Example Corp",
"contact_name": "John Doe",
"email": "[email protected]",
"street_line1": "77 Netherpark Crescent",
"street_line2": "",
"city": "STIRKOKE HOUSE",
"postal_code": "KW1 6LZ",
"phone": "215-555-5555"
"posting_location_number": "1234567890"
}

Example POST Response

Your account will now appear in your carriers list with an assigned carrier_id that you will specify when creating Royal Mail shipments.

1
2
3
{
"carrier-id": "se-1234567"
}

How to Confirm an Active OBA Account

To locate your OBA account number:

Royal Mail Service Details

Domestic Services

International Services

Packages

Royal Mail Enhancement Codes

Royal Mail has enhancement codes that correspond to delivery confirmation types in ShipEngine. For example, the Royal Mail enhancement code for the Signed For service maps to the confirmation type direct_signature.

Only certain services allow certain enhancements. If you choose an option that is not supported with a selected service, then you’ll get a generic error, like Error code E0004 - Failed Schema Validation.

Please consult with Royal Mail for the latest version of Key FAQs for Royal Mail API Shipping, their page RMG Shipping API Technical User Guide, or similar documentation to learn more about enhancement codes.

Return Services

To create return labels, Royal Mail must approve you for at least one of the following services:

Both Royal Mail return services support labelless shipping. Review our Paperless Labels guide for details on creating paperless labels in ShipEngine.

Review the Return Shipping Labels page for details on creating return labels with ShipEngine.

Shipping with Royal Mail

Requirements

Adding Shipment Insurance

Adding shipment insurance is not supported for this carrier.

Advanced Options

Royal Mail supports the following advanced options:

To see what advanced options are available with any carrier, use the List Carrier Advanced Options call.

Royal Mail Customs Declarations

Custom forms will print with the label for your international shipments.

Shipping to the Channel Islands

Guernsey and Jersey: Royal Mail requires customs declarations for Channel Islands shipments to Guernsey and Jersey. Please use the country code GE and JE, respectively. Royal Mail will not produce these forms if the country code is GB.

Isle of Man: Change the country code to IM and then the proper forms will be included with the label. Isle of Man (IOM) shipments do not require customs and there is no option to select IOM as a country code.

Royal Mail Additional Details

Royal Mail Troubleshooting Tips

Here are tips on how to handle some common issues when shipping with Royal Mail.

Example Label

This is an example of a label using Royal Mail 48 - CRL service.

You are now ready to create shipments using Royal Mail via ShipEngine!