ParcelystParcelyst

Documentation

Guides & API Reference

Everything you need to integrate with Parcelyst — from email forwarding setup to programmatic API access.

Email Forwarding Setup

Forward your shipping confirmation emails to Parcelyst so we can track your parcels automatically. Your unique forwarding address can be found in your Settings.

Gmail

Option A — Forward all emails

1

Open Gmail and click the gear icon, then See all settings.

2

Go to the Forwarding and POP/IMAP tab.

3

Click Add a forwarding address and paste your Parcelyst forwarding address.

4

Gmail will send a confirmation email to your Parcelyst address. We'll automatically confirm it — refresh the page after a few seconds.

5

Select Forward a copy of incoming mail to and choose your Parcelyst address. Click Save Changes.

Option B — Forward only shipping emails (recommended)

1

First, add your Parcelyst forwarding address using Option A steps 1–4 above (you need to register the address before creating filters).

2

In Gmail, click the search bar and select Show search options (the icon on the right).

3

In the From field, enter sender addresses for your shipping emails, e.g. shipment-tracking@amazon.co.uk. You can use OR to match multiple senders.

4

Click Create filter, then tick Forward it to and select your Parcelyst address. Click Create filter.

TipIf you use Option A, you can set it to “Keep Gmail's copy in the Inbox” so your emails stay in Gmail as usual.

Outlook / Hotmail

Automatic forwarding

1

Go to outlook.live.com and click the gear icon, then View all Outlook settings.

2

Navigate to Mail → Forwarding.

3

Tick Enable forwarding and paste your Parcelyst forwarding address.

4

Optionally tick Keep a copy of forwarded messages to keep emails in your Outlook inbox.

5

Click Save.

Using rules — forward specific senders only

1

Go to Settings → Mail → Rules.

2

Click Add new rule and give it a name, e.g. “Parcelyst forwarding”.

3

Set the condition to From and enter your shipping email senders (e.g. Amazon, DPD, Royal Mail).

4

Set the action to Forward to and paste your Parcelyst forwarding address.

5

Click Save.

Y!Yahoo Mail

Automatic forwarding

1

Open Yahoo Mail and click the gear icon, then More Settings.

2

Go to Mailboxes and select your email address.

3

Scroll down to Forwarding and paste your Parcelyst forwarding address.

4

Click Verify. Yahoo will send a verification code — check your Parcelyst dashboard for it, or wait a moment and click Save.

Using filters

1

Go to Settings → More Settings → Filters.

2

Click Add new filters.

3

Set From to contain your shipping sender addresses.

4

Under Then, select Forward to and enter your Parcelyst forwarding address.

5

Click Save.

Apple Mail (iCloud)

Setting up rules

1

Go to icloud.com/mail and sign in.

2

Click the gear icon in the bottom left and select Rules.

3

Click Add a Rule.

4

Set the condition, e.g. is from a specific sender like your retailer's shipping address.

5

Set the action to Forward to and paste your Parcelyst forwarding address.

6

Click Done, then Done again to save.

TipiCloud Mail doesn't support blanket forwarding of all emails. You'll need to create a rule for each sender or use a keyword-based condition like “subject contains tracking”.

Other Email Clients

Most email providers support forwarding. The general steps are the same:

1

Find your email provider's forwarding or rules settings (usually under Settings → Mail → Forwarding or Rules).

2

Add your Parcelyst forwarding address as the destination. You can find it in your Settings.

3

If prompted, verify the forwarding address by confirming a code or clicking a link.

4

Optionally set up a filter so only shipping/tracking emails are forwarded.

Common shipping sender addresses

shipment-tracking@amazon.co.ukauto-confirm@amazon.co.uknoreply@dpd.co.uknoreply@evri.comdonotreply@royalmail.comtracking@dhl.comnoreply@ups.com
TipNeed help? Email us at info@forgefreelancesolutions.com and we'll walk you through it.

Introduction

The Parcelyst REST API lets you programmatically query your tracked parcels and their timeline events. All endpoints return JSON and require authentication via an API key.

Base URL

/api/v1

Authentication

All API requests must include your API key in the Authorization header as a Bearer token.

bash
curl -H "Authorization: Bearer fio_your_api_key_here" \
  https://your-domain.com/api/v1/parcels

Generate API keys from your Settings page. Keys are shown once on creation — store them securely.

Error responses

401Missing, invalid, or revoked API key
403API access requires a paid plan
429Rate limit exceeded

Rate Limits

The API allows 60 requests per minute per user. Rate limit status is returned in response headers.

HeaderDescription
X-RateLimit-LimitMax requests per window (60)
X-RateLimit-RemainingRemaining requests in current window
X-RateLimit-ResetSeconds until the window resets

Account

GET/api/v1/account

Returns your API account details, including your unique forwarding email address for inbound parcel emails.

Example Response

json
{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "plan": "starter",
    "forwardingAddress": "abc123def456@inbound.parcelyst.com"
  }
}

Try it

Enter your API key in the bar above to send requests.

List Parcels

GET/api/v1/parcels

Returns a paginated list of your parcels, optionally filtered by status, carrier, or search query.

Query Parameters

status

string

Filter by parcel status. Comma-separated for multiple: in_transit,delivered

carrier

string

Filter by carrier code: royal_mail, evri, dpd, ups, dhl, amazon_shipping

search

string

Search by tracking number (partial match).

page

integer

Page number (default: 1).

page_size

integer

Results per page, 1–100 (default: 25).

Example Response

json
{
  "data": [
    {
      "id": "a1b2c3d4-...",
      "trackingNumber": "RM123456789GB",
      "carrier": "royal_mail",
      "normalizedStatus": "in_transit",
      "eta": null,
      "createdAt": "2026-02-10T08:00:00.000Z",
      "lastEventAt": "2026-02-14T12:30:00.000Z",
      "daysInTransitCached": 4
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 25,
    "total": 42,
    "totalPages": 2
  }
}

Try it

Enter your API key in the bar above to send requests.

Get Parcel Detail

GET/api/v1/parcels/:id

Returns a single parcel with its full timeline of events.

Path Parameters

idreq

uuid

The parcel ID (UUID).

Example Response

json
{
  "data": {
    "parcel": {
      "id": "a1b2c3d4-...",
      "trackingNumber": "RM123456789GB",
      "carrier": "royal_mail",
      "normalizedStatus": "in_transit",
      "createdAt": "2026-02-10T08:00:00.000Z",
      "lastEventAt": "2026-02-14T12:30:00.000Z"
    },
    "events": [
      {
        "id": "e5f6g7h8-...",
        "rawStatus": "Parcel is in transit",
        "normalizedStatus": "in_transit",
        "eventTime": "2026-02-14T12:30:00.000Z",
        "location": "London Hub",
        "source": "carrier_poll"
      }
    ]
  }
}

Try it

Enter your API key in the bar above to send requests.