# ============================================================
# MailboxGUI Scheduled Mail
# ============================================================
# File location after the plugin starts:
# plugins/MailboxGUI/scheduled-mail/scheduled-mail.yml
#
# This file lets server owners schedule MailboxGUI mail to send
# at a specific server date/time. Mail is sent through the same
# MailboxGUI systems as admin/API mail, so normal recipient checks,
# notifications, expiration, package limits, COD validation, item
# templates, and Shared Admin Inbox COD return behavior still apply.
#
# Main layout:
#
# scheduled-mail:
#   task-id:
#     enabled: true/false
#     type: PAPER_LETTER | BOOK_LETTER | PACKAGE | MONEY
#     from: "&a&lServer"
#     send-date: "yyyy-MM-dd"
#     send-time: "HH:mm:ss"
#     timezone: server or an IANA timezone such as America/New_York
#     repeat: none | daily | weekly | monthly | every:<duration>
#     catch-up-missed: true/false
#     notify-recipients: true/false
#     expire-after: none or a duration such as 30m, 12h, 7d
#     recipients:
#       mode: PLAYERS | ALL_WITH_MAILBOX_DATA | ALL_WITH_REGISTERED_MAILBOX | ONLINE_PLAYERS | PERMISSION
#
# Setting details:
#
# enabled:
#   true  = task can run.
#   false = task is ignored until enabled with config edit or /mba scheduledmail enable <id>.
#
# type:
#   PAPER_LETTER = sends a classic paper Letter.
#   BOOK_LETTER  = sends a written Book Letter.
#   PACKAGE      = sends a standard Package or COD Package if package.cod.enabled is true.
#   MONEY        = sends Vault/economy Money Mail.
#
# from:
#   Display name shown in the mail lore. Minecraft color codes using '&' are supported.
#
# send-date:
#   Optional first scheduled send date.
#   Format must be: yyyy-MM-dd
#   Example: "2026-08-01"
#   Required for repeat: none, weekly, monthly, and every:<duration>.
#   Also recommended for daily schedules when you want a specific start date.
#
# send-time:
#   Required scheduled send time.
#   Format must be: HH:mm:ss
#   Example: "18:00:00"
#   If send-time is set without send-date, the task repeats daily at that time.
#
# timezone:
#   server = use the server JVM timezone.
#   You may also use an IANA timezone, for example:
#   America/New_York, America/Los_Angeles, UTC, Europe/London
#
# repeat:
#   none       = one scheduled run only.
#   daily      = repeats once per day after the first send date/time.
#   weekly     = repeats once per week after the first send date/time.
#   monthly    = repeats once per month after the first send date/time.
#   every:<duration> = repeats by duration. Examples: every:6h, every:30m, every:7d
#   If send-date is omitted, only repeat: daily is valid. If repeat is omitted with only send-time, daily is used.
#
# catch-up-missed:
#   true  = if the server was offline at the scheduled time, send once when the plugin starts.
#   false = if the server missed the scheduled time, skip that missed run and wait for the next repeat.
#
# notify-recipients:
#   true  = recipients receive normal MailboxGUI notifications.
#   false = deliver silently without recipient notification messages/sounds.
#
# expire-after:
#   none = mail does not expire.
#   Duration examples: 30m, 12h, 3d
#   Expiration starts when mail is delivered, not when it is first scheduled.
#   Expired COD Packages can return to the Shared Admin Inbox if configured below.
#
# recipients.mode:
#   PLAYERS = send only to listed players/UUIDs under recipients.players.
#   ALL_WITH_MAILBOX_DATA = send to every player with MailboxGUI data.
#   ALL_WITH_REGISTERED_MAILBOX = send only to players with at least one registered physical mailbox.
#   ONLINE_PLAYERS = send only to online players who have MailboxGUI data when the task runs.
#   PERMISSION = send to online players with recipients.permission and MailboxGUI data.
#
# recipients.players:
#   Used only with mode: PLAYERS.
#   Accepts player names or UUIDs.
#
# recipients.permission:
#   Used only with mode: PERMISSION.
#
# recipients.online-only:
#   Used only with mode: PERMISSION.
#   Currently permission checks are online-player only.
#
# Package item syntax:
#   MATERIAL:amount
#   xp:amount
#   t:template-id:amount
#   template:template-id:amount
#
# COD package settings:
#   package.cod.enabled:
#     true/false. If true, the package becomes a COD Package.
#
#   package.cod.vault:
#     Vault/economy price. Use 0.0 for no Vault payment.
#
#   package.cod.item-currency:
#     Item-currency payment list using the same package item syntax above.
#
#   package.cod.return-to-admin-inbox.payments:
#     true = successful COD payments return to the Shared Admin Inbox.
#
#   package.cod.return-to-admin-inbox.declined-or-expired:
#     true = declined or expired COD Package contents return to the Shared Admin Inbox.
#
# Admin commands:
#   /mba scheduledmail reload
#   /mba scheduledmail list
#   /mba scheduledmail info <id>
#   /mba scheduledmail run <id>
#   /mba scheduledmail enable <id>
#   /mba scheduledmail disable <id>
#
# Permissions:
#   mailboxgui.admin.scheduledmail
#   mailboxgui.admin.scheduledmail.reload
#   mailboxgui.admin.scheduledmail.run
#   mailboxgui.admin.scheduledmail.manage
# ============================================================

scheduled-mail: {}

# ============================================================
# Commented Examples
# ============================================================
#
# To use an example, replace the empty line above:
# scheduled-mail: {}
#
# with an uncommented scheduled-mail section like the examples below.

# scheduled-mail:
#   event-paper-letter:
#     enabled: false
#     type: PAPER_LETTER
#     from: "&a&lServer"
#     send-date: "2026-08-01"
#     send-time: "18:00:00"
#     timezone: server
#     repeat: none
#     catch-up-missed: true
#     notify-recipients: true
#     expire-after: none
#     recipients:
#       mode: PLAYERS
#       players:
#         - Rismr1
#     letter:
#       message: "Thanks for joining the event!"
#
#   event-book-letter:
#     enabled: false
#     type: BOOK_LETTER
#     from: "&d&lEvent Team"
#     send-date: "2026-08-01"
#     send-time: "18:05:00"
#     timezone: America/New_York
#     repeat: none
#     catch-up-missed: true
#     notify-recipients: true
#     expire-after: 7d
#     recipients:
#       mode: ALL_WITH_REGISTERED_MAILBOX
#     letter:
#       title: "Event Info"
#       message: "Open your mailbox for this week's event details."
#
#   daily-time-only-letter:
#     enabled: false
#     type: PAPER_LETTER
#     from: "&a&lDaily Mail"
#     send-time: "09:00:00"
#     timezone: server
#     catch-up-missed: true
#     notify-recipients: true
#     expire-after: none
#     recipients:
#       mode: ALL_WITH_MAILBOX_DATA
#     letter:
#       message: "Here is today's daily server mail."
#
#   weekly-vip-money:
#     enabled: false
#     type: MONEY
#     from: "&6&lVIP Rewards"
#     send-date: "2026-08-02"
#     send-time: "12:00:00"
#     timezone: server
#     repeat: weekly
#     catch-up-missed: true
#     notify-recipients: true
#     expire-after: 14d
#     recipients:
#       mode: PERMISSION
#       permission: "mailboxgui.scheduled.vip"
#       online-only: true
#     money:
#       amount: 100.00
#
#   monthly-community-money:
#     enabled: false
#     type: MONEY
#     from: "&6&lCommunity Reward"
#     send-date: "2026-08-05"
#     send-time: "12:00:00"
#     timezone: server
#     repeat: monthly
#     catch-up-missed: true
#     notify-recipients: true
#     expire-after: 14d
#     recipients:
#       mode: ALL_WITH_REGISTERED_MAILBOX
#     money:
#       amount: 250.00
#
#   event-package:
#     enabled: false
#     type: PACKAGE
#     from: "&b&lEvent"
#     send-date: "2026-08-03"
#     send-time: "20:00:00"
#     timezone: server
#     repeat: none
#     catch-up-missed: true
#     notify-recipients: true
#     expire-after: 3d
#     recipients:
#       mode: ONLINE_PLAYERS
#     package:
#       contents:
#         - DIAMOND:3
#         - EMERALD:5
#         - xp:250
#         - t:rare-sword:1
#       cod:
#         enabled: false
#         vault: 0.0
#         item-currency: []
#         return-to-admin-inbox:
#           payments: false
#           declined-or-expired: false
#
#   event-cod-package:
#     enabled: false
#     type: PACKAGE
#     from: "&c&lAuction"
#     send-date: "2026-08-04"
#     send-time: "18:00:00"
#     timezone: server
#     repeat: none
#     catch-up-missed: true
#     notify-recipients: true
#     expire-after: 2d
#     recipients:
#       mode: PLAYERS
#       players:
#         - Rismr1
#     package:
#       contents:
#         - DIAMOND_BLOCK:1
#         - xp:500
#       cod:
#         enabled: true
#         vault: 250.00
#         item-currency:
#           - EMERALD:10
#         return-to-admin-inbox:
#           payments: true
#           declined-or-expired: true