> For the complete documentation index, see [llms.txt](https://docs.cozycrafters.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cozycrafters.net/plugin-docs/cozymail.md).

# CozyMail

### What It Does

CozyMail is an in-game mail plugin for Cozy Crafters SMP.

It lets players receive and read mail through a shared mailbox system. Mail can come from other players, server admins, or Cozy Chronicles issues. Letters open in Minecraft's book reader.

### Main Features

| Feature                | Description                                                                                                     |
| ---------------------- | --------------------------------------------------------------------------------------------------------------- |
| Player mail            | Players can send written-book letters to other players.                                                         |
| Inbox                  | `/mail` opens the player's inbox. If the GUI is disabled, the plugin falls back to a text inbox.                |
| Book reading           | Letters open as readable books and are marked read when opened.                                                 |
| Admin announcements    | Admins can send a written book as server mail to selected recipient groups.                                     |
| Cozy Chronicles        | Admins can publish written-book issues that are delivered to active players and kept in a public archive.       |
| Notifications          | Players can receive login unread-mail banners, chat notifications for new mail, and sound cues if enabled.      |
| Do Not Disturb         | Players can toggle DND for player-to-player letters if the feature is enabled.                                  |
| Inbox tools            | The inbox can support search, mark-all-read, reply, and right-click deletion when enabled.                      |
| Text fallbacks         | The inbox and Chronicles archive have text modes when GUI features are disabled or when text mode is requested. |
| PlaceholderAPI support | If PlaceholderAPI is installed, CozyMail registers `cozymail` placeholders.                                     |
| CozyTowns support      | If CozyTowns is installed and compatible, admin mail can target `town:<name>` scopes.                           |

### Basic Admin Workflow

1. Give normal players `cozymail.use`.
2. Give trusted staff or admins `cozymail.admin`.
3. Configure feature toggles in `config.yml` as needed.
4. Use `/cozymail reload` after changing the config or messages.
5. For admin announcements, write and sign a book, hold it, then run `/mailadmin send <scope> <subject>`.
6. Review the confirmation prompt, then run `/mailadmin confirm` or `/mailadmin cancel`.
7. For Cozy Chronicles, write and sign a book, hold it, then run `/chronicles publish`.
8. Review the confirmation prompt, then run `/chronicles confirm` or `/chronicles cancel`.

### Notes

* CozyMail commands are player-focused. `/mail`, `/mailadmin`, and `/chronicles` require an in-game player.
* `/cozymail reload` can be run by any command sender with `cozymail.admin`.
* Player-to-player mail uses signed books. `/mail send <player>` gives the sender a bound book when they are not already holding a written book.
* Holding a signed book and running `/mail send <player>` is supported when legacy held-book sending is enabled.
* Player letters have a configurable send cooldown. The default is 120 seconds.
* Recipients can have a configurable maximum unread mailbox size. The default is 100 unread letters.
* Cozy Chronicles publishes to players seen within the configured active window. The default is 30 days.
* Admin announcement and Chronicles publish confirmations expire after the configured timeout. The default is 30 seconds.
* No item attachments, money attachments, Vault support, PlayerPoints support, or Oraxen GUI items were confirmed in the source.

### Common Use Cases

| Use Case                                  | Command                                   |
| ----------------------------------------- | ----------------------------------------- |
| Open a player inbox                       | `/mail`                                   |
| Send a player letter                      | `/mail send <player>`                     |
| Read a specific letter from text output   | `/mail read <id>`                         |
| Send server mail to all known players     | `/mailadmin send all <subject>`           |
| Send server mail to online players        | `/mailadmin send online <subject>`        |
| Send server mail to one player            | `/mailadmin send player:<name> <subject>` |
| Send server mail to a town                | `/mailadmin send town:<name> <subject>`   |
| Send server mail to recently seen players | `/mailadmin send new:<days> <subject>`    |
| Open the Chronicles archive               | `/chronicles archive`                     |
| Publish a Chronicles issue                | `/chronicles publish`                     |
| Reload CozyMail config and messages       | `/cozymail reload`                        |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cozycrafters.net/plugin-docs/cozymail.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.