1. Create the Email Template
The content for emails is stored in the dev/email folder of the application which will send the email. For example, if you look in the applications/core/dev/email folder (you will need to be in developer mode to see that folder) you will see all the emails the core application sends.
All emails sent from the IPS Community Suite are sent in two formats: HTML (for most email clients) and plain text (for older email clients or users who specifically do not want to see HTML emails). For each type of email that can be sent, there are two files: key.phtml (which contains the HTML version) and key.txt (which contains the plaintext version).
Note that both types are sent to the user, and their individual email client will determine the most appropriate one to display.
To send your own type of email, you will therefore need to create both of these. They key you use can be anything so long as it is unique. The first line of both files should be a tag like this:
<ips:template parameters="$parameter1, $parameter2, $email" />
Later (in step 3) when you call the code to send your email you can pass whatever parameters you want which can then be used in your templates. A final parameter, $email, will also always be passed which contains the \IPS\Email object you're working with.
Within the templates, you can include template logic and most template tags, however be careful: the email you're sending will probably be to a different user to who is logged in when the email is sent, so do not use anything which is dependent on the currently logged in member. most importantly, do not use {lang=""} template tag (which is always based on the currently logged in member). Instead, you can access $email->language which is an \IPS\Lang object for the correct language of the recipient.
There's also a special tag, {dir}, that you can use in your template. This is either ltr or rtl depending on the recipient's language, and is used (most notably with <table>s) to ensure the email layout is appropriate for the language. Usage example:
<td dir='{dir}' valign='middle' align='center' style="...">
When creating your HTML template, be aware that email clients use very different standards to browsers and many normal techniques cannot be used. We recommend you use a template from one of the IPS applications as your base, and you may want to use a tool such as Litmus.
When creating your plaintext template, be aware that you cannot use any HTML tags, and whitespace is significant; that is, any whitespace in your template will be displayed in the email.
2. Add Subject Language Strings
The system will automatically look for a language string with the key mailsub__<app>_<key> to use as the subject, so add that to your dev/lang.php file. Note that you can use the parameters you pass to the template - for example, you will notice in applications/core/dev/lang.php:
'mailsub__core_notification_new_likes' => '{$member->name|raw} liked your post',
3. Send the Email
The actual code to send the email is very simple:
\IPS\Email::buildFromTemplate( 'app', 'key', $params )->send( $member );
The send() method can be passed either an \IPS\Member object (this is best as the system will automatically customize the email for the user, including choosing the correct language) or an email address as a string (which you should only do if you need to send an email to unregistered users) or an array of either of these to send to multiple recipients. You can also pass second and third parameters for users to CC and BCC respectively.
If you want to customize the content of the message depending on the member you can include variables in your template with the format *|key|* and then send like so:
Template:
<td> *|some_key|*<br> </td>
PHP:
\IPS\Email::buildFromTemplate( 'app', 'key', $params, TRUE )->mergeAndSend( array( 'user1@example.com' => array( 'some_key' => 'value for user 1', ), 'user2@example.com' => array( 'some_key' => 'value for user 2', ) ) );
Report Document