Receiving
- Carrier detection, field locks, sender, photo, damaged flag and custom fields
- Expected packages and purchase orders from CSV, a folder or a URL, with auto-matching
- Bulk receive without barcodes; 2D barcode parsing
Raptool Parcel 1.2 · Inbound mailroom tracking
Every parcel, followed
Every parcel, followed
from the dock to the desk.
Raptool Parcel takes a package from the carrier’s hand to the recipient’s signature: receive it, shelve it, send it out on a delivery route, hand it over and report on it. A web app for the desk, a mobile app that works offline and a PHP API work from the same data.
StoryboardThe life of
The life of
a parcel.
Seven scenes from the loading dock to the final report. Each one shows the real screen behind it.
01At the dock
Scan the label.
The rest fills itself in.
A courier hands over the parcels. One scan of the carrier label identifies the carrier, and if the package was expected, the details come from the purchase order or delivery list.
- Carrier detected from the barcode, with fields you can lock for a whole stack
- Expected packages and purchase orders pre-fill the receive form
- Reads long 2D barcodes, including ANSI MH10.8 data
- Bulk receive many packages at once without barcodes
02On the shelf
A place, a label
and a note for every parcel.
Choose the shelf, add a photo or a damaged flag, print the label. The recipient is told by email and, when you set it up, by text message.
- Shelf, package type, photo, damaged flag and custom fields at receive
- Label printing with the tracking barcode
- Email notification from your own template
- Text messages through Twilio, 46elks or your own gateway
03Waiting
Nothing sits
forgotten.
Reminders go out on their own for packages that stay undelivered. If a recipient is away, a rule forwards the package to a cover or holds it until they are back.
- Follow-up reminders by email and text, sent automatically or by hand
- Forwarding and hold rules with date ranges
- Days waiting shown on every open package, with a Delayed filter
- Custom statuses such as “Waiting for customs”
04On the route
From the mailroom
to every stop.
A courier scans the route barcode on a handheld and works stop by stop. Several packages can travel together in a pouch to another mailroom.
- Scan a ROUTE barcode to start a run; copy routes and read run history
- Checkpoints: scan a location barcode, add a photo or signature if needed
- Pouches with a manifest, sealed, received and signed for once
- Works offline; actions queue on the device and sync when the connection returns
05Handed over
Proof of delivery,
kept with the parcel.
The recipient signs on the screen, or the courier scans an employee ID card instead. A photo is optional, and every step stays in the package history.
- One signature can cover a whole batch of packages
- Deliver by ID card: scan a badge to find and hand over their packages
- Optional delivery photo
- Full transaction history on every package
06Desk to desk
Inside the building,
the same careful flow.
Staff send a package request to a colleague. The mailroom collects it by scanning the label, and from there it follows the normal delivery flow.
- Send internal: a request with its own INT tracking number and label
- Requester role for people who may only send and follow their own requests
- The sender gets an email when the package is delivered
- Internal and inbound packages are kept apart in lists and reports
07Reports and control
See what was late
and why.
Set delivery targets in hours, follow on-time delivery and read the activity log. Run several mailrooms from one install and protect sign-in with a second step.
- Delivery targets (SLA) per carrier and package type, with on-time reporting
- Reports with date, carrier and route filters, exported as CSV
- Activity log of sign-ins, settings changes and package actions
- Multiple mailrooms; two-step sign-in (TOTP), inactivity timeout and account lockout
One systemEverything
Everything
in one system.
The parcel moves from the dock to the desk. The web app, the mobile app and the API all work on the same records, so every stop is visible to everyone who needs it.
StartDockThe carrier hands over the parcels.
MailroomReceive, shelve, label, notify.
RouteStop by stop, with checkpoints.
DestinationDeskSigned for, in the history.
Web appDesk and admin for PCs and tablets.
Mobile appPhones and handhelds. Works offline.
APIPHP 8 REST, JSON. Used by both apps.
Direction: dock to desk · illustration
Features in 1.2What is
What is
in the box.
The 1.2 release, grouped the way the mailroom works.
Delivering
- Signature, delivery photo or ID card
- Deliver by person, by route or by scanning
- Checkpoints with optional photo and signature
Tracking
- Custom statuses on top of the five base statuses
- Pouches and internal packages
- Saved views with your own filters and columns
Notifications
- Email from templates
- SMS via Twilio, 46elks or your own gateway
- Scheduled and manual reminders
Multi-site
- Several mailrooms from one install
- Per-mailroom overrides for delivery targets, signatures and reminders
- Forwarding and hold rules with mailroom filters
Security
- Two-step sign-in (TOTP) with recovery codes
- Inactivity timeout and lockout after 8 failed sign-ins
- Single sign-on (SAML 2.0)
Admin
- Five fixed roles
- Status and rule editors
- Activity log with CSV export
Mobile and offline
- Installable app for phones and handhelds
- Every action queues offline and syncs later
- Sync problems can be retried or discarded
DocumentationMore
More
information.
Installation, setup and the API in short. Pick a topic.
Install on XAMPP (Windows)
Raptool Parcel is plain PHP 8 with MySQL or MariaDB, vanilla JavaScript, no framework, no Composer and no build step.
The easy way
- Start Apache and MySQL in the XAMPP Control Panel.
- Unzip
raptool-parcel.zipanywhere, then double-clickinstall.bat.
The installer copies the app to C:\xampp\htdocs\parcel, creates the database and a database user with a random password, writes api/config.php, offers demo data and opens the app. If XAMPP is somewhere else, run install.bat -Xampp D:\xampp. Running it again later upgrades an existing install and keeps your config and data.
By hand
- Copy the
raptool-parcelfolder toC:\xampp\htdocs\parcel. - In phpMyAdmin or the MySQL shell, create the database and a user.
- Import
db/schema.sql, thendb/seed.sql. - Copy
api/config.sample.phptoapi/config.phpand enter the database password. The timezone defaults to Europe/Stockholm. - Open
http://localhost/parcel/and sign in with[email protected]/ChangeMe123. Change the password straight away under Settings, Your account.
CREATE DATABASE parcel CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'parcel'@'localhost' IDENTIFIED BY 'choose-a-password';
GRANT ALL ON parcel.* TO 'parcel'@'localhost';Demo data (empty database only)
C:\xampp\php\php.exe C:\xampp\htdocs\parcel\db\seed_demo.phpAdds sites, two routes, 14 people, about 130 packages, five staff sign-ins and a second mailroom. The password for all demo staff is Password1.
Upgrade from version 1.1
Keep your config and data. Copy the new files over the old ones, but leave api/config.php in place. Then upgrade the database in one of two ways.
Option A: the web upgrade page
From the server machine, open http://localhost/parcel/upgrade.php. The page runs the database migrator and prints what it did.
Option B: the command prompt
C:\xampp\php\php.exe C:\xampp\htdocs\parcel\db\migrate.phpIf the migrator has not run you will see “needs upgrade” errors: the database schema is older than the code expects. Run the upgrade again.
Finally, bump the ?v= numbers in web/index.html and mobile/index.html so browsers fetch the new CSS and JS, and bump CACHE in mobile/sw.js so handhelds pick up the new version.
First-time setup
Everything is configured under Settings in the web app. Start with one mailroom and add more as you expand.
- Company: name, contact and logo, used in the header, labels and emails
- Mailrooms: name, shelves and optional overrides
- Statuses: custom labels on top of the five base statuses
- Delivery targets: hours to deliver by, per carrier or type
- Reminders: timing, repeats and message template
- Text messages: Twilio, 46elks or your own gateway
- Checkpoints: photo and signature required, optional or off
- Expected packages: manual, CSV import or scheduled import
- Security: two-step sign-in, inactivity timeout, purge of deleted packages
- Shelves and carriers
- Sites and locations: buildings and floors; “Paste a list” imports them
- Routes: ordered stops for couriers
- People: one by one or pasted as a list
- Custom fields (optional): up to 10 text, 5 number and 5 date fields each for packages and people
- Notification email: edit the template
- Users: roles, and optional mailroom limits
- Field names (optional): for example Package to Parcel
- Single sign-on (optional)
- Activity log: view and export as CSV
- Barcodes: print sheets for locations and routes
Roles and permissions
Five fixed roles. An admin can limit each user to one or more mailrooms.
| Role | Can do |
|---|---|
| Requester | Sign in, send desk-to-desk package requests, see and print labels for their own, follow delivery status. Least privilege. |
| Viewer | Look at packages and reports only. Cannot take any actions. |
| Courier | Send out, hold, release and deliver (with signature). Can log checkpoints and start routes. |
| Mailroom | Receive, edit, notify, return to sender, reopen. Manage people and forwarding rules. Can set up expected packages. |
| Admin | Everything, including settings, users, mailrooms, and deleting packages. |
Parcel Mobile on handhelds and phones
Open https://<your-server>/parcel/mobile/ on the device, sign in, and choose Add to home screen or Install app.
Scanning
- Hardware scanners in keyboard mode (Zebra DataWedge, Honeywell and similar) work out of the box. Set the scanner to send Enter after each scan.
- On Android Chrome, the camera button opens a barcode scanner.
LOC-<id>logs your location,ROUTE-<id>starts a route run,POUCH-<id>opens a pouch.
Work in the field
- Checkpoints with optional photo and signature.
- Routes: stops, packages at each stop, deliveries and failures, and a finished run with its duration.
- Pouches: open, add by scan, seal, arrive, deliver with one signature.
- ID card delivery when it is turned on.
Offline
Every change goes into a queue on the device and syncs when the connection returns; the home screen shows what is waiting. Anything the server rejects, for example a package someone else already delivered, appears under Sync problems, where it can be retried or discarded.
HTTPS is required for installing the app, the offline cache and the camera. localhost is the only exception.
Expected packages and purchase orders
- Add manually under Settings, Expected packages: tracking number, PO number, expected date and sender.
- Import a file: upload a CSV. Column order does not matter and unknown columns are ignored. Recipients are matched by email or name.
- Scheduled import from a folder or HTTPS URL. A local folder on the server works best. SFTP is not built in; drop files into the folder instead.
When a package with a matching tracking or PO number arrives at Receive, an expected package is linked and closed. An expected PO is linked but stays open, so you can receive many packages against one order and close it by hand.
CSV format
tracking,carrier,sender,recipient,expected,note
SE1234567890,PostNord,Dustin,[email protected],2026-09-25,Urgent
PO-002,DHL,Würth,[email protected],2026-09-26,Pouches and internal packages
Pouches
A pouch is a batch of packages for another mailroom, location or person, sent with a single signature.
- Open a new pouch and choose where it goes.
- Add packages by barcode, one scan at a time.
- Seal it. The app locks it and marks the packages en route.
- The destination mailroom receives it and the packages are ready for delivery.
- The courier delivers everything inside with one signature.
Each pouch has a barcode (POUCH-<id>) and a manifest of every package inside.
Internal packages
Staff with the Requester role or higher can send a package request from one person to another inside the building.
- Click Send internal and fill in sender, recipient, type and a note.
- The app prints a label with the tracking number
INT-<n>. - The mailroom collects it by scanning the label.
- It then goes through the normal delivery flow.
- On delivery, the sender gets an email.
What is and is not included
The feature set follows the Wasp Package Tracker 1.2 manual.
Included
- Receive with carrier detection, photo, damaged flag, custom fields and label printing
- Search with advanced filters and saved views
- En route, hold, release and deliver, with batch signature
- Details page with history, edit, print and media gallery
- Email and SMS notification with templates
- Dashboard and reports with CSV export
- Single sign-on (SAML), multi-mailroom, custom statuses
- Expected packages, reminders, checkpoints, pouches, internal packages
- Two-step sign-in, forwarding and hold rules, activity log, delivery targets
Not included
- Smart lockers
- USB signature pads (use a photo or the mobile camera instead)
- Asset tracking
- SFTP scheduled imports (drop files into a folder instead)
- Wasp’s colour themes (light and dark mode instead)
- Wasp’s user groups (five fixed roles instead)
Troubleshooting
| Symptom | What to do |
|---|---|
| “Needs upgrade” errors | The database is older than the code. Open upgrade.php on the server or run db/migrate.php. |
| Cannot install the mobile app, no offline cache or camera | These need HTTPS. Give Apache a certificate; localhost is the only exception. |
| Scanner types but nothing happens | Configure the hardware scanner to send Enter after each scan. |
| New version does not show after upgrade | Bump the ?v= numbers in the two index.html files and CACHE in mobile/sw.js. |
| Item under Sync problems | The server rejected a queued action, for example a package someone else already delivered. Retry or discard it. |
| Emails open in your own mail program | Server email is off by default. Enable Send notifications from the server and fill in SMTP. Microsoft 365 needs SMTP AUTH enabled for the mailbox. |
| Text message failed | A failed text never fails the package action. The failure is logged in the package history. |
| Locked out | Eight failed sign-ins lock an account for 15 minutes. An admin can reset a user’s two-step sign-in under Settings, Users. |
| API answers 401 with a Bearer token sent | If Apache strips the Authorization header, send X-Auth-Token: <token> instead. |
| Reminders do not go out | The tick job runs on page loads, throttled to every 10 minutes. For reliable timing, add a Windows Scheduled Task for api/cron/tick.php. |
API overview
Base URL /parcel/api/index.php/. JSON in and out. Send Authorization: Bearer <token> from POST auth/login. Send X-Mailroom: <id> to limit a request to one mailroom. Roles order: requester < viewer < courier < mailroom < admin.
| Method and path | Min role | Purpose |
|---|---|---|
POSTauth/login | none | Sign in; returns a token and the user |
GETbootstrap | viewer | Settings, sites, routes, mailrooms, statuses and version |
GETpackages | viewer | List with status, search, carrier, site, route and date filters |
GETpackages/lookup?tracking= | viewer | Find a package, and its expected match, by tracking number |
GETpackages/{id} | viewer | One package with events, photo and signature |
POSTpackages | mailroom | Receive a package |
PATCHpackages/{id} | mailroom | Edit receive fields or status; logged as an event |
POSTpackages/actions | courier | enroute, hold, release, deliver, return, reopen, transfer, arrive, checkpoint and more |
POSTpackages/notify | mailroom | Build one email per recipient from the template |
POSTpackages/remind | mailroom | Send reminders now |
POSTpackages/bulk | mailroom | Receive 1 to 200 packages at once |
POSTpackages/parse-scan | viewer | Parse a 2D or ANSI MH10.8 scan into tracking, carrier and recipient matches |
GETrecipients/by-badge?badge= | courier | Person and open packages for an ID card |
GETexpected | viewer | Expected packages and purchase orders |
POSTexpected/import | mailroom | Import a CSV of expected items |
GETpouches | viewer | Pouches sent from or addressed to the mailroom |
POSTpouches/{id}/seal | mailroom | Lock a pouch; its packages become en route |
POSTpouches/{id}/deliver | courier | Deliver every package inside with one signature |
POSTroutes/{id}/runs | courier | Start a route run |
PATCHroute-runs/{id} | courier | Record progress or finish a run |
POSTinternal | requester | Create a desk-to-desk request |
GETmailrooms | viewer | Mailrooms the user belongs to |
GETreports/summary | viewer | KPIs, per-day and per-carrier figures, on-time delivery |
GETaudit | admin | Activity log, filterable |
Mobile writes accept an optional client_ref, so a replayed offline action returns the first result and never repeats the work.