Bug Reporting for Games With In-Game Mail

In-game mail looks simple from the player's side, a message arrives with items or gold attached and they click to claim it. Underneath, it is a delivery pipeline with several stages where value can be lost, the send, the queue, the delivery to the mailbox, the claim, and the expiry sweep that returns or deletes unclaimed mail. Attachments make it high stakes, because a bug at any stage can swallow an item or a stack of currency that the player considers as real as money. Lost-attachment reports are emotionally charged and notoriously hard to verify. This post is about capturing the mail id and attachment state so those reports stop being he said, she said.

Mail is a delivery pipeline

The mistake is treating mail as a single action when it is really a multi-stage pipeline. A message is composed and sent, it sits in a queue, it is delivered to the recipient's mailbox, the recipient opens and claims the attachments, and eventually an expiry process sweeps anything unclaimed. Each transition is a place where attachments can be dropped, double-claimed, or stranded. A bug that loses an item could be a send that recorded the wrong attachment, a delivery that arrived empty, a claim that succeeded on the client but failed on the server, or an expiry sweep that deleted before returning.

Because the failure could be in any stage, a player's report from the claim end cannot tell you where it actually broke. They only see that the item is missing now. To debug, you need to identify the specific piece of mail and then trace it through the pipeline to find the stage that failed. That means the report has to carry the mail id and enough attachment state to compare what was supposed to be attached against what actually arrived and what was actually claimed, across the whole journey.

Capture the mail id and attachment manifest

Every piece of mail should have a unique id, and that id is the key to the whole investigation. With it you pull the server record, the sender, the recipient, the send timestamp, the attachment list, and the claim and expiry status. Capture it at report time along with the player's relationship to the mail, whether they were the sender expecting it to leave their inventory or the recipient expecting it to arrive. The two roles experience a lost attachment as different complaints that only reconcile against the shared mail record.

Capture the attachment manifest as the player understood it, the items with their ids and stack counts and any attached currency. For the recipient, also capture what actually appeared in the mailbox versus what they expected, and for cash on delivery style mail, capture the price and whether it was paid. The manifest is what lets you check conservation, did the item leave the sender, did it arrive for the recipient, and was it claimed once or not at all. Without the manifest tied to the mail id, you are left taking the player's word for what was attached, which is exactly the dispute you cannot resolve.

Delivery, claim, and expiry state

The delivery and claim state is where you localize the failure. Capture whether the mail was delivered, whether it was opened, whether the attachments were claimed, and the timestamps of each. A claim that the client thinks succeeded but the server never committed is a classic source of lost items, and only the claim state on both ends reveals it. Likewise, capture whether the mail had an expiry and whether the expiry sweep had run, because expiry bugs that delete attachments instead of returning them to the sender are a quiet way to destroy value.

Cash on delivery and item-for-currency mail deserve extra attention, because they combine the attachment risk with a currency leg, and a bug can take the payment without releasing the item or release the item without collecting payment. Capture both the currency movement and the item movement for these. With delivery, claim, and expiry state captured against the mail id, a lost-attachment report stops being a mystery and becomes a question of which stage in a known pipeline failed, which you can answer from the record rather than from argument.

Setting it up with Bugnet

With Bugnet, the in-game report button captures your custom fields automatically, so a mail report arrives carrying the mail id, the sender and recipient, the attachment manifest, the player's role, and the delivery, claim, and expiry state without the player having to describe any of it. They just say their item never arrived, and the report already holds the manifest and the claim status behind that claim. If claiming mail triggers a crash, Bugnet captures the stack trace with the same mail context, so a crash mid-claim is tied to the exact piece of mail and its attachments.

Because Bugnet folds duplicate reports into one grouped issue with an occurrence count, a systemic delivery bug, say attachments vanishing on mail sent from a particular source, shows up as a climbing count on a single issue rather than a scatter of individual lost-item complaints. Filter the dashboard by your mail-related custom fields to isolate reports involving currency attachments or cash on delivery, and sort by occurrence to find the delivery paths that are leaking value. One dashboard shows you both the individual disputed mail and the systemic pattern of where your mail pipeline drops attachments.

Resolving lost-item disputes fairly

Lost-attachment reports are as much a trust problem as a technical one, because players are convinced an item they value is gone, and a slow or dismissive response burns goodwill fast. Capturing the mail id and manifest lets you resolve these fairly and quickly, you can confirm whether the item truly left the sender, whether it arrived, and whether it was claimed, then either restore it with confidence or explain clearly what happened. Either outcome is better than the back and forth that comes from having no record.

Build the habit that every mail report starts from the mail record, not the player's memory, and your support load on lost-item disputes drops because each case becomes a lookup. Over time, the occurrence counts point you at the pipeline stages that fail most, the claim race or the expiry sweep, so you can fix the source rather than endlessly restoring items one at a time. In-game mail carries real value, and treating every report as a traceable piece of mail is what keeps that value trustworthy.

Make mail traceable end to end

Aim for a mail system where any piece of mail can be traced from send to claim using its id, and where every report inherits that traceability. When the pipeline is observable, the difference between a delivered, claimed, and expired item is a field lookup rather than a guess, and that observability is what lets you stand behind your economy when players ask what happened to their attachment.

As your game adds new mail sources, system rewards, event payouts, player gifts, each is a new entry point into the pipeline and a new place for attachment bugs to appear. Keeping the mail id and attachment state on every report means new sources are debuggable from day one rather than after a wave of lost-item complaints. A mail system players trust to carry their gold and gear is one where nothing moves without leaving a record you can follow.

In-game mail carries real value through several stages. Capture the mail id and attachment manifest, and lost-item disputes become a lookup instead of an argument.