canonical: https://jentic.com/apis/royalmail.com/royalmail

# Royalmail ChannelShipper & Royal Mail Public API

Import your orders, retrieve your orders and generate labels. The API exposes 9 endpoints secured with apiKey authentication.

## For AI agents

Programmatically create orders, retrieve pageable list of orders. Covers 9 operations with apiKey authentication.

## Scope

Does not handle payments, crm, or developer tools - use for communications only.

## Capabilities

- Create orders
- Retrieve pageable list of orders
- Set order status
- Delete orders
- Monitor ChannelShipper & Royal Mail Public API operational status and events

## Use cases

### Communications Operations

Use the ChannelShipper & Royal Mail Public API to perform communications operations programmatically. The API provides 9 endpoints covering core functionality including create orders, retrieve pageable list of orders, retrieve pageable list of orders with details.

Example prompt: Call POST /orders to create orders

### Automated Rate Limits Management

Automate rate limits operations by combining multiple ChannelShipper & Royal Mail Public API endpoints. Agents can retrieve pageable list of orders and then retrieve pageable list of orders with details in a single workflow.

Example prompt: Call GET /orders to retrieve pageable list of orders, then verify the result

### AI Agent Integration via Jentic

AI agents discover and call ChannelShipper & Royal Mail Public API endpoints through Jentic without managing credentials directly. An agent searches for the required operation by intent, receives the matching endpoint schema, and executes the call with Jentic-managed authentication. This eliminates the need to read API documentation or handle apiKey tokens manually.

Example prompt: Search Jentic for 'create orders', load the operation schema, and execute with Jentic-managed credentials

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/orders` | Create orders |
| GET | `/orders` | Retrieve pageable list of orders |
| GET | `/orders/full` | Retrieve pageable list of orders with details |
| PUT | `/orders/status` | Set order status |
| GET | `/orders/{orderIdentifiers}` | Retrieve specific orders |
| DELETE | `/orders/{orderIdentifiers}` | Delete orders |
| GET | `/orders/{orderIdentifiers}/full` | Retrieve details of the specific orders |
| GET | `/orders/{orderIdentifiers}/label` | Return a single PDF file with generated label and/or associated document(s) |

## Key resources

- **Rate Limits** — <p>Exceeding the following rate limits will result in a 429 error:</p><table class='security-details
- **Version** — Operations related to Version
- **Orders** — Operations related to Orders
- **Labels** — Operations related to Labels

## Why Jentic

- **Setup:** Wiring the ChannelShipper and Royal Mail Public API by hand means passing your key in the Authorization header and building your own pagination and status handling across the orders collection. Through Jentic you install once, import the ChannelShipper and Royal Mail Public API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** This API puts the order identifiers in the URL path (`/orders/{orderIdentifiers}`), so a rule can pin your agent to specific orders: it can read those orders and nothing else. You choose the operations it may call, so order deletion and status changes are not included unless you add them.
- **Credential handling:** Your Royal Mail API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create shipping orders' or 'check an order's status', and Jentic returns the matching operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Twilio** — Alternative communications API
- **Sendgrid** — Alternative communications API
- **Pusher** — Complementary communications API

## FAQ

### What authentication does the ChannelShipper & Royal Mail Public API use?

The ChannelShipper & Royal Mail Public API uses an API key passed in the `Authorization` header. Through Jentic, these credentials are stored encrypted in your Jentic One instance and injected at execution time, so raw secrets never enter the agent context.

### Can I create orders with the ChannelShipper & Royal Mail Public API?

Yes. Use the POST /orders endpoint. The API returns structured JSON responses that agents can parse and act on directly.

### What are the rate limits for the ChannelShipper & Royal Mail Public API?

Rate limits are not specified in the OpenAPI spec. Check the vendor documentation for current limits. Through Jentic, rate limiting is handled automatically with retry logic built into the execution layer.

### How do I create orders through Jentic?

Install the Jentic SDK with pip install jentic, authenticate through Jentic One, the self-hosted execution layer, then search for 'create orders'. Jentic returns the matching ChannelShipper & Royal Mail Public API operation with its input schema. Load the schema and execute the call - credentials are injected automatically.

### How many endpoints does the ChannelShipper & Royal Mail Public API have?

The ChannelShipper & Royal Mail Public API exposes 9 endpoints covering rate limits, version, orders operations.

### Can I limit what my agent is allowed to do with the Royal Mail Click and Drop API?

Yes. Because Jentic One is self-hosted, you decide which operations your agent may call, so you can grant read access through GET /orders and GET `/orders/{orderIdentifiers}` while withholding POST /orders, PUT `/orders/status`, and DELETE `/orders/{orderIdentifiers}.` Since the order identifiers sit in the URL path, your own rules can pin the agent to specific orders, letting it read those and nothing else. Order deletion and status changes stay out of reach unless you explicitly add them.