In this post we'll explain how to make use of token module's API in a custom module. Token is a very handy solution that can replace chunks of specially formatted text with dynamically loaded values.

Let's say we want to achieve the following:

1) We have a content type called Feature that contains an image field, called field_image.

2) A user posts a Feature content to our site.

3) We want to send a content post confirmation email to the user and want to include the name of the image file they uploaded.

Of course, this functionality can be achieved in other ways, we'll show you how to do this using Token API and a little custom module.

So our first step is to create our tokens, these chunks will be programatically replaced with the dynamic values on the fly. So here's how we'll do it:

We'll name this file custom_token.inc and include it in our custom.module file. In our custom module we'll create an administrator page for our module to create a text field where we can insert the text we want to email the user, together with our newly created token. We won't go into detail about how to create an admin page with a form on it and how to use drupal's email functions, we'll explain how to make use of Token API in our module.
To show the available tokens, we'll use a function like this in our form:

This way we can view all tokens that are available and (if we didn't forget to include our custom_token.inc file) we'll see our newly created token, [filename] as well. So we're able to access and use it in the emails. To actually send the emails when a Feature content is posted, the best to use is a custom_nodeapi function and fire hook_mail when the content is inserted. A very important thing is to use this format in the email body: