mailer.gtw

~~LANG:FR@frman:mail~~


jMailer is a useful class for sending emails in controllers or business classes. It is based on the famous  [[http://phpmailer.codeworxtech.com|PHPMailer]] class (version 2.3).

Here are its features:
  * support **attachments**
  * **HTML** or **TEXT** email
  * **Multiple recipients**
  * **Multiple sending** channel (mail(), sendmail)
  * **SMTP authentication** support
  * Mail **templates** through jTpl

You can find many PHPMailer use cases over the web. So, we won't document all of the features above.

However, jMailer brings some additional features :

   * default configuration of jMailer is stored in the configuration file of the application
   * you can use jTpl templates to generate your emails content.
   * errors messages are localized in properties files (jLocale)
   * errors are raised and logged through exceptions.

===== Configuration file =====

jMailer options shall be edited in //var/config/defaultconfig.ini.php//. Look at the [mailer] section.

==== Configuration options ====


  * //webmasterEmail//: default sender email
  * //webmasterName//:  default sender name
  * //mailerType//: indicates how to send mails (default: "mail")
    * "mail": PHP mail function
    * "sendmail": use the server program 
    * "smtp": direct connection to an SMTP host
  * //hostname//: used in //Message-Id// and //Received// headers, and also as default //HELO// string. If empty, the value returned by SERVER_NAME is used or 'localhost.localdomain'.
  * //sendmailPath//: path to sendmail program

To send mails with a SMTP server:
  * //smtpHost//: SMTP hostname
  * //smtpPort//: SMTP port
  * //smtpSecure//: secured connection or not (possible value: "", "ssl", "tls")
  * //smtpHelo//: SMTP //Helo// message
  * //smtpAuth//: turn on/off SMTP authentication 
  * //smtpUsername//: SMTP login
  * //smtpPassword//: SMTP password
  * //smtpTimeout//: SMTP server time out

jMailer uses also general parameters //locale// and //charset// to setup the language and charset of emails.

Of course, you can change all of these parameters directly with properties and methods of jMailer class. See reference documentation.

===== Sending a simple mail =====

Sending a text email.

<code php>
  $mail = new jMailer();

  $mail->Subject = 'Subject';
  $mail->Body = 'Text content';

  $mail->AddAddress('recipientId@exemple.com' , 'recipient name');

  $mail->Send();
</code>


===== Sending a mail using a template =====

You can use the powerfull template engine of Jelix to send an email. You have to create a template in your module. In this template, you can use meta values to specify your email parameters.

Example, in modules/mymodule/templates/supermail.tpl
<code html>
    {meta Subject 'Super mail.'}
    {meta Priority 1}
    {meta From 'your name<your@email.com>'}
    {meta Sender 'your@email.com'}
    {meta ReplyTo array('your name<your@email.com>')}
    {meta to array($name.'<'.$email.'>')}
    {meta cc array('titi <titi@example.com>')}
    {meta bcc array('tutu <tutu@example.com>')}

    Hello {$name},
    Here is an email generated by jMailer and Jelix.
</code>

And in your PHP code :


<code php>
    $mail = new jMailer();
    $tpl = $mail->Tpl('mymodule~supermail');
    $tpl->assign('name', 'Mister Toto');
    $tpl->assign('email', 'toto@example.com');
    $mail->Send();
</code>


Notice that @@C@jMailer@@ will create template variables corresponding to some PHPMailer properties, so you can use it them anywhere in the template


<code html>
    {meta Subject 'Super mail.'}
    {meta Priority 1}
    {meta From 'your name<your@email.com>'}
    {meta Sender 'your@email.com'}
    {meta ReplyTo array('your name<your@email.com>')}
    {meta to array($name.'<'.$email.'>')}
    {meta cc array('titi <titi@example.com>', 'tutu <tutu@example.com>')}

    Hello {$name},
    Here is an email generated by jMailer and Jelix.
    This email is send to : 
    {foreach $cc as $person}
      - {$person[0]}
    {/foreach}
</code>

===== Sending an HTML email =====

You have to call the @@M@isHTML@@ method like in this example:

<code php>
$mail = new jMailer();
$mail->isHTML(true);
$mail->Body = "<p>My <strong>HTML</strong> email !</p>";
$mail->AddAddress('toto@example.com' , 'Toto');
$mail->Send();
</code>

If you use a HTML template, indicate @@true@@ to the method @@M@Tpl@@.

<code php>
$tpl = $mail->Tpl('mymodule~supermail', true);
</code>

===== Sending an attachment =====

You can add attachment easily in your email, by giving the path of the file stored somewhere on the hard drive. You can also indicate an other name for the file.

<code php>
$mail = new jMailer();
$mail->AddAttachment(jApp::varPath('original_filename.pdf'), 'new_filename.pdf');
...
$mail->Send();
</code>

===== Advanced features =====

Since jMailer inherits from the PHPmailer class, read [[http://phpmailer.worxware.com/index.php?pg=methods|the documentation of PHPMailer]] to know more about its features.