Grasscutter-MeaMailPlus/README.md

![Group 148.jpg](https://s2.loli.net/2022/05/03/5ZPG2neTlrMW6Az.jpg)
# MeaMailPlus - Grasscutter Mail enhancements
MeaMailPlus is a plugin of [Grasscutter](https://github.com/Grasscutters/Grasscutter), you can use this plugin to send your mail conveniently.

English | 简体中文 (正在写)

## 💡Feature

- [x] **Birthday Mail**  - Send birthday emails to players on their birthdays.
- [X] **Daily Bonus**  - Players will receive rewards when they join the server.
- [X] **Newbie Gift Mail**  - Players will receive rewards when they first joined.
- [X] **Scheduled Mail push**  - You can limit the level threshold of players to receive the mail.
- [X] **Command support**  - Support sending Mails by command.
- [ ] **RESTful API**  - Send Mail via third-party API.
- [ ] **MORE**  - Comming soon...

## 🍗Setup
### Install
1. [Download Plugin Jar](https://github.com/Coooookies/Grasscutter-MeaMailPlus/releases)
2. Put plugins into `plugins` folder of your grasscutter server.
3. Start your server, then the plugin will create `MeaMailPlus` folder in your server plugin folder.
```
Root
│   lib
│   keys
│   resources
│   ...
└───plugins
    │   ...
    └───MeaMailPlus
        │   template       // template files
        └───config.json    // plugin config file
```

### How to use?

The plugin will create a `MeaMailPlus` folder in your server plugin folder, include `template` folder and `config.json` file.
#### Config file
The config file is a `JSON` file, you can edit it to set the plugin's behavior.
Run command `/meamail reload` in console to reload the config.
```
{
  "updateTime": [4, 0, 0],         // set the server's start time for send mail of the day, default is 04:00:00(24 hours system)
  "initialMail": [ 1001 ],         // set the initial mail id, you can set multiple mail ids like [1001, 1002, 1003]
  "birthDayMail": [ 1004 ],        // set the birthday mail id, you can set multiple mail too!
  
  "dailySignInMail": [             // players can only receive once a day, and will not send if they are not online.
    {
      "templateId": 1002,          // set the template id for daily sign in mail.
      "minLevel": 0                // you can limit the level(0-60) threshold of players to receive the mail.
    },
    {
      "templateId": 1003,          // multiple mail...
      "minLevel": 25                
    },
    {
      "templateId": 1004,          // multiple mail...
      "minLevel": 55                
    }
  ],
  
  "dailyRepetitionMail": [         // send a timed email collectively
    {
      "onlineOnly": false,         // whether the player needs to be online to receive mail
      "triggerTime": [12, 0, 0],   // 12:00:00
      "templateId": 1003,          // templateId
      "minLevel": 0                // you can limit the level(0-60) threshold of players to receive the mail.
    },
    {                              // multiple mail...
      "onlineOnly": true,
      "triggerTime": [6, 0, 0],    // 16:00:00
      "templateId": 1003,
      "minLevel": 0
    },
    {                              // multiple mail...
      "onlineOnly": true,
      "triggerTime": [0, 0, 0],    // 24:00:00
      "templateId": 1003,
      "minLevel": 0
    }
  ]
}
```
#### Template file
You can make multiple template files in `template` folder, only supports `JSON`.
like this: 
TemplateExample.json
```
{
  "templateId": 1001,              // Your template id         
  "title": "Mail title",           // Your Mail title
  "sender": "KiritaniIwako",       // Your sender name, you can set "Server"
  "expireTime": 0,                 // Your mail expire time, will be explained in detail later.
  "remainTime": 2592000,           // Your mail remain time, if you have set the remainTime, the expireTime will not take effect.
  "importance": 0,                 // Your mail importance, 0 is normal, 1 is star
  "body": {                        // Your mail content, will be explained in detail later.
    "content": "Mail content",
    "items": [
      {
        "id": 223,                 // item id
        "count": 1,                // amount
        "level": 1                 // item level(1-90?)
      }
    ]
  }
}
```
1. How to set the mail `expireTime` or `remainTime`?
- [Timestamp converter](https://www.epochconverter.com/)
```
{
  "expireTime": 1651571451,
  // use 10 digits timestamp, like this: 
  // you can use convert tool to convert the timestamp to 10 digits timestamp, 
  // https://www.epochconverter.com/
  
  "remainTime": 2592000
  // time in second
  // 2592000 is the seconds of 30 days: 
  // 2592000 = (d) * 24(h) * 60(m) * 60(s)
  // if you are not sure, you can use two 10 digits timestamp subtraction:
  // 2592000 = 1651568400 (2022-5-3 9:00:00GMT) - 1648976400 (2022-4-3 9:00:00GMT)
}
```

2. How to set the mail `body/content`?
```
{
  "body": {
    "content": "Mail content",
    // you can set the content of the mail, 
    // you can use the variable: 
    // `{playerName}`: (Testing) player name
    // `\r\n`: line feed
    // you can use link to open Webview in-game & Browser:
    // `<type=\"browser\" text=\"Discord\" href=\"https://discord.gg/T5vZU6UyeG\"/>`: open a Browser, tag name is "Discord".
    // `<type=\"webview\" text=\"Discord\" href=\"https://discord.gg/T5vZU6UyeG\"/>`: open a Browser, tag name is "Discord".
    
    "items": [                     // items in the mail, if you set `[]`, no item will be sent
      {
        "id": 223,
        "count": 1,
        "level": 1
      }
      {
        "id": 223,                 // item id
        "count": 1,                // amount
        "level": 1                 // item level(1-90?)
      },
      {
        "id": 224,                 // Multiple items...
        "count": 1,
        "level": 1
      },
      {
        "id": 202,                 // Multiple items...
        "count": 10000000,
        "level": 1
      }
    ]
  }
}
```

Hyperlinks in the mail content:
```
<type=\"browser\" text=\"Discord\" href=\"https://discord.gg/T5vZU6UyeG\"/>
<type=\"webview\" text=\"Discord\" href=\"https://discord.gg/T5vZU6UyeG\"/>
```
### Command & Permission
Command:
```
Send Mail:
    /meamail send <templateId> <uid>
    /meamail sendall <templateId> <minLevel>
    /meamail sendallonline <templateId> <minLevel>
Other:
    /meamail reload
    /meamail help
```

Permission:
```
meo.mail | Control plugin functions
```