⚙️ Configuration

Everything on this page is config.yml. Run /mail reload after editing.

Mail mode

mail-mode: BOTH

In BLOCK mode only the bare /mail is disabled. The subcommands keep working.

Command aliases

command:
  aliases: []

Extra names /mail answers to. Empty by default. Set one if EssentialsX is fighting you for /mail.

Adding an alias takes effect on /mail reload. Removing one needs a restart: a live command cannot be pulled out of a running server without leaving every connected client holding a command tree that no longer matches.

Limits

mail:
  max-items-per-letter: 9
  subject-max-length: 32
  message-max-length: 512
  inbox-rows-per-page: 5
  cooldown-seconds: 30

max-items-per-letter must match the number of slots in compose.item-slots in menus.yml. Change one, change the other.

inbox-rows-per-page is capped at 5: a chest is six rows and the last one is the control bar.

Length limits and the cooldown apply to players only. Server mail ignores all three.

Send cost

mail:
  send-cost:
    amount: 0.0
    per-group: false
    bypass-permission: polaroidmail.bypasscost
    groups:
      default: 0.0
      # vip: 50.0

Charged to the sender on top of any money they attach. 0 disables it. Needs Vault.

With per-group: false everyone pays amount. With true the amount comes from the sender's LuckPerms primary group, and amount is ignored.

Group lookup goes: the player's group → default → amount. So adding a rank in LuckPerms never silently changes what anyone pays; an unlisted rank falls back instead.

Without LuckPerms installed, per-group does nothing and amount is used.

Delivery delay

mail:
  delivery-delay:
    seconds: 0
    per-group: false
    bypass-permission: polaroidmail.bypassdelay
    groups:
      default: 0
      # vip: 1800

How long a player-to-player mail sits in transit before the recipient can see it. Same group mechanics as the cost above.

Server mail is never delayed. A delayed mail is invisible in the inbox and does not count as unread until it lands.

Letter type

mail:
  letter-type: ITEM

A mail with no written message never produces a letter either way.

Blacklist

mail:
  blacklist:
    - minecraft:bedrock
    - minecraft:spawner
    - minecraft:trial_spawner
    - minecraft:command_block
    - minecraft:barrier

Items that can never be attached. Accepts custom-item ids too, e.g. nexo:crate_key.

Expiration

mail:
  expiration:
    claimed-after-days: 0
    unclaimed-after-days: 30
    return-to-sender: true
    return-subject: "Returned: %subject%"
    check-interval-minutes: 60

Two separate clocks, deliberately:

• claimed-after-days removes old receipts. Harmless — the contents are already in the player's hands. 0 keeps them forever.
• unclaimed-after-days stops mail waiting. This one destroys items and money if nobody claims them.

return-to-sender: true bounces expiring mail back to whoever sent it instead of deleting it. The bounce arrives as server mail, which is what stops it looping forever. Mail that was empty, or that came from the server in the first place, is just removed.

Every expiration run says out loud in console what it took. When a returning player asks where their mail went, that is the only thing that can answer.

check-interval-minutes: 0 disables cleanup entirely.

Welcome mail

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

Mail waiting on a player's first join. Its contents are the entry with that id in server-mail.yml.

Transfer log

log:
  enabled: true
  keep-days: 90
  keep-dismissed-days: 30
  inspect-entries: 200

Records every item and coin that moves through the post: sent, claimed, returned, expired, and anything staff did in /mail admin.

keep-dismissed-days is how long a mail a player deleted stays recoverable in the admin mirror. 0 keeps them forever.

inspect-entries caps both /mail admin player:<name> and /mail admin global.

Discord

discord:
  enabled: false
  webhook-url: ""

Mirrors mail activity into a channel. See Discord Logging for the whole section.

Economy

vault:
  enabled: true

Auto-disabled when Vault or an economy plugin is missing. When off, the money field disappears from the compose form.

Sounds

sounds:
  mail-received:
    key: entity.experience_orb.pickup
    volume: 1.0
    pitch: 1.0

Cues: mail-received, mail-sent, mail-claimed, inbox-open, inbox-close, page-turn, button-click, error.

Use sound keys (block.copper_chest.open), not the old enum names. Leave a key empty to silence that cue.

Notifications

mail:
  notifications:
    notify-if-online: true

Whether a connected player is told the moment mail arrives. The join notice is separate and always runs.

Dates

mail:
  date-format: "dd/MM/yyyy HH:mm"

A Java date pattern, used by %sent% and %claimed%. An invalid pattern silently falls back to the default rather than breaking every item.