In the current Mailet API there are many deprecated classes and methods marked with the @Deprecated annotation and some also with the @deprecated javadoc tag. However, very few of these have any related documentation on what to use instead, or at least why it is deprecated if there is no alternative. As it is, someone using or implementing the API has no idea what the migration path should be to avoid using these deprecated APIs which may disappear in the future.
Please document all deprecations, most importantly with what is the recommended way to migrate away from them.
This may be true for other modules as well, but certainly is in this central API.