Tutorial: Sending a Letter (Mail Framework Mod)

PLEASE NOTE: Mail Framework Mod is obsolete in favor of Content Patcher. Backwards compatibility is maintained, but for new mods, CP should be used.

It's super easy to send a letter in Stardew Valley, thanks to frameworks like Mail Framework Mod.

Note: This tutorial assumes that you are already familiar with some modding basics, like making sure to have SMAPI installed and knowing how a manifest works.

You can also use Content Patcher to send mail.

Future infobox info: PebbleQuest, May 22 2021

Finding Examples

Examples are the key to understanding any mod or coding project. Fortunately, mail is used in a lot of mods so there are lots of examples out there to look at.

Seed Samples

Creating a Manifest

Creating a manifest is easy. See the official wiki for more help. Here is an example for our project.

{
  "Name": "Your Project Name",
  "Author": "your name",
  "Version": "1.0.0",
  "Description": "One or two sentences about the mod.",
  "UniqueID": "YourName.YourProjectName",
  "UpdateKeys": [],
  "ContentPackFor": {
    "UniqueID": "DIGUS.MailFrameworkMod"
  }
}

Using Mail Framework Mod

1. Inside your mod folder, in the same place you put the manifest.json, create a new file and call it mail.json.
2. We will be creating a very basic letter to start. In your mail.json, add the following code.

   [
       {
           "Id": "MyMail",
           "GroupID": null,
           "Text": "Hi @, this is a letter!^^-Lewis",
           "Date": "1 spring Y1"
       }]
   

3. Each piece of mail created using MFM needs to have an ID. A group ID is optional, and letters with the same group ID will never be sent on the same day. As mentioned in the Content Patcher section of this tutorial, @ indicates the player's name, and ^ is a line break.
4. The date variable is the first day that the letter becomes eligible to receive. So, if you do not want the letter to be received before the second year, you could put "1 spring Y2" to assure that the player does not receive it prematurely. You can also add variables such as specific days of the month that the letter is able to be received, and a specific season and weather as well.
5. Let's say we want to add the condition that the player will only receive this letter if they are at 2 hearts or above with Lewis. We would use the following code:

   [
       {
           "Id": "MyMail",
           "GroupId": null,
           "Text": "Hi @, this is a letter!^^-Lewis",
           "Date": "1 spring Y1",
           "FriendshipConditions": [
               {
                   "NpcName": "Lewis",
                   "FriendshipLevel": 2
               }]
       }]
   

6. You can also add skill conditions, stats conditions, and collections conditions, as well as conditions on whether or not the player has seen a certain event, or if they have certain buildings on their farm built.
7. Finally, let's add a gift to the letter! Lewis will give the player a chocolate cake. We'll use this code.

   [
       {
           "Id": "MyMail",
           "GroupId": null,
           "Text": "Hi @, this is a letter!^^-Lewis",
           "Date": "1 spring Y1",
           "Attachments": [
               {
                   "Type": "Object",
                   "Name": null,
                   "Index": 220,
                   "Stack": 1
               }]
           "FriendshipConditions": [
               {
                   "NpcName": "Lewis",
                   "FriendshipLevel": 2
               }]
       }]
   

8. You can add Json Assets items as well, by putting the name of the object in the name variable, as opposed to it's index number. You can also attach craftable items, recipes, and equipment if you so desire! And to send more than one of an item, simply add the number you want to the stack variable.
9. There are many other conditions you can add, and going over all of them would take a while. This tutorial simply covers the basics. The mod author, Digus, has written instructions on the mod page for content pack creators that goes more in-depth on what each variable can do. See here. (It is in the mod description under the subtitle "For modders to use content pack".)

What's Next?

As with all the tutorials here, this is just scratching the surface. There are so many possibilities for things that can be done with mail! Looking more into both Content Patcher and Mail Framework Mod can help you to do more with the mail you create, or perhaps branch out into other areas of modding!

Interested in writing a tutorial for this wiki? We'd love to have you! No qualifications are needed. Just create a new page, call it "Tutorial: Doing a Thing" (name as appropriate), and start sharing your knowledge.