Section: jMailer: sending mails
| « jHttp: http requests | ^ Class utilities | jWiki: generating contents from wiki contents » |
− Table of content
jMailer is a useful class for sending emails in controllers or business classes. It is based on the famous 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.
$mail = new jMailer();
$mail->Subject = 'Subject';
$mail->Body = 'Text content';
$mail->AddAddress('recipientId@exemple.com' , 'recipient name');
$mail->Send();
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
{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.
And in your PHP code :
$mail = new jMailer();
$tpl = $mail->Tpl('mymodule~supermail');
$tpl->assign('name', 'Mister Toto');
$tpl->assign('email', 'toto@example.com');
$mail->Send();
Notice that jMailer will create template variables corresponding to some PHPMailer properties, so you can use it them anywhere in the template
{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}
Sending an HTML email ¶
You have to call the isHTML method like in this example:
$mail = new jMailer();
$mail->isHTML(true);
$mail->Body = "<p>My <strong>HTML</strong> email !</p>";
$mail->AddAddress('toto@example.com' , 'Toto');
$mail->Send();
If you use a HTML template, indicate true to the method Tpl.
$tpl = $mail->Tpl('mymodule~supermail', true);
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.
$mail = new jMailer();
$mail->AddAttachment(JELIX_APP_VAR_PATH.'original_filename.pdf', 'new_filename.pdf');
...
$mail->Send();
Advanced features ¶
Since jMailer inherits from the PHPmailer class, read the documentation of PHPMailer to know more about its features.
