QQ Mail

Overview

QQ Mail gives your server real post offices players walk up to. A sender composes a parcel from their own inventory, addresses it and pays a distance-based fee; the items leave their inventory and live in the database until the recipient collects them at the destination office, where they materialize exactly once — nothing is duplicated and nothing is silently destroyed.

It runs fully standalone. Code is escrow-encrypted; config.lua, locales/*.lua and the entire web/ UI stay open.

Requirements

• Required: ox_lib and oxmysql — both free
• An inventory — ox_inventory (or an ox-API-compatible fork) or qb-inventory
• A framework — QBCore, Qbox or ESX, auto-detected (absence is logged, not an error)
• Optional: ox_target / qb-target / qtarget if you prefer targeting over the [E] prompt

There is no hard dependency on any other QQ product. qq_market and qq_retail are detected at runtime if present, but nothing in the mail domain consumes them in this version.

Installation

1. Drop the qq_mail folder into your resources and add it to server.cfg after ox_lib, oxmysql and your framework. The folder must be named qq_mail.

ensure qq_mail

2. Start the server once. The schema installs itself and six post offices are seeded across the map. You should see:

[QQ Mail] v1.0.0 loaded

3. Grant yourself the admin ACE, then open /qqmail in game:

add_ace group.admin command.qqmail allow

Want player couriers? Register the courier item too — see Courier item below.

Database

Tables auto-create on first resource start — nothing to run. To install the schema by hand, run install.sql against your database before the first start (same DDL, safe to re-run):

mysql -u YOUR_USER -p YOUR_DATABASE < install.sql

Courier item

Player couriers carry a parcel as a real inventory item, so it needs registering — once, using the copy-paste snippet for your inventory in the bundled installation/ folder:

Restart that inventory resource afterwards. QQ Mail checks for the item at boot and prints a loud (non-fatal) error if it is missing — the courier board simply can't hand parcels out until it exists. Skip this step entirely if you only want recipients collecting their own parcels.

Addressing & delivery

Four ways to address a parcel — each can be switched off by an admin:

• Character name
• Phone number
• Citizen ID
• To bearer — no recipient, just an 8-character pickup code that whoever holds it can redeem

The post takes time. A parcel the recipient collects themselves is carried between offices — a few minutes next door, around twenty across the map — and shows when it will arrive. The rate is yours to set; setting it to zero makes delivery instant. That timer is what gives couriers something to sell: a courier hand-in is immediate.

Cash on delivery. The recipient pays on collection and the money reaches the sender; the sender pays a small commission up front. COD is all-or-nothing — it is structurally impossible to pay and receive only part of the goods.

Couriers.A sender can hand delivery to a courier and attach a reward. The job appears on a public board at every office; a player takes it, collects the parcel at the origin (a real item carrying the parcel's real weight) and hands it in at the destination to earn the reward. If nobody takes it in time an NPC delivers instead and the reward is burned; miss the delivery deadline and the parcel goes home with the reward refunded. A sender can recall a job nobody has taken.

Notifications & deadlines. Every office lists everything waiting for you anywhere— parcels at other offices appear dimmed and name where to collect them. A login notice counts what's waiting, and a pop-up fires if a parcel arrives while you're online. An uncollected parcel returns to its sender; an unclaimed return ends in lost & found. Goods are preserved at every step, and the collection window starts when the parcel arrives, not when it was sent.

The money model

Postage fees are a sink — the money leaves the economy. A courier reward is an escrow: the sender pays it at send, and it is either paid to the courier who delivers, burned if an NPC delivers, or refunded if the parcel comes home. It is never created from nothing.

The only thing that can create money is the optional NPC delivery subsidy, and it is disabled by default — it requires both a positive npcSubsidyPerDelivery and a configured non-player treasury account. Even then it is bounded by a per-office and a global daily cap, and by absolute ceilings compiled into the code that no in-game setting can raise.

Admin panel & commands

/qqmail opens an ACE-gated panel: offices, a blocked-items list, and 54 live-tunable settings across six groups. Changes apply with no restart; settings that can create money are hard-capped in code and require a confirmation. Everything a player does — sending, collecting, redeeming a code, taking a courier job — happens in the office window, with no commands to learn.

/qqmail                       # the admin panel — offices, blocked items, all 54 settings
/qqmail_create                # create an office at your current position
/qqmail_delete <id>           # remove an office, its blip and its ped
/qqmail_set <key> [value]     # set or clear one setting without the panel

command.qqmail is the master admin permission. Finer leaves let you split duties, and the server console always passes:

add_ace group.admin command.qqmail allow          # master

# optional finer-grained leaves
add_ace group.mod command.qqmail_create   allow
add_ace group.mod command.qqmail_delete   allow
add_ace group.mod command.qqmail_settings allow
add_ace group.mod command.qqmail_denylist allow

config.lua is the first-run default only — once the server has started, the admin panel is the source of truth and its values live in the database. The keys read once at boot (language, adapters, integrations, admin ACE, interaction mode, courier item name) are the exception; change one of those, then restart.

Localization

QQ Mail ships in 7 languages — English, Deutsch, Español, Français, Polski, Русский, Українська — switchable per player from the office window itself, a choice that persists per player. Set the server default with Config.language.

Troubleshooting

• No offices, no blips? The schema did not install. Check the console around the [QQ Mail] banner for an oxmysql error, and confirm oxmysql starts before qq_mail.
• /qqmail says you are not allowed? The ACE is not granted, or granted to a group your identifier isn't in. Try it from the server console first — console always passes.
• The office clerk floats or sinks into the ground? Adjust pedZOffset in /qqmail → Settings (world group). It applies live.
• Couriers can't pick anything up? The container item isn't registered — see Courier item. The boot error names the item it looked for.

Support

Licensed buyers get support via Tebex ticket and our community. The fastest channel is our Discord.