Royal Mail API Integration: A Complete Guide for UK Businesses

The Royal Mail API gives UK businesses programmatic access to Royal Mail’s shipping infrastructure — creating shipments, generating labels, booking collections, tracking parcels and submitting manifests, all without anyone manually logging into the Royal Mail portal. This guide covers how the API works, which product is right for your volume, how authentication works, and what a properly built integration looks like.

Which Royal Mail API is right for your business?

Royal Mail doesn’t have a single API — it has several, aimed at different despatch volumes and use cases. Choosing the wrong one is a common early mistake that causes problems later.

Click & Drop API is the right starting point for most ecommerce businesses. It’s Royal Mail’s despatch platform for businesses sending up to around 1,000 items per day. The API automates what you’d otherwise do manually through the Click & Drop web interface — importing orders, generating labels, submitting the end-of-day manifest. If you’re on WooCommerce, Shopify, a custom platform or a bespoke OMS, and you’re not doing industrial volumes, this is where you start. It’s well-documented, relatively straightforward to authenticate, and covers the full range of Royal Mail domestic services.

Pro Shipping API is for higher-volume operations, typically from 100 to 1,000 shipments per day where you need more direct control over service selection, label formats, EORI and IOSS data for international orders, and automated manifest submission. The integration is more involved than Click & Drop but gives you more flexibility in how labels are generated and how services are selected per shipment.

Mailmark API is for large-scale operations processing more than 1,000 items daily — subscription fulfilment operations, large ecommerce businesses and third-party logistics providers. It enables discounted postage rates, barcode-level tracking and full enterprise-grade automation. Royal Mail approval is required and the integration is the most complex of the three.

The right API for your business is determined by your daily despatch volume, what platform you’re integrating with, and how much control you need over service selection and label formats. Part of the scoping process for any Royal Mail integration is identifying the right product before development starts — using the wrong one means either hitting volume limits you didn’t anticipate or over-engineering an integration for a simpler use case.

What the Royal Mail API returns

Depending on which API product you’re using, the Royal Mail API handles several distinct operations:

Shipment creation — you submit the recipient address, package weight, dimensions and service type. The API validates the address, creates the shipment record in Royal Mail’s system, and returns a shipment ID and tracking number. This is the core operation that everything else is built around.

Label generation — from the shipment ID, the API generates a printable label in your specified format (PDF, ZPL for thermal printers, or PNG). The label includes the barcode, address, service indicators and all the data Royal Mail needs to route the parcel. This can be generated immediately after shipment creation and sent to a printer queue without any manual steps.

Collection booking — if you’re using a collection service rather than dropping off at a post office or Parcelforce depot, the API handles collection booking automatically based on your configured collection address and time window.

Manifest submission — Royal Mail requires an end-of-day manifest that summarises all shipments from that day. The integration submits this automatically at a scheduled time rather than requiring someone to log in and click through the manual process. Missed manifests cause delays in processing and collection.

Tracking — the tracking API returns real-time parcel status events. These can be pulled into your customer-facing order tracking page, used to send automated despatch notification emails, or pushed to your order management system to keep customer service teams informed without needing to check Royal Mail’s website.

How Royal Mail API authentication works

Royal Mail uses OAuth 2.0 for API authentication. You register as an API developer through the Royal Mail Developer Portal, create an application, and receive a client ID and client secret. These are exchanged for a Bearer access token, which is included in the header of every API request.

Access tokens expire after a set period and need to be refreshed. A properly built integration caches the token for its valid lifetime and requests a new one only when it expires — rather than fetching a new token on every API call, which adds unnecessary latency and can trigger rate limits on the token endpoint.

For Click & Drop specifically, authentication is handled through the Click & Drop developer portal and uses an API key rather than OAuth. This is simpler to set up but the key needs to be stored securely server-side and rotated periodically.

Credentials should never appear in client-side code. The integration uses a server-side proxy — your platform sends a request to your own server, the server calls the Royal Mail API with the credentials, and the response is returned to your platform. This is the same pattern used for all API integrations and keeps your Royal Mail credentials protected.

International shipping and compliance data

For international shipments, the Royal Mail API handles the additional data requirements that come with cross-border sending. EORI numbers (Economic Operators Registration and Identification) are required for commercial shipments from the UK to the EU and other destinations. IOSS numbers (Import One Stop Shop) are relevant for EU-bound B2C shipments under the EU VAT reform. Both can be included in the shipment creation request and are automatically included on the customs data that accompanies international parcels.

Customs commodity codes, declared values, contents descriptions and country of origin data are all part of the international shipment payload. Getting this data from your order management system and passing it correctly to the API is part of the integration scope — particularly important for businesses selling internationally at volume where customs delays caused by missing or incorrect data are a real operational problem.

Service selection and packaging rules

One of the key advantages of a custom Royal Mail API integration over a plugin is the ability to implement your own service selection logic. Plugins offer a dropdown. A custom integration can automatically select the right service based on weight, dimensions, order value, destination, delivery speed requirements and any other criteria you define.

Examples of custom service selection logic: parcels over 2kg automatically use Tracked 48 Large Letter; orders over £100 automatically use Special Delivery for signature; next-day orders placed before 2pm use Tracked 24; international orders to specific destinations use the appropriate tracked international service. All of this runs automatically without anyone making a manual decision at despatch.

Packaging rules work the same way — the integration can calculate whether an item fits a specific letter or large letter format based on dimensions, and switch to the appropriate postage class automatically. This can make a meaningful difference to postage costs at scale.

Error handling and resilience

A production Royal Mail API integration needs to handle failure states gracefully. The Royal Mail API can be unavailable, return validation errors for addresses, reject shipments with missing data, or return unexpected responses. Each of these needs a defined handler.

Common error scenarios to handle: invalid or undeliverable postcode; weight or dimensions outside the allowed range for the selected service; missing customs data for international shipments; API unavailability causing a timeout; rate limit responses. A well-built integration logs all errors, alerts your team, and either retries automatically where appropriate or flags the shipment for manual review without losing the order.

For what a Royal Mail integration costs and how long it takes to build, see the Royal Mail API integration cost guide. For the full service and pricing tiers, see the Royal Mail API integration service. If you’re on WooCommerce specifically, see how to automate Royal Mail labels on WooCommerce.

Choosing between Click & Drop, Pro Shipping and Mailmark

The three Royal Mail API products aren’t just different volume tiers — they have meaningfully different technical architectures and different approval requirements. Understanding which one your business actually needs before development starts saves significant time and avoids the cost of rebuilding an integration that started on the wrong API.

Most businesses start with Click & Drop and move to Pro Shipping only when their volume and complexity requirements exceed what Click & Drop supports. Click & Drop is intentionally accessible — lower volume requirements, simpler authentication, easier developer registration. The trade-off is less direct control over some aspects of the label generation and shipment creation process. For the majority of UK ecommerce businesses, this is an acceptable trade-off that never becomes a problem.

Pro Shipping becomes necessary when you need: service combinations not available through Click & Drop; direct label format control that Click & Drop doesn’t expose; integration with enterprise systems that require a more direct API connection; or volumes where the Click & Drop infrastructure doesn’t scale appropriately. Royal Mail’s approval process for Pro Shipping is more formal — they want to understand your expected volume and integration use case before granting access.

Mailmark is a different category entirely. It’s not just a higher-volume version of Pro Shipping — it’s the enterprise fulfilment infrastructure that large operations use to access discounted postage rates through volume commitments and barcode-level tracking across high-volume despatch runs. The technical complexity is higher, the approval process is more involved, and the benefits only become meaningful at very high volumes. If you’re asking whether you need Mailmark, you almost certainly don’t yet.

Testing and sandbox environments

Royal Mail provides sandbox environments for all three API products. All integration development should happen against the sandbox before connecting to your live account. The sandbox returns realistic responses — label data, tracking numbers, shipment IDs — that allow end-to-end testing of the full despatch flow without generating real postage charges or creating real shipment records in your Royal Mail account.

Testing should cover the full range of scenarios your integration will encounter in production: successful shipment creation for each service type, address validation failures, weight and dimension limit exceeded, API unavailability, timeout handling, manifest submission, and tracking event retrieval. Edge cases — orders at the weight limit of a service, international shipments with EORI data, multiple items consolidated into a single shipment — should all be tested in sandbox before going live.

The transition from sandbox to production is typically straightforward once testing is complete — it’s usually a matter of switching API endpoint URLs and credentials from sandbox values to production values. Having a clear checklist of what to test in production (typically a small batch of real orders before enabling full automation) is part of the handover process.

If you need help with a custom API integration for your website or business application, I can help. I build bespoke API integrations for UK businesses. See API integration pricing or get in touch to discuss your project.

Need a custom integration built?

I build custom API integrations — Stripe, Companies House and bespoke data pipelines. Reliable, well-documented, no agency overhead.

Discuss your project →