Please provide an API documentation...

Ok, you directed me to mail_edit_user.inc, which demonstrates some of the features.

Here are some questions that are still open:

1. What's the meaning of the options parameter in hook_mail_edit_tokens_list()? How can it be used? I would like to chain calls to related modules so that they can add more tokens. Can I use the options parameter for passing my tokens list on to another module's hook_mail_edit_tokens_list()? How should I do that to avoid conflicts down the road?
2. The second parameter to hook_mail_edit_text($mailkey, $langcode) should be called $language.
3. t('description') should be t('Description').
4. How can we reset your registry? Why not just use a cache?
5. The order on admin/build/mail-edit seems to be random (or database order) — not very convenient as the list grows...
6. It would be nice if you could pass the description through filter_xss() when putting it into the textfield to allow some highlighting (%variables) in the default descriptions.
7. You should not have an index on column id.
8. It would be nice if the code were a bit more modular; for example a function that loads a record from {mail_edit} or another function that turns $tokens into a <dl> would be handy.

No, we haven't made any progress with this issue.

What do you need to know beyond what you see in mail_edit_user.inc?