Category: Modding Tools

Mail Framework Mod

Author: Digus

Created: 09 October 2017

1 / 2
2 / 2

Simplify the send of mail to the player, giving more control over when and what should be received.
Also giving more options not possible just editing the data files, like changing the text color and background of the letter at will.

Compatibility Warning:
This mod is incompatible with FeTK and Tool-Upgrade Delivery Service that depends on it. They are both broken and unsupported for more than a year, even some vanilla letter won’t work with it. (Adventure Guild letters)
So you should remove both before installing, or your custom mails won’t work properly.
Fortunately, there is an alternative to Tool-Upgrade Delivery Services, Mail Services Mod, that does the same and much more.


  1. Install the latest version of SMAPI.
  2. Unzip the MailFrameworkMod into /Stardew Valley/Mods.

Change Log:


  • New API Interface for SMAPI mods.
  • API method to load content pack folder from inside your SMAPI mod.
  • API method to load a letter.
  • API method to get a letter data.
  • API method to get the mail data string of a letter.
  • Fix mailbox not working properly when an error happened when closing the letter.
  • Better log on those errors.


  • More changes for compatibility with SMAPI 4
  • New attribute in the letter class to set the ITranslationHelper.
  • Content pack don’t need to change anything, but this change should avoid some rare i18n issues.
  • Mods that use MFM through code can update their implementation.


  • Make the mod compatible with SMAPI 4.
  • New property for Deepest mine level.
  • New property for current money.
  • New property for total money earned.
  • New console command to force mailbox to update to help modders debug.
  • Letter collection menu now show custom close button too.


  • Make the mod compatible with 1.5.5, without forcing SMAPI to convert it.
  • Should fix some problems with attachment not working on Unix OS.
  • New property for House Upgrade Level.


  • Fixed error when Expanded Preconditions Utility was not loaded.


  • New properties to support the use of Expanded Preconditions
  • New property to make it possible to add text besides the letter id to the player’s MailReceived list.


  • Support to DGA(Dynamic Game Assets) as attachments.


For Modders to use content pack:

  • There is a template inside the mod folder with commented instructions on what each property do.
  • All letter features but the conditions and callback are the same as coding with the framework.
  • Conditions are limited to the ones implemented, and the callback always set the letter id as received. If you need advanced conditions you still should code them. Or you can politely suggest me to add a condition to the content pack, if its something that makes sense, I might add it.
  • Here is the template as added in the mod file:



For Modder to use the API:

  • Copy IMailFrameworkModApi interface with the method you want to use from MFM interface.
  • Copy ILetter if one of the methods need it.
  • Methods:
    • RegisterContentPack – Use Helper.ContentPacks.CreateTemporary to load a folder from your mod that contain the mail.json and possible i18n folder for translations. Manifest is not needed since you can use that method parameter.
    • RegisterLetter – Fill an ILetter with the properties you need. A condition is also required to register an letter. A callback is advisable, to at least add the letter ID as received. See examples bellow, on the “For Modder to code with MFM dependency” session.
    • GetLetter– You will get the ILetter object for the letter ID.
    • GetMailDataString– You will get the mail data string for the letter ID. Mail data string is basically the translated text plus the translated title with a [#] separator.

For Modder to code with MFM dependency:

  • Reference the MailFrameworkMod.dll on your SMAPI project.
    • You register your Letter using MailDao.SaveLetter(Letter)
    • At the begin of each day the mod will check for Letters that have reached its condition for delivery and add them to the mailbox.
    • This Letters will be opened first when the player check the mailbox.
    • When the Letter is opened, it is removed from the mailbox.
    • The callback condition of the letter is them called.
    • At the end of the day Letter still on the mailbox will be removed, so they are not saved by the game.
  • You can think of this mod as an repository for your letters. It works best if you load all your letter when the game loads.


Spoiler:  Show

My Other Mods:

Related Stardew Valley mods

  • Bigger Backpack

    Bigger Backpack

    DescriptionBuy a bigger backpack at Pierre’s for only 50,000g! This backpack has 48 slots. ConfigNote: run Stardew Valley once with ... read more

  • Experience Bars

    Experience Bars

    Experience Bars adds experience bars for your skill levels, so you can see how far you are from leveling. Install UsePress X to ... read more

  • Skip Fishing Minigame

    Skip Fishing Minigame

    ACKNOWLEDGEMENTThank you to all the generous people who have supported this mod through donations and kind words, it’s very much ... read more

  • Portraiture


    Portraiture Version 1.11.0Support for HDP content packs.New Above Box Mode (active on default, can be deativated in the config and ... read more