Delivery is the process of carrying mail from sender to the recipient and returning back, with or without a reply.

Route

Delivery route has 5 positions:

• Sender
• Sender transition point
• Mail Hub
• Recipient transition point
• Recipient

It looks similar to a flight of an airplane: courier ascends to the sender transition point, travels to the hub then travels to the recipient transition point, then descend to the recipient. Return back home follows the same logic but reversed.

Ascends and descends are the only parts of a courier's flight that happen in the world. They use regular entity pathfinding to try to reach the target position of a phase.

• When the chunk with a courier unloads - delivery will continue in the background regardless of the phase
• If the chunk becomes loaded again - courier will return to the world
• When a courier finishes delivery in an unloaded chunk - it will be spawned next time that chunk is loaded

Route schematic and courier visibility

Mail Hub

Couriers do not fly straight from A to B. They must go through a virtual point called Mail Hub.

Hub is where many important decisions and checks are made - recipient existence, distance calculation (influencing flight duration), handling payback.

Location

Hubs are located in a 1024 block grid, at Y320.

When delivery starts - hub nearest to the sender is chosen:
If sender is at X720, Z1337 and recipient is at X999999, Z999999 - mail hub at X1024, Z1024 will be chosen.

Mail hub location will impact the direction courier flies off to, delivery duration and other delivery properties.

Duration

Delivery duration is based on distance between the sender, recipient and a chosen mail hub.
Duration uses the following formula:
duration = (distance from sender to hub + distance from recipient to hub) / courier travel speed
By default, courier travel speed is 20 blocks/second.

For the duration calculation, distance from an address to mail hub is capped at 5000 blocks, so distant deliveries wouldn't take too much time.

All this only applies to the traveling phases of a delivery, when a courier is in a background.

Payback

Delivery involving payback is handled differently from usual deliveries:

Instead of being delivered straight to the buyer, mail with payback request will be kept at Mail Service and the courier will immediately return back to seller.
Simultaneously, a payback box will be sent to the buyer by a service courier.

Mail with request will remain at Mail Service for the duration selected on the payback tag, awaiting payback from the buyer.
If buyer does not send payback package in time, mail with request will be returned back to the seller.

When buyer sends required items, Mail Service does some checks, and, if all is fine, sends the original mail to the buyer using the same courier.
Simultaneously, buyer's payback package will be sent to the seller by a service courier.

Payback delivery

Player can cancel a payback request by sending a payback tag to Mail Service.
Last request will be cancelled and mail will return to the sender.

Commands

Delivery can also be started using the /envelope send <item[recipient]> [sender] command.

/envelope send envelope:letter[envelope:mail_recipient={type:"player", name:"Steve"}] {type:"player", name:"mortuusars"}

• envelope:mail_recipient address must be set
• sender address is optional, if omitted - receiver will see the sender as "Unknown"
• any item can be sent, regardless if it has #envelope:mailable tag or not