Configuration

Courier uses HOCON format for its main configuration file located at config/courier/config.conf.

Main Configuration

# Courier Mail System Configuration

# Rate limiting settings
rateLimits {
    # Maximum messages per day per player
    messagesPerDay = 50

    # Maximum messages per hour per player
    messagesPerHour = 10

    # Maximum messages per minute per player
    messagesPerMinute = 3

    # Maximum recipients per message
    maxRecipients = 10
}

# Mail expiration settings
expiration {
    # Days until unclaimed mail expires (0 = never)
    defaultDays = 30

    # Hours between cleanup runs
    cleanupIntervalHours = 1
}

# GUI settings
gui {
    # Items per page in inbox
    itemsPerPage = 45

    # Allow sending to self (useful for testing)
    allowSendToSelf = false
}

Rate Limits

Rate limits prevent spam and protect server performance:

Setting	Default	Description
`messagesPerDay`	50	Max messages a player can send per day
`messagesPerHour`	10	Max messages per hour
`messagesPerMinute`	3	Max messages per minute
`maxRecipients`	10	Max recipients per message

Mail Expiration

Configure how long mail is kept:

expiration {
    # Set to 0 to never expire mail
    defaultDays = 30

    # How often to check for expired mail
    cleanupIntervalHours = 1
}

Messages Configuration

Customize all user-facing messages in config/courier/messages.json:

{
  "prefix": "<gray>[<gold>Mail</gold>]</gray> ",
  "errors": {
    "cannotSendToSelf": "<red>You cannot send mail to yourself!</red>",
    "playerNotFound": "<red>Player <yellow>{player}</yellow> not found!</red>",
    "rateLimited": "<red>You are sending too fast! Try again in {seconds}s</red>",
    "presetNotFound": "<red>Preset <yellow>{preset}</yellow> not found!</red>"
  },
  "success": {
    "mailSent": "<green>Mail sent to <yellow>{recipient}</yellow>!</green>",
    "block": "<green>Blocked <yellow>{player}</yellow></green>",
    "unblock": "<green>Unblocked <yellow>{player}</yellow></green>"
  },
  "login": {
    "header": "<gold>━━━━━━━━━━━━━━━━━━━━━━━━━━━</gold>",
    "unread": "<yellow>You have <gold>{count}</gold> unread message{plural}!</yellow>",
    "hint": "<gray>Use <yellow>/mail</yellow> to view your inbox</gray>",
    "footer": "<gold>━━━━━━━━━━━━━━━━━━━━━━━━━━━</gold>"
  }
}

MiniMessage Formatting

All messages support MiniMessage formatting:

Colors

<red>, <green>, <blue>, etc.
<#FF5555> (hex colors)
<gradient:red:blue>text</gradient>

Styles

<bold>, <italic>, <underlined>
<strikethrough>, <obfuscated>
<reset> to clear formatting

Placeholders

Available placeholders in messages:

Placeholder	Description
`{player}`	Player name
`{recipient}`	Recipient name
`{count}`	Number count
`{plural}`	”s” if count > 1
`{seconds}`	Seconds remaining
`{preset}`	Preset ID
`{error}`	Error message

Ceremony Integration

Courier depends on Ceremony for storage and cross-server communication. Configure Ceremony in config/ceremony/config.conf:

# Database storage for mail
storageType = "MONGO_DB"
storageUrl = "mongodb://localhost:27017"

# Cross-server communication
messageBus {
    type = "REDIS"
    serverId = "server-1"
    redisAddress = "redis://localhost:6379"
}

# Player data storage
playerData {
    backend = "CARDINAL_COMPONENTS"
    caching = true
}

Storage Types

Type	Best For
`JSON`	Development/testing
`SQLITE`	Single server, simple setup
`MONGO_DB`	Production, multi-server
`MARIA_DB`	Alternative to MongoDB

Message Bus Types

Type	Description
`NONE`	Single server only
`REDIS`	Popular, feature-rich
`NATS`	Lightweight, fast

Permissions

Courier uses the Fabric Permissions API. Default permissions:

Permission	Default	Description
`courier.mail.use`	true	Use `/mail` command
`courier.admin`	op (4)	Admin commands

Configure with LuckPerms or similar:

/lp group default permission set courier.mail.use true
/lp group admin permission set courier.admin true

Preset Directory

Package presets are stored in config/courier/presets/:

config/courier/presets/
├── starter_kit.json
├── welcome_gift.json
├── rare_pokemon.json
├── mining_supplies.json
├── battle_ready.json
└── event_reward.json

See Preset Packages for creating custom presets.

Reloading Configuration

Reload configurations without restarting:

/mailadmin reload

This reloads:

Package presets
Messages configuration