📤 Server Mail

Mails written once in server-mail.yml and sent by id. This is how you do event rewards, compensations and the welcome mail without retyping anything.

Sending one

/mail servermail server:all      welcome
/mail servermail server:online   event-reward
/mail servermail player:Steve    compensation

Leave the id off and the compose screen opens instead, for a one-off.

Writing one

# Sender name shown on every server mail. Plain text; colour it in items.yml.
sender: "Server name"

mails:

  welcome:
    subject: "Welcome!"
    message:
      - "Glad to have you here."
      - ""
      - "Take this to get started."
    money: 0.0
    items:
      - BREAD:16
    commands: []
    mail-item: welcome

Field	Notes
`subject`	No length limit. Server mail skips the player limits
`message`	One line per list entry. Optional
`money`	Created, not taken from anyone. Needs Vault
`items`	`id` or `id:amount`. Custom ids work: `nexo:starter_sword`
`commands`	Run from console on claim. `%player%` is the claimer
`mail-item`	Which appearance to use. Optional
`free-slots`	Empty slots the player must have before claiming. Optional

A mail needs at least one of message, items or money. An entry with none of them is refused with errors.empty-server-mail rather than sending an empty envelope.

free-slots

event-reward:
  commands:
    - "excellentcrates key give %player% vote 3"
  free-slots: 3

Every mail already refuses to be claimed unless its own contents fit — that check simulates the delivery against the player's inventory, so it accounts for stacks merging. But it can only see what this plugin is carrying. A give run by another plugin is invisible to us until it has already happened, by which point a full inventory has dropped it on the floor.

free-slots closes that gap: the mail also demands that many plainly empty slots. The larger of the two requirements wins.

Only worth setting when commands delivers items from a plugin we cannot hook. Leave it out otherwise — an unnecessary requirement just makes a mail harder to claim for no benefit.

Its own look

mail-item: welcome makes the inbox use inbox-entry.pending-welcome and claimed-welcome from items.yml.

Leave the line out and it falls back to pending-server / claimed-server, like any other server mail. That is the whole mechanism — name a pair, define it in items.yml, done.

Commands on claim

commands:
  - "give %player% diamond 1"
  - "lp user %player% parent add vip"

They run from console the moment the mail is claimed.

Prefer items and money where you can. Those go through the mailbox properly: they are held inside the mail, refused rather than dropped when there is no room, returned if the mail expires, and recorded in the transfer log. A command does none of that — it fires once and whatever happens, happens.

Welcome mail

Turn it on in config.yml:

welcome-mail:
  enabled: true
  mail-id: welcome

It is posted on a player's first join ever, not on every login. mail-id points at any entry in mails:, so the welcome mail is just an ordinary server mail with a trigger attached.

Notes on broadcasts

server:all reaches everyone the server has ever seen, which on a large server is a lot of rows. It is a real write, not a chat message.
server:online reaches whoever is connected at that instant.
Server mail is never delayed, never costs anything, and cannot be blocked by a player.
A broadcast that reaches nobody reports errors.no-recipients and hands your attachments back.